fix: recover empty database migrations and persist Docker icons

docs/admin-accounts.md

@@ -23,4 +23,4 @@ ADMIN_PASSWORD=admin
 
 运行隔离回归：在仓库根目录执行 `pnpm --filter @worthpath/api test:isolated`。测试库名使用随机 `wp_test_` 前缀，API 使用随机本机端口；完成或失败后清理自己创建的服务和数据库。管理员测试只在该隔离流程中运行，避免修改真实管理员。
 
-已有迁移目录 `005_account_icons`、`006_navigation_transfers`、`007_notes_display` 排在初始迁移之前，因此原有 `migrate deploy` 从空库初始化会失败。本次未重命名历史迁移。隔离测试用当前 Prisma 模型建立临时库，再移除本次字段并执行新增 SQL 来验证增量迁移；现有库迁移正常。全新部署仍需要单独修复历史迁移顺序。
+历史 `005_account_icons`、`006_navigation_transfers`、`007_notes_display` 排在初始迁移之前的问题已由项目迁移入口修复，保留所有历史目录名称和 SQL 校验值。隔离测试通过正式迁移入口建立空库，再运行业务回归；不再使用 `db push` 或手动改列来代替迁移。空库失败恢复与部署命令见 [数据库迁移](database-migrations.md)。

docs/architecture.md

@@ -32,7 +32,7 @@ Revision 保存按业务日期生效的绝对金额，每次金额更新新增
 
 ## 账户图标模块
 
-Icon 存储 name、ownerId、shared、SHA-256 和规范静态 PNG 的 MediumBlob，不存储 source；内置图标来源保留在资源清单中。Position.iconId 外键 SetNull，多个账户共享同一图片。所有图标接口使用已验证身份，读取/检索/赋值均限定 shared=true 或 ownerId=当前用户，响应不返回 ownerId。个人上传默认私有；共享发布须中文名称和明确公开确认。拒绝 SVG、动图、损坏图片、超限像素/文件，重编码移除元数据。内置图标固定 ID 追加初始化；在线请求不会发送用户财务数据。
+Icon 存储 name、ownerId、shared、SHA-256 和规范静态 PNG 的 MediumBlob，不存储 source；内置图标来源保留在资源清单中。配置 `ICON_STORAGE_DIR` 后，上传及备份恢复同时将图片按 SHA-256 文件名持久化，启动时分批补齐旧图标，读取时校验文件并从数据库修复缺失或损坏内容。Docker 将 `/app/data/icons` 绑定到宿主机 `/opt/worthpath/data/icons`，数据库内容继续用于兼容与自包含 ZIP 备份。内容文件可以被多条图标记录共用，删除数据库记录不自动删除文件。Position.iconId 外键 SetNull，多个账户共享同一图片。所有图标接口使用已验证身份，读取/检索/赋值均限定 shared=true 或 ownerId=当前用户，响应不返回 ownerId。个人上传默认私有；共享发布须中文名称和明确公开确认。拒绝 SVG、动图、损坏图片、超限像素/文件，重编码移除元数据。内置图标固定 ID 追加初始化；在线请求不会发送用户财务数据。
 
 当前备份要求完整 icons 数组，ZIP v9 将图标内容放入 icons.json；内容校验和解码在导入事务前完成，图标在事务内以当前用户私有范围重建，账户关联重映射。清空删除私有图标，公开共享图标不因发布者清空而消失。用户删除时图标 ownerId SetNull，不影响他人已引用的公共图标。
 

docs/database-migrations.md

@@ -0,0 +1,29 @@
+# 数据库迁移
+
+在仓库根目录执行：
+
+```sh
+pnpm db:migrate
+```
+
+Docker 部署需要重新构建镜像以包含修复后的迁移脚本，再执行迁移：
+
+```sh
+docker compose build app
+docker compose run --rm app node scripts/database.cjs deploy
+docker compose up -d app
+```
+
+请使用以上项目入口。历史目录 `005_account_icons`、`006_navigation_transfers`、`007_notes_display` 排在 `202610010001_initial` 前面，直接运行 Prisma `migrate deploy` 会在空库首先创建 Icon，因 User 表尚不存在而出现 MySQL 1824。项目入口先通过 Prisma 部署四个初始迁移，再部署完整迁移集合。历史 SQL 与目录名称保持原样，已有数据库的记录和校验值不变；重复运行只应用尚未执行的迁移。
+
+如果已经遇到该失败，更新代码或镜像后重新运行项目入口即可。脚本仅在确认没有业务表、没有成功迁移、仅有 `005_account_icons` 的 1824 失败且执行步数为零时，通过 Prisma `migrate resolve --rolled-back 005_account_icons` 标记该次失败，再按正确顺序迁移。不会执行 reset、db push 或删除业务表。
+
+其他失败、部分执行或没有迁移记录的已有表会拒绝自动恢复，需要根据实际数据库状态手动处理。不要直接把失败记录标记为 applied，也不要对有数据的库执行 reset。Prisma 官方说明见 [生产迁移故障恢复](https://www.prisma.io/docs/orm/v6/prisma-migrate/workflows/patching-and-hotfixing)。
+
+隔离回归入口：
+
+```sh
+pnpm --filter @worthpath/api test:isolated
+```
+
+测试只创建和清理随机 `wp_test_` 库，覆盖真实空库初始化、重现 005 失败并恢复、迁移校验值一致、重复执行保留数据和历史、拒绝未跟踪的已有表，以及完整业务回归。