Genarrative/docs/technical/EDITOR_ASSET_API_MIGRATION_2026-04-08.md

编辑器与资产 API 迁移清单（2026-04-08）

1. 任务定位

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