维护手册

玩家设定 →

「玩家设定 →」

代码变更后的标准同步工作流（DESIGN 6.5 展开）。核心原则：数据与页面同 commit；构建即验证；以代码为准。

1. 同步工作流（标准动作）

1. 代码变更后：npm run sync
   （= npm run extract && npm run verify）
2. 看 verify 报告：
   - STALE → 对应页面出过期徽标 → 核对新数值 → 更新设定/技术叙述
   - 覆盖率告警（V2）→ 新玩法出现 → 按模板建设定页 + 技术页
   - 配对告警（V4）→ pair 断链 → 修复 frontmatter
3. 提交：data/ 与页面同 commit；manifest 记录最后同步点
4. 可选：pre-commit hook / CI 跑 verify --strict

1.1 npm run extract（三提取器）

提取器	输入	输出
scripts/extract-rules.mjs	domain/*Rules.java、config/*Config.java	data/rules/*.json（28 个）
scripts/extract-balance.mjs	application*.yml 的 emberfall.* 子树	data/yml/*.json
scripts/extract-sql-seed.mjs	V47/V64/V66/V81/V85 + db/init.sql 配置表 INSERT	data/sql/*.json（9 个，版本重放 + manual-overrides.json）

提取失败的文件显式写入 data/unparsed.json（当前为空），绝不静默跳过。

1.2 npm run verify（五项校验）

校验	规则	失败处置
V1 数据新鲜度	data/*.json 的 sha256 与当前源文件对比	输出 STALE → 页面过期徽标；build 默认失败（--allow-stale 降级警告）
V2 玩法覆盖率	后端 *Controller.java ↔ settings 页 frontmatter	缺页告警（新玩法出现）
V3 路由/视图对齐	前端路由 ↔ settings 页 route 字段	告警
V4 配对完整性	设定页 pair ↔ 技术页双向存在	缺失视为未完成
V5 来源存在性	技术页 SourceRef/CodeFact 路径真实存在	告警

2. STALE 处理流程

1. 运行 npm run sync 后 verify-report.json 列出 STALE 项（data/*.json 的 source.sha256 与当前源码不符）
2. 对每个 STALE 项：git diff 查看代码变更 → 若数值变化：更新相关页面叙述与差异审计（新差异 → 写 audit/diffs/dNN → 页面挂 DiffNote）
3. 重新 npm run extract 生成新 data/*.json，npm run verify 全绿后提交

3. 新玩法加入流程（新 Controller 出现时）

1. npm run verify → V2 覆盖率告警列出新 *Controller.java
2. 判断玩法归类（growth/combat/dungeon/social/monetization），在 settings/<域>/ 建设定页（5.2 七节模板）+ tech/implementations/<域>/ 建技术页（5.3 六节模板）
3. frontmatter 配对：设定页 pair: tech/implementations/<域>/<页>；技术页 pair: tech/implementations/<域>/<页>（同值）
4. 状态徽标与代码事实一致（在线/已停用/未开放/已下线，准则 8）
5. 若涉及 yml 新键 → 更新 配置中心；若涉及新表 → 更新 数据模型索引
6. 更新 source-index（新常量类 → 提取器清单）
7. 跑 npm run sync 全绿后提交

4. pair 维护

• 双向约定：设定页与实现页 frontmatter 的 pair 同值 = 实现页路径（如 tech/implementations/growth/realm）
• verify V4 双向校验；断链时两页同时修复
• 页面改名必须同步改两侧 pair + 更新 audit/index.md 的 affected 与全站链接

5. 物品图鉴复核流程（items-name-map.json）

1. 物品中文名映射为人工维护资产（准则 12）：data/items-name-map.json（ID → 中文名/用途/来源）
2. AI 生成初稿必须标注「待策划复核」；策划确认后移除标记
3. 代码中物品常量变化（GameRepository/GameRepositoryGoldItems 的 ID 常量）→ 同步复核图鉴条目
4. 设定页禁止直接展示物品 ID；技术页允许

6. 构建与部署

命令	行为
npm run dev	VitePress 本地预览
npm run build	npm run sync（失败即中止）+ vitepress build docs
npm run preview	预览构建产物
deploy-docs.ps1	npm ci && npm run build → 压缩 → 上传 Nginx 静态目录（/emberfall-docs/）

• buildEnd 钩子执行 verify；STALE 默认构建失败（--allow-stale 仅本地调试）
• CI 建议：push 到 docs 相关路径时跑 node scripts/verify.mjs --strict，失败即中止合并；pre-commit hook 跑 verify 快速模式

7. 差异留痕（准则 7）

任何「旧 docs vs 代码」冲突：先写 tech/audit/diffs/ 条目（5.5 模板），再在设定页挂 DiffNote，最后登记 audit/index.md 总览。禁止只改页面不登记差异。

8. 相关页面

• 设定来源索引：数据管线产物与来源
• 差异审计：D1~D7 与新增流程
• 配置中心：键变更时的更新点
• 架构总览：模块与迁移体系