# 编辑器与资产 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`

---

## 3. 前端接入

统一入口：

- `src/editor/shared/editorApiClient.ts`

已切换的编辑器链路：

- 角色预设覆盖保存
- 敌人预设覆盖保存
- 场景预设覆盖保存
- 场景角色覆盖保存
- NPC 形象覆盖与布局配置保存
- 物品目录读取与物品覆盖保存
- 状态行为覆盖保存
- 角色主形象生成、发布与任务查询
- 角色动作生成、导入、发布、模板读取与任务查询

---

## 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. 旧工具链隔离状态

自 `2026-04-19` 起，`scripts/dev-server/**` 中的旧 Vite 本地插件实现代码已经从仓库删除，也不再作为当前开发入口使用。

当前保留状态：

- `scripts/dev-server/` 目录只保留迁移说明 README。
- 旧链路的历史背景由 `docs/audits/engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md` 等审计文档承接。

新增编辑器或资产能力时，应优先写入：

- `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 本地插件代码已删除，不再保留并行实现。