docs: 全局文档梳理归档 — 删除过期文件 + 归档 V1/早期设计 + wiki 数据校正 + CLAUDE.md 规则优化

**根目录清理:**
- 删除 CLAUDE-1.md(ZCLAW 旧项目配置,HMS 已完全脱离)
- 移动 DESIGN.md → docs/archive/(ERP 旧设计系统)
- 删除 plans/ 98 个临时会话计划文件

**归档重组:**
- V1 审计(12 文件)→ docs/archive/audits-v1/
- 早期 CRM/插件迭代设计(13 文件)→ docs/archive/superpowers-early/
- 已完成/已取代设计(28 文件)→ docs/archive/superpowers-completed/
- 早期讨论/测试报告 → docs/archive/discussions-early/ + test-reports-early/
- QA 重复文件清理(3 个旧版 result 文件)

**wiki 数据校正:**
- 迁移数 137→145,源文件 599→649,提交数 720→800+
- 小程序文件 124→163,Web 前端 297→332
- 后端测试 999→943(实际统计),权限码 75+→128
- 文档索引新增归档目录说明

**CLAUDE.md 规则优化:**
- §2.5 闭环工作法:提交+文档+推送三合一 + wiki 更新触发条件
- §2.6 Feature DoD:新增文档一致性检查项
- §6 反模式:新增 wiki 更新滞后/推送不及时警告
This commit is contained in:
iven
2026-05-15 09:29:04 +08:00
parent dc983945ff
commit 18fa6ce6d4
92 changed files with 53 additions and 10253 deletions

View File

@@ -116,15 +116,29 @@
- `cargo test --workspace` — 所有测试通过(有相关测试时)
- 功能验证 — 启动后端 + 前端服务,在浏览器中实际操作验证改动生效(涉及 API 或 UI 时)
- `pnpm build` — 前端生产构建通过(涉及前端时)
5. **提交** — 验证通过后按 §5 规范提交
6. **文档同步** — 更新相关文档(如果涉及架构、接口、模块变化)
7. **推送到仓库** — 提交后立即 `git push`,确保远程仓库同步
5. **提交 + 文档 + 推送(三合一,强制)** — 验证通过后按顺序执行:
- a. 按 §5 规范提交代码
- b. 检查本次变更是否触发 wiki 更新(见下方 wiki 更新触发条件),触发则更新后单独 `docs(wiki)` 提交
- c. `git push` 立即推送,不允许"等一下再推"
- **禁止连续 5 个非 docs 提交而不更新 wiki 关键数字**
#### wiki 更新触发条件(步骤 5b 的判定标准)
以下任一条件满足时,**必须**更新 wiki 后才能继续下一任务:
- **fix 提交** → `wiki/index.md` 症状导航新增条目或标记"已修复"
- **feat 提交(新功能)** → `wiki/index.md` 关键数字更新 + 对应模块 wiki 页更新(实体数/路由数/端点数等)
- **数据库迁移变化** → 关键数字中的迁移数/表数更新
- **API 路由变化** → 路由数更新
- **测试数量变化** → 测试数/断言数更新
- **连续 5 个代码提交** → 强制做一次 wiki/index.md 关键数字全文校正(对比代码实际数量)
**铁律:**
- **步骤 0 阅读 Wiki 是绝对起点** — 不读 wiki 就开干 = 连环境配置都不知道,所有验证步骤都是空谈。
- **步骤 1 现状确认是强制起点** — 不检查就开干 = 脱离实际,所有产出不可信。
- **步骤 4 功能验证必须实际操作** — 只看编译通过不算验证,必须启动服务、在浏览器中确认功能正常。
- **步骤 7 推送是强制环节**,不推送就等于没完成。不允许"等一下再推"
- **步骤 5 三合一是强制流程** — 提交后必须检查 wiki、必须推送缺一不可
- **每次新会话开始时,先检查是否有未推送的提交并立即推送**。
### 2.6 Feature DoD — 功能完成定义(强制)
@@ -166,6 +180,13 @@
- [ ] 用户输入已验证和消毒(防 SQL 注入、XSS
- [ ] 无 CORS 通配符、无硬编码密钥
#### 文档一致性
- [ ] `wiki/index.md` 关键数字与代码实际状态一致(迁移数、路由数、实体数、测试数等)
- [ ] 新增/修复的 bug 已记录在症状导航中(含根因+解决方案)
- [ ] 新增功能已记录在对应模块 wiki 页面中(实体、端点、事件等)
- [ ] wiki 页面的"最后更新"日期已刷新为当天
#### 端到端验证
- [ ] `cargo check` 全 workspace 通过
@@ -173,6 +194,7 @@
- [ ] 浏览器中手动验证功能正常(列表/创建/编辑/删除/权限拦截)
- [ ] 小程序中验证(涉及小程序页面时)
- [ ] 相关路由权限按角色测试通过(至少 admin + 只读角色)
- [ ] 本地提交已推送到远程仓库
---
@@ -370,8 +392,11 @@ chore(docker): 添加 PostgreSQL 健康检查
- ❌ **不要**在 plugin.toml 中使用与实体名不一致的权限码 — `permissions[].code` 前缀必须与 `schema.entities[].name` 完全一致(如实体 `customer_tag` → 权限码 `customer_tag.list`/`customer_tag.manage`,不能写成 `tag.manage`),否则页面 403
- ❌ **不要**漏掉实体的 `.list` 权限 — 每个实体必须同时声明 `.list` 和 `.manage`,缺少 `.list` 导致列表页 403
- ❌ **不要**跳过验证直接提交 — 编译/测试/功能验证必须全部通过
- ❌ **不要**提交后忘记推送 — 不推送等于没完成,远程仓库必须同步
- ❌ **不要**提交后忘记推送 — 不推送等于没完成,远程仓库必须同步。每次新会话开始先检查未推送提交
- ❌ **不要**忘记更新文档 — 涉及架构、接口、模块变化时必须同步更新相关文档
- ❌ **不要**连续 5 个代码提交不更新 wiki — wiki 是团队唯一真相源过期数据比没有数据更有害5 月实测89 fix 仅 11 有 wiki 更新,关键数字迁移数差 8 个)
- ❌ **不要**修复 bug 后跳过症状导航更新 — 每个修复都应该帮助未来遇到同类问题的人快速定位根因
- ❌ **不要**新增功能后不更新 wiki 关键数字 — 迁移数/路由数/实体数/测试数必须与代码同步,否则 wiki 指标表就是废数据
- ❌ **不要**一次性输出长文档 — 超过 200 行的文档必须分步编写(先大纲 → 逐章 → 整合),否则会因上下文过长卡死
- ❌ **不要**忽略讨论记录 — 每次发散式讨论结束后必须建立文档到 `docs/discussions/`,不要口头确认后就忘
- ❌ **不要**跳过 Feature DoD — 每个功能标记"完成"前必须通过 §2.6 检查清单,不全面验证就提交 = 后续 5 次 fix媒体库教训