fix(chess-skin-admin): cascade file cleanup on delete and replace

[joke-lx]

背景

chess-skin-admin 的两个清理路径都漏删文件:

• deleteSkin: 只移 KV index,文件资源保留 —— 与"删除"语义不一致,且长期累积孤儿文件
• replacePiece: 每次换皮都上传新图 + 改 KV,但旧文件从不清理,storage 持续增长

改动

deleteSkin(composable)

改为文件先删,KV 后移;任一失败中止(KV 不动):

1. 抓出目标 skin meta,收集全部 fileIds(pieces + boardBackground,空 fileId 跳过)
2. 并发 Promise.allSettled 调用 fileV1Service.delete({fileId, groupId:190})
3. 任一 rejected → 收集失败清单,把消息挂到 error.value 并抛错;KV index 一字不动
4. 全部成功 → 才把该 skin 从 KV index 移除并持久化

boardBackground 类型是 unknown,仅在长得像 {fileId:string} 时尝试删,避免误删。

返回类型从 Promise<void> 变为 Promise<DeleteSkinResult>(pieceFilesDeleted, backgroundDeleted),供 UI 显示文件清理计数。

replacePiece(composable)

新增 best-effort 清理被替换的旧 fileId:

• 上传前先抓出旧 piece 的 fileId
• 上传新图 → 持久化 KV(失败时旧文件不动)
• KV 持久化成功后 → 尽力 DELETE 旧 fileId,失败只挂 orphanedFailed,不影响主操作

设计取舍:

• 不先删旧:上传失败 → 旧文件消失,KV 还引用 → 断图
• 不写 KV 前删旧:同上
• 旧文件清失败不回滚:换皮已生效,孤儿留待日后清理

返回类型从 Promise<ChessSkinMeta> 变为 Promise<ReplacePieceResult>(meta, orphanedCleaned, orphanedFailed)。

UI 文案更新

位置	旧	新
删除 modal 描述	"文件资源保留"	"联动删除该皮肤对应的全部棋子图文件(约 12 张,含 boardBackground)。任一文件删除失败将中止操作,KV index 不变"
删除按钮 tooltip	"(文件保留)"	"+ 联动删除文件"
删除成功 status	"已从 chess_skin:index 移除"	"已从 chess_skin:index 移除(N 个文件一并删除)"
替换成功 status	"已替换并发布"	三种分支:清理成功/清理失败/无旧图
ReplaceTab help	"原文件保留可回滚"	"被替换的旧文件会一并清理(清理失败仅警告)"

验证

• husky pre-commit lint-staged 通过(ESLint 0 warnings)
• Node ≥22 环境下 pnpm lint + pnpm --filter @style-library/showcase build 兜底验证(本机 Node 16 未跑)

已知遗留

本轮改动只清未来新增的孤儿。已有的历史孤儿(改动前留下的旧 fileId 引用)未清理。可加一个 cleanOrphans() 工具函数遍历 index.value 然后用 fileV1Service.list 按 tag 反查并删除,但属于独立功能,留作下一轮。

🤖 Generated with Claude Code