tanzk
cab6599ee2
docs(governance): 文档性质标记规范 — 区分「需求」与「需求的需求」+ 全量打标 (#71)
用户: 「有的是需求，有的是需求的需求，都需要打上不同的标记」
## 核心洞察
三类文档（META/REQ/REF）长期混用同一套审查标准 → 用错标准 = 审查失效。
## 新增规范
docs/standards/文档性质标记规范.md (v1.0)
- 三分类定义 + 判定判据（判据是「约束范围」，不是文件名）
- ★ 三类规则差异表：
| | META | REQ | REF |
|审查标准| 能否约束住别人 | 验收标准达成 | 与代码一致 |
|变更成本| 高(全仓) | 中(局部) | 低(同步) |
|架构锁定| ❌ | ✅ | ❌ |
- 三层落地：① 文档头标性质 ② README §六 索引 ③ META 强制类挂 AGENTS
## 全量打标 25/25
META 13 · REQ 5 · REF 7
## ★ 盘点发现（已修复）
- **11 份 META 中曾仅 4 份有强制入口** → 7 份「标记了但约束不住」
- docs/standards/ 目录名误导：18 份混着 4 REF + 3 REQ
- 易错点：名为"XX接入规范"但只约束一个集成 → 是 REQ 不是 META
## 强制链补齐（AGENTS.md 绝对禁止 8~11）
新增 4 条，把"待挂"META 接入强制链：
- 8. error-code.md 响应格式（成功 {code,data,message} / 错误走 HTTPException）
- 9. 数据采集合并去重机制 所有采集通道的去重键
- 10. 投诉渠道口径与对账 渠道口径权威定义（改动影响全部投诉数字）
- 11. 数据源接入与缓存加速 缓存铁律（写入后必须失效 pattern）
## 其它
- docs/README.md 新增 §六 文档性质索引（单一事实来源）；修复历史表格粘连缺陷
- AGENTS.md 新增「文档性质纪律（强制）」章
- review-checklist.md 新增「文档性质」检查项（6 条子项）
- .github/instructions/doc-class-rationale.instructions.md（applyTo: docs/**）
---
## 附带修复：前端构建/编辑器报错（真实问题）
### ① Vue 3 模板被误报 compileError（根因：仓库根无 ESLint 配置）
现象：`v-model:preset="..."` 被编辑器标 [vue/no-v-model-argument] compileError
实测澄清：vite build / docker build / 命令行 eslint **全部通过**
根因：VS Code ESLint 扩展以**工作区根**为 cwd 启动；根目录无任何 ESLint 配置
→ 回退内置默认规则集（含 Vue 2 遗留规则 vue/no-v-model-argument）
修复：
- 新增 eslint.config.mjs（根级**桥接**文件，转发 web/eslint.config.js，单一事实来源）
- 新增 web/jsconfig.json（声明 vueCompilerOptions.target=3，Vue 语言服务）
- 新增 .vscode/settings.json（eslint.useFlatConfig=true 等）
- web/eslint.config.js 显式关闭 vue/no-v-model-argument 并注明原因
验证：两个 cwd 均解析出 118 条规则、该规则 = [0]（一致）
### ② el-radio-button label → value 迁移（Element Plus 2.14 弃用）
实测告警：[el-radio] label act as value is about to be deprecated (3.0.0 移除)
项目实际装 element-plus 2.14.4（package.json 写 ^2.6.2）→ 告警真实存在
迁移 28 文件 / 158 处（脚本 scripts/migrate_radio_label_to_value.py，可复现）
验证：浏览器实测 el-radio 弃用告警**归零**
## 验证
- 前端 eslint 0 error（5 warning 均为既有 v-html）· vitest 52 例全绿
- vite build 成功 · docker compose build --no-cache 成功
- 文档性质标记覆盖 25/25 · AGENTS 强制链 9 份 META
关联工单: #71