pixelheros/production/qa/evidence/2026-06-20-config-editor-plan-a.md

# 配置编辑器 Plan A — 验证证据

- **Plan**: `docs/superpowers/plans/2026-06-20-config-editor-foundation.md`
- **Branch**: `card0614`
- **Date**: 2026-06-21
- **Tasks implemented**: 1–13 (full plan)

---

## 自动化测试（BLOCKING 门槛）

- **命令**: `npx tsx --test __tests__/*.test.ts`（在 `extensions/pixelhero-config-editor/` 下运行）
- **结果**: **36 / 36 PASS**，0 fail，0 skip
- **耗时**: ~560–600ms

覆盖范围：

| 测试文件 | 用例数 | 覆盖点 |
|---|---|---|
| `recordValue.serializer.test.ts` | 8 | num/str/bool/enumRef/speed/arr/obj/raw 序列化；`serializeEntry` 单行与嵌套续行 |
| `parser.test.ts` | 8 | AST → RecordValue；speed 表达式识别；enumRef fallback；raw 保留；`findExportObjectLiteral` |
| `tsConfigFile.test.ts` | 10 | load/getKeys/read；patch/add/delete；`.bak` 备份；语法校验阻断；dirty/no-op save；speed+enumRef 往返不丢 |
| `validation.test.ts` | 8 | dup-uuid、missing-required、bad-enum、dangling-ref（触发槽/field/revive）、bad-override-key、herolist-inconsistent |
| `buildSkillDesc.test.ts` | 2 | 受击触发盾效、驻场光环描述 |

> **说明**：Task 11（`store.ts`）与 Task 12（`index.ts`/面板）依赖 Cocos `Editor` 全局，无法在 Node 中 import/运行，故无单元测试——按计划设计。自动化门槛以纯逻辑层 36 用例为准。

---

## 构建（BLOCKING 门槛）

- **命令**: `npm run build`（在 `extensions/pixelhero-config-editor/` 下运行）
- **结果**: 成功，两个产物均生成，esbuild 无错误。

| 产物 | 大小（字节） | 说明 |
|---|---|---|
| `dist/main.js` | 9,982,310 (~9.5 MB) | node/cjs；内联 `typescript` 编译器 API；`Editor` 为运行时全局（无 esbuild 报错） |
| `dist/panels/default.js` | 642,825 (~628 KB) | browser/iife；内联 `vue/dist/vue.esm-bundler.js`（含运行时模板编译器） |

`dist/` 已被 `extensions/pixelhero-config-editor/.gitignore` 忽略，未提交。

### 构建过程中的必要修正（已记入 Task 12 commit message）

Plan 给出的 `esbuild.config.mjs` 将面板入口设为 `platform: 'browser'` 且 `external: []`。但 Plan 的面板 `src/panels/default/index.ts` 在运行时用 `node:fs`/`node:path` 读取 `static/template/default/index.html` 与 `static/style/default/index.css`。esbuild 在 browser 平台下拒绝打包 `node:` 内建，报错：

```
X [ERROR] Could not resolve "node:fs"
X [ERROR] Could not resolve "node:path"
```

**修正**：将面板入口的 `external` 改为 `['node:fs', 'node:path']`。理由：Cocos 面板进程在 Electron 渲染层运行，能访问 Node 内建；vue 仍按 plan 打进 IIFE。`dist/main.js` 不受影响（platform:'node' 本就允许 `node:` 内建）。

---

## 编辑器内集成（ADVISORY — 待人工完成）

> 以下为人工在 Cocos Creator 3.8.6 中执行的验证清单。完成后请勾选并补截图路径。

- [ ] 1. 打开 Cocos Creator 3.8.6 项目 `d:\game\pixelheros`。
- [ ] 2. 扩展管理器（Extension Manager）→ 项目扩展 → 启用/重载 `pixelhero-config-editor`；控制台无报错。
- [ ] 3. 主菜单 → 面板（Panel）→ 英雄技能配置（Hero/Skill Config），面板打开。
- [ ] 4. 表下拉切换 `英雄/怪物` → 列表显示真实 uuid（应含 5011/5012/.../6106 等英雄条目）。
- [ ] 5. 表下拉切换 `技能` → 列表显示 6xxx 系列技能 uuid；切 `驻场技能` → 7xxx 系列。
- [ ] 6. 点选 hero 表任一条 → 右侧 `<pre>` 显示结构化 JSON：
  - [ ] 6a. `fac` 字段为 `{ "kind": "enumRef", "qualifier": "FacSet", "member": "HERO" }`（或 `MON`）。
  - [ ] 6b. 技能 `skills.<uuid>.cd` 为 `{ "kind": "speed", "level": "Slow3" }`（或其它 AtkSpeedLv 成员）。
  - [ ] 6c. 数值/字符串字段为 `{ "kind": "num"|"str", "value": ... }`。
- [ ] 7. 点选 skill 表任一条 → JSON 中 `TGroup`/`DTType`/`IType`/`RType`/`EType` 等字段均为 `enumRef`，`call_hero`（若有）为 `num` 或 `enumRef`。
- [ ] 8. 结论：端到端 IPC 打通，IO 层正确解析真实 `assets/script/game/common/config/heroSet.ts` 与 `SkillSet.ts`。
- [ ] 9. 截图存档路径（填写）：`production/qa/evidence/screenshots/config-editor-plan-a-YYYYMMDD.png`

---

## 提交记录

| Task | Commit SHA | 标题 |
|---|---|---|
| 11 | `e3102c63` | feat(config-editor): main-process store (in-memory truth + message impls + asset-db refresh) |
| 12 | `24b5c498` | feat(config-editor): extension entry + minimal Vue panel proving end-to-end IPC |
| 13 | （本提交） | test(config-editor): record Plan A verification evidence |

Tasks 1–10 由前序批次完成并提交，SHAs 详见 `git log --oneline extensions/pixelhero-config-editor/`。

---

## Definition of Done 对照

1. **扩展可被 Cocos 3.8.6 加载，菜单可打开面板** — 待人工确认（见上节步骤 2–3）。
2. **IO 层对真实配置正确解析（含 speed 表达式与枚举引用）** — 单元测试覆盖（fixtures 镜像真实形态），人工确认真实文件见步骤 6。
3. **patch 一条英雄保存后：磁盘文件更新且为合法 TS；其他条目与符号表达式原样保留；`.bak` 已生成；asset-db 已刷新** — TsConfigFile 单元测试覆盖文件行为（patch/add/delete/save/.bak/语法校验）；asset-db refresh 在 `store.saveRecord` 中调用，待人工在编辑器内验证一次保存。
4. **校验层对各类非法数据正确报错（error 级阻断保存）** — 8 个 validation 单元测试覆盖；`saveRecord` 在 error 时回滚不落盘。
5. **全部单元测试 PASS（BLOCKING）** — **36/36 PASS**。
6. **未改动 `assets/script/game/**` 任何游戏运行时代码** — 本批次仅改动 `extensions/pixelhero-config-editor/**` 与本证据文件。