1

docs/technical/EDITOR_ASSET_API_MIGRATION_2026-04-08.md

@@ -0,0 +1,106 @@
+# 编辑器与资产 API 迁移清单（2026-04-08）
+
+## 1. 任务定位
+
+对应 [EXPRESS_BACKEND_PARALLEL_WORKSTREAM_PLAN_2026-04-08.md](../planning/EXPRESS_BACKEND_PARALLEL_WORKSTREAM_PLAN_2026-04-08.md) 中的任务 8：编辑器 API 归口与工具链隔离。
+
+本轮目标是把编辑器写盘、资产生成、生成任务查询从旧的 Vite 本地 API 插件里收口到 `server-node`，并把前端编辑器组件改成通过统一 SDK 访问。
+
+---
+
+## 2. 新命名空间
+
+编辑器写盘与读取：
+
+- `GET /api/editor/catalog/items`
+- `GET /api/editor/json/:resourceId`
+- `POST /api/editor/json/:resourceId`
+
+资产生成与任务查询：
+
+- `POST /api/assets/character-visual/generate`
+- `POST /api/assets/character-visual/publish`
+- `GET /api/assets/character-visual/jobs/:taskId`
+- `POST /api/assets/character-animation/generate`
+- `POST /api/assets/character-animation/publish`
+- `GET /api/assets/character-animation/jobs/:taskId`
+- `POST /api/assets/character-animation/import-video`
+- `GET /api/assets/character-animation/templates`
+- `POST /api/assets/qwen-sprite/master`
+- `POST /api/assets/qwen-sprite/sheet`
+- `POST /api/assets/qwen-sprite/frame-repair`
+- `POST /api/assets/qwen-sprite/save`
+
+---
+
+## 3. 前端接入
+
+统一入口：
+
+- `src/editor/shared/editorApiClient.ts`
+
+已切换的编辑器链路：
+
+- 角色预设覆盖保存
+- 敌人预设覆盖保存
+- 场景预设覆盖保存
+- 场景角色覆盖保存
+- NPC 形象覆盖与布局配置保存
+- 物品目录读取与物品覆盖保存
+- 状态行为覆盖保存
+- 角色主形象生成、发布与任务查询
+- 角色动作生成、导入、发布、模板读取与任务查询
+- Qwen 精灵主图、精灵表、修帧与资产保存
+
+---
+
+## 4. 权限与环境边界
+
+`server-node` 通过环境变量控制工具接口：
+
+- `EDITOR_API_ENABLED`：控制 `/api/editor/*`。
+- `ASSETS_API_ENABLED`：控制 `/api/assets/*`。
+
+默认策略：
+
+- 非 `production` 环境默认开启。
+- `production` 环境默认关闭。
+- `ASSETS_API_ENABLED` 未设置时跟随 `EDITOR_API_ENABLED`。
+
+这批接口会读写 `src/data/*.json` 与 `public/generated-*`，不应作为正式运行时 API 使用。
+
+---
+
+## 5. 旧工具链隔离状态
+
+`scripts/dev-server/**` 中的旧 Vite 本地插件已经不再由 `vite.config.ts` 注入，也不再作为当前开发入口使用。
+
+旧文件保留用途：
+
+- 作为历史迁移参考。
+- 对照旧 DashScope 调用与文件写入逻辑。
+
+新增编辑器或资产能力时，应优先写入：
+
+- `server-node/src/modules/editor/**`
+- `server-node/src/modules/assets/**`
+- `src/editor/shared/editorApiClient.ts`
+
+不要再新增旧式散落接口：
+
+- `/api/item-overrides`
+- `/api/npc-visual-overrides`
+- `/api/character-overrides`
+- `/api/character-visual/*`
+- `/api/animation/*`
+- `/api/qwen-sprite/*`
+
+---
+
+## 6. 当前验收状态
+
+- `/api/editor/*` 与 `/api/assets/*` 命名空间已落地。
+- 前端编辑器组件已通过统一 SDK 或资源 ID 访问编辑器 API。
+- Vite 已代理 `/api/editor` 与 `/api/assets` 到 Node 后端。
+- 写接口已经有环境门禁。
+- 旧 Vite 本地插件不再是当前工具链入口。