From 69ad12837e59b141b4fa031bbc40817e4ebb4057 Mon Sep 17 00:00:00 2001 From: tangweijie <877588133@qq.com> Date: Wed, 11 Mar 2026 17:29:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E6=88=90P2=E6=A0=87=E7=AD=BE?= =?UTF-8?q?=E5=8C=96=E4=B8=8EAI=E6=8A=BD=E6=A3=80=E8=87=AA=E5=8A=A8?= =?UTF-8?q?=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Makefile | 16 +- .../00_Management/01_Project_Progress.md | 1 + .../design/00_Management/03_Task_Checklist.md | 10 + .../09_AI_Document_Optimization_Plan.md | 6 + .../10_AI_Retrieval_Whitelist.md | 1 + .../12_AI_Weekly_Audit_Template.md | 3 +- .../00_Management/14_AI_Audit_Diff_Latest.md | 23 +++ docs/design/00_Management/README.md | 1 + .../Archive/00_Archive_Tag_Index.md | 61 ++++++ docs/design/04_Appendix/README.md | 2 +- scripts/README.md | 3 +- scripts/ai-weekly-audit-diff.sh | 189 ++++++++++++++++++ scripts/check-ai-doc-governance.sh | 19 +- scripts/generate-archive-tag-index.sh | 99 +++++++++ 14 files changed, 429 insertions(+), 5 deletions(-) create mode 100644 docs/design/00_Management/14_AI_Audit_Diff_Latest.md create mode 100644 docs/design/04_Appendix/Archive/00_Archive_Tag_Index.md create mode 100755 scripts/ai-weekly-audit-diff.sh create mode 100755 scripts/generate-archive-tag-index.sh diff --git a/Makefile b/Makefile index b34aa2a..c813119 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ # 福建水务营收系统概要设计文档 Makefile # Version: 1.0 -.PHONY: help init create validate export clean install-deps check-links check-mermaid validate-mermaid count-mermaid check-mermaid-file merge-docs check-ai-governance +.PHONY: help init create validate export clean install-deps check-links check-mermaid validate-mermaid count-mermaid check-mermaid-file merge-docs check-ai-governance archive-tag-index ai-audit-diff # 默认目标 help: @@ -21,6 +21,8 @@ help: @echo " check-mermaid 检测所有markdown文件中的mermaid图表" @echo " validate-mermaid 验证mermaid图表语法" @echo " check-ai-governance 检查AI文档治理基线" + @echo " archive-tag-index 生成 Archive 标签索引" + @echo " ai-audit-diff 生成 AI 抽检差异清单" @echo " count-mermaid 统计mermaid图表数量" @echo " check-mermaid-file 检测指定文件中的mermaid图表 (使用 FILE=文件名)" @echo " merge-docs 合并所有文档" @@ -44,6 +46,8 @@ help: @echo " make check-mermaid # 检测所有mermaid图表" @echo " make validate-mermaid # 验证mermaid语法" @echo " make check-ai-governance # 检查AI文档治理基线" + @echo " make archive-tag-index # 生成 Archive 标签索引" + @echo " make ai-audit-diff # 生成 AI 抽检差异清单" @echo " make check-mermaid-file FILE=新-概要设计说明书.md" @echo " make export-word # 导出Word文档" @echo " make export-pdf # 导出PDF文档" @@ -122,6 +126,16 @@ check-ai-governance: @echo "检查AI文档治理基线..." @./scripts/check-ai-doc-governance.sh +# 生成 Archive 标签索引 +archive-tag-index: + @echo "生成 Archive 标签索引..." + @./scripts/generate-archive-tag-index.sh + +# 生成 AI 抽检差异清单 +ai-audit-diff: + @echo "生成 AI 抽检差异清单..." + @./scripts/ai-weekly-audit-diff.sh + # 检测所有markdown文件中的mermaid图表 check-mermaid: @echo "检测所有markdown文件中的mermaid图表..." diff --git a/docs/design/00_Management/01_Project_Progress.md b/docs/design/00_Management/01_Project_Progress.md index bf30f24..0cd5e63 100644 --- a/docs/design/00_Management/01_Project_Progress.md +++ b/docs/design/00_Management/01_Project_Progress.md @@ -114,6 +114,7 @@ > 说明:本表中的历史记录按当时原始表述保留;当前正式数据库口径统一以“达梦数据库 8.0+”为准。 +| 2026-03-11 | `docs/design` P2 优化(Archive 标签化与抽检自动化) | 完成 P2 持续优化:1)新增 `scripts/generate-archive-tag-index.sh` 并生成 `docs/design/04_Appendix/Archive/00_Archive_Tag_Index.md`,对 Archive 文档按“来源/用途/可信级别”标签化;2)新增 `scripts/ai-weekly-audit-diff.sh` 并输出 `docs/design/00_Management/14_AI_Audit_Diff_Latest.md` 差异清单;3)在 `Makefile` 接入 `archive-tag-index` 与 `ai-audit-diff` 命令;4)同步更新 `12_AI_Weekly_Audit_Template.md`、`04_Appendix/README.md`、`00_Management/README.md`、`scripts/README.md` 的入口说明。 | 用户要求执行 P2 优化清单,需把“标签化 + 自动化”从规划项落地为可执行资产。 | 正面影响,Archive 资料从“目录分类”升级为“可检索标签资产”;AI 抽检从人工记录升级为脚本化差异输出,周检可复用、可对比、可追踪,后续持续治理成本显著降低。 | | 2026-03-11 | `docs/design` P1 修复(治理口径与统一入口) | 执行 P1 修复清单:1)更新 `00_Management/04_Writing_Guide.md` 中数据库选型与术语标准,统一为“达梦数据库 8.0+”;2)修复 `00_Management/03_Task_Checklist.md` 与 `00_Management/01_Project_Progress.md` 当前交付总结中的旧数据库表述;3)增强 `00_Management/11_Main_Doc_Chapter_Index.md` 的数据库导航,新增 `METER/INST` 专题边界与 `02_Table_Specs` 映射入口;4)更新 `00_Management/10_AI_Retrieval_Whitelist.md`,将 `02_Table_Specs.md` 纳入 P2 映射检索。 | 用户要求“执行 P1 修复清单”,需完成跨文档术语映射统一与入口完善。 | 正面影响,治理文档与主文档口径进一步对齐,减少历史术语对 AI 检索与评审的干扰;数据库主口径与映射补充入口更清晰,P0/P1/P2 检索链路更加稳定。 | | 2026-03-11 | `docs/design` P0 全量修复(接口/数据库/边界收敛) | 按 P0 缺口执行全量修复:1)更新 `03_Technical_Design/03_Interface_Design.md`,补齐 `IF-UP/IF-METER/IF-INST` 接口域口径并将“实现状态”改为“已覆盖 + 版本迭代维护”;2)修复 `02_Detailed_Design/01_Detailed_Design.md` 附录编号规则(`CS` 前缀、`IF-UP/REV/CS/METER/INST/EXT`)及历史占位写法;3)在 `03_Technical_Design/01_Database_Design.md` 新增 `METER/INST` 专题表边界章节,收敛 `installation_*` 与历史 `water_meter_*` 口径;4)重写 `03_Technical_Design/02_Table_Specs.md` 为“单表规格补充(历史映射)”,降级为非主口径并移除 OpenGauss 冲突表述;5)同步更新 `README.md`、`03_Technical_Design/README.md`、`02_Module_Traceability_Index.md`、`scripts/unified_export.sh` 等入口说明。 | 用户明确要求“P0 全量修复”,需消除主文档与补充文档在接口编号、数据库专题表与权威边界上的冲突。 | 正面影响,主文档链路(详设→数据库→接口)口径一致性显著提升;`02_Table_Specs` 从并行主稿风险收敛为映射补充,避免历史命名反向污染;AI 检索时“主口径优先级”更清晰,可降低后续持续优化与交付评审的返工风险。 | | 2026-03-11 | `03_Interface_Design` 主文档导航与锚点标准化 | 持续优化接口主文档可检索性:1)重构 `docs/design/03_Technical_Design/03_Interface_Design.md` 顶部导航为“章节导航(精简)”,将原目录链接统一切换为 `sec-*` 显式锚点;2)为“接口设计范围、设计原则、接口视图、外部接口、内部接口、数据对象、接口安全、实现状态”补齐稳定锚点;3)同步更新 `docs/design/00_Management/11_Main_Doc_Chapter_Index.md` 的接口主文档入口,统一改为标准化锚点。 | 用户要求“也做吧”,需要将接口主文档与已完成的概要/详细/技术主文档保持同一导航与锚点规范 | 正面影响,接口主文档章节跳转稳定性提升,避免依赖自动标题锚点;主文档章节索引与正文章节映射一致,AI 检索命中与跨文档定位效率进一步提高。 | diff --git a/docs/design/00_Management/03_Task_Checklist.md b/docs/design/00_Management/03_Task_Checklist.md index 4553d5e..559aa81 100644 --- a/docs/design/00_Management/03_Task_Checklist.md +++ b/docs/design/00_Management/03_Task_Checklist.md @@ -138,6 +138,16 @@ ## ✅ 最新完成任务 (持续更新) +### 📋 `docs/design` P2 优化(标签化 + 自动化) + +- [x] **完成 Archive 标签化与 AI 抽检自动化** ✅ (2026-03-11) + - [x] 新增 `scripts/generate-archive-tag-index.sh`,支持一键生成 Archive 标签索引 ✅ + - [x] 生成 `docs/design/04_Appendix/Archive/00_Archive_Tag_Index.md`(来源/用途/可信级别)✅ + - [x] 新增 `scripts/ai-weekly-audit-diff.sh`,输出标准化差异清单 ✅ + - [x] 生成 `docs/design/00_Management/14_AI_Audit_Diff_Latest.md`(当前差异 0)✅ + - [x] `Makefile` 新增 `archive-tag-index` 与 `ai-audit-diff` 命令入口 ✅ + - [x] 更新 `12_AI_Weekly_Audit_Template.md`、`04_Appendix/README.md`、`00_Management/README.md`、`scripts/README.md` ✅ + ### 📋 `docs/design` P1 修复(治理口径与统一入口) - [x] **完成跨文档术语统一与检索入口增强** ✅ (2026-03-11) diff --git a/docs/design/00_Management/09_AI_Document_Optimization_Plan.md b/docs/design/00_Management/09_AI_Document_Optimization_Plan.md index 4afeba9..64dc730 100644 --- a/docs/design/00_Management/09_AI_Document_Optimization_Plan.md +++ b/docs/design/00_Management/09_AI_Document_Optimization_Plan.md @@ -172,9 +172,15 @@ - 已新增主文档章节导航:`docs/design/00_Management/11_Main_Doc_Chapter_Index.md`。 - 已新增每周抽检模板:`docs/design/00_Management/12_AI_Weekly_Audit_Template.md`。 - 已新增 AI 治理检查脚本:`scripts/check-ai-doc-governance.sh`,并接入 pre-push。 +- 已新增 Archive 标签索引:`docs/design/04_Appendix/Archive/00_Archive_Tag_Index.md`。 +- 已新增 Archive 标签生成脚本:`scripts/generate-archive-tag-index.sh`(`make archive-tag-index`)。 +- 已新增 AI 抽检差异脚本:`scripts/ai-weekly-audit-diff.sh`(`make ai-audit-diff`)。 +- 已新增自动化差异清单:`docs/design/00_Management/14_AI_Audit_Diff_Latest.md`。 ### 当前指标 - 一级目录 README 覆盖率:100%(7/7) - 主文档 Front Matter 覆盖率:100%(6/6) - AI 治理脚本检查:已通过 +- Archive 标签覆盖率:100%(31/31,Markdown 文档) +- AI 抽检差异清单:可自动生成(当前差异 0) diff --git a/docs/design/00_Management/10_AI_Retrieval_Whitelist.md b/docs/design/00_Management/10_AI_Retrieval_Whitelist.md index abd49aa..527b783 100644 --- a/docs/design/00_Management/10_AI_Retrieval_Whitelist.md +++ b/docs/design/00_Management/10_AI_Retrieval_Whitelist.md @@ -24,6 +24,7 @@ 5. `docs/design/02_Detailed_Design/02_Module_Traceability_Index.md` 6. `docs/design/00_Management/01_Project_Progress.md` 7. `docs/design/00_Management/03_Task_Checklist.md` +8. `docs/design/00_Management/14_AI_Audit_Diff_Latest.md` ### P2:辅助映射资料 diff --git a/docs/design/00_Management/12_AI_Weekly_Audit_Template.md b/docs/design/00_Management/12_AI_Weekly_Audit_Template.md index 2825d8c..a64e194 100644 --- a/docs/design/00_Management/12_AI_Weekly_Audit_Template.md +++ b/docs/design/00_Management/12_AI_Weekly_Audit_Template.md @@ -37,6 +37,8 @@ | `make check-links` | 通过/未通过 | | | `make validate-mermaid` | 通过/未通过 | | | `scripts/check-ai-doc-governance.sh` | 通过/未通过 | | +| `make archive-tag-index` | 通过/未通过 | Archive 标签索引更新 | +| `make ai-audit-diff` | 通过/未通过 | 输出差异清单并归档 | ## 5. 问题与整改计划 @@ -50,4 +52,3 @@ - 下周重点动作: 1. 待填写 2. 待填写 - diff --git a/docs/design/00_Management/14_AI_Audit_Diff_Latest.md b/docs/design/00_Management/14_AI_Audit_Diff_Latest.md new file mode 100644 index 0000000..361a921 --- /dev/null +++ b/docs/design/00_Management/14_AI_Audit_Diff_Latest.md @@ -0,0 +1,23 @@ +# 福建水务营收系统 AI 抽检差异清单(自动生成) + +## 1. 生成信息 + +| 项目 | 内容 | +| --- | --- | +| 生成时间 | 2026-03-11 17:29:08 | +| 扫描范围 | P0 主文档 + P1 治理入口(非 Archive) | +| 差异总数 | 0 | +| P1 差异数 | 0 | +| P2 差异数 | 0 | + +## 2. 差异明细 + +| 编号 | 类别 | 文件 | 行号 | 现象 | 建议 | 级别 | +| --- | --- | --- | --- | --- | --- | --- | +| - | - | - | - | 未发现口径差异 | 无需修复 | - | + +## 3. 建议动作 + +1. 先修复 P1 差异,再处理 P2 优化项。 +2. 修复后执行:`make check-links`、`make validate-mermaid`、`make check-ai-governance`。 +3. 周检归档可复用 `docs/design/00_Management/12_AI_Weekly_Audit_Template.md`。 diff --git a/docs/design/00_Management/README.md b/docs/design/00_Management/README.md index e1c4903..f9a4817 100644 --- a/docs/design/00_Management/README.md +++ b/docs/design/00_Management/README.md @@ -19,6 +19,7 @@ - `11_Main_Doc_Chapter_Index.md`:主文档章节导航索引 - `12_AI_Weekly_Audit_Template.md`:每周抽检模板 - `13_AI_Weekly_Audit_2026W11.md`:首次周检记录示例 +- `14_AI_Audit_Diff_Latest.md`:自动化差异清单(P2) ## 使用顺序(建议) diff --git a/docs/design/04_Appendix/Archive/00_Archive_Tag_Index.md b/docs/design/04_Appendix/Archive/00_Archive_Tag_Index.md new file mode 100644 index 0000000..182d7b3 --- /dev/null +++ b/docs/design/04_Appendix/Archive/00_Archive_Tag_Index.md @@ -0,0 +1,61 @@ +# 福建水务营收系统 Archive 标签索引 + +## 文档定位 + +本文档用于对 `docs/design/04_Appendix/Archive/` 下历史资料进行标签化管理,统一标注: + +- 来源标签(source) +- 用途标签(usage) +- 可信级别(trust_level) + +> 说明:Archive 资料仅用于追溯与核对,**不得直接替代 P0 主文档口径**。 + +## 标签定义 + +| 维度 | 标签 | 说明 | +| --- | --- | --- | +| 来源标签 | `REQ` | 需求规格或需求澄清原文 | +| 来源标签 | `MANUAL` | 操作手册或使用说明资料 | +| 来源标签 | `DESIGN_LEGACY` | 历史设计稿或旧版设计产物 | +| 来源标签 | `ORIGINAL_ATTACH` | 原始附件导出稿或原始副本 | +| 来源标签 | `DATA_DICT` | 数据字典与字段口径资料 | +| 来源标签 | `INTEGRATION` | 外部集成、接口协同类资料 | +| 可信级别 | `A` | 原始来源资料,可信但需结合当前主文档裁剪 | +| 可信级别 | `B` | 整编/映射资料,需交叉核对 | +| 可信级别 | `C` | 历史方案资料,仅作参考线索 | + +## 归档文档标签清单 + +| 文档路径 | 来源标签 | 用途标签 | 可信级别 | 正式口径可直接引用 | +| --- | --- | --- | --- | --- | +| `docs/design/04_Appendix/Archive/01_Requirements/202-营业收费管理系统需求规格说明书-需求+设计.md` | `REQ` | 需求追溯 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/01_Requirements/202-营业收费管理系统需求规格说明书20240412.md` | `REQ` | 需求追溯 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/01_Requirements/202-营业收费管理系统需求规格说明书20240415.md` | `REQ` | 需求追溯 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/01_Requirements/202-设备管理系统需求规格说明书.md` | `REQ` | 需求追溯 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/01_Requirements/营收系统_需求规格说明书.md` | `REQ` | 需求追溯 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/02_Manuals/抄表APP详细设计.md` | `MANUAL` | 流程核对 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/02_Manuals/福建水投PDA操作手册.md` | `MANUAL` | 流程核对 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/02_Manuals/福建水投微网厅操作手册.md` | `MANUAL` | 流程核对 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/02_Manuals/福建水投营收系统操作手册.md` | `MANUAL` | 流程核对 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/02_Manuals/营收系统_用户操作手册.md` | `MANUAL` | 流程核对 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/03_Design_Docs/02_Module_Design_legacy_20260311.md` | `DESIGN_LEGACY` | 历史方案对照 | C | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/03_Design_Docs/03_CA_Installation_Design_legacy_20260311.md` | `DESIGN_LEGACY` | 历史方案对照 | C | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/03_Design_Docs/数据库设计.md` | `DESIGN_LEGACY` | 历史方案对照 | C | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/03_Design_Docs/营收系统_详细设计说明书.md` | `DESIGN_LEGACY` | 历史方案对照 | C | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/03_Design_Docs/营收系统银行接口规范设计文档.md` | `DESIGN_LEGACY` | 历史方案对照 | C | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/04_Original_Attachments/202-营业收费管理系统需求规格说明书 - 需求+设计.md` | `ORIGINAL_ATTACH` | 原始附件取证 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/04_Original_Attachments/202-营业收费管理系统需求规格说明书20240412.md` | `ORIGINAL_ATTACH` | 原始附件取证 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/04_Original_Attachments/202-营业收费管理系统需求规格说明书20240415.md` | `ORIGINAL_ATTACH` | 原始附件取证 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/04_Original_Attachments/202-设备管理系统需求规格说明书.md` | `ORIGINAL_ATTACH` | 原始附件取证 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/04_Original_Attachments/抄表APP详细设计.md` | `ORIGINAL_ATTACH` | 原始附件取证 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/04_Original_Attachments/物联网集抄及营收平台关于水表数据交互需求及接口规范V1.2-20220921.md` | `ORIGINAL_ATTACH` | 原始附件取证 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/04_Original_Attachments/福建水投PDA操作手册.md` | `ORIGINAL_ATTACH` | 原始附件取证 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/04_Original_Attachments/福建水投微网厅操作手册.md` | `ORIGINAL_ATTACH` | 原始附件取证 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/04_Original_Attachments/福建水投营收系统操作手册.md` | `ORIGINAL_ATTACH` | 原始附件取证 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/04_Original_Attachments/营收系统_用户操作手册.md` | `ORIGINAL_ATTACH` | 原始附件取证 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/04_Original_Attachments/营收系统_详细设计说明书.md` | `ORIGINAL_ATTACH` | 原始附件取证 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/04_Original_Attachments/营收系统_需求规格说明书.md` | `ORIGINAL_ATTACH` | 原始附件取证 | A | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md` | `DATA_DICT` | 字段口径追溯 | B | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/07_Integration/物联网集抄及营收平台关于水表数据交互需求及接口规范.md` | `INTEGRATION` | 跨系统集成核对 | B | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/07_Integration/表务水表功能整合.md` | `INTEGRATION` | 跨系统集成核对 | B | 否(需回写 P0) | +| `docs/design/04_Appendix/Archive/07_Integration/表务管理整合.md` | `INTEGRATION` | 跨系统集成核对 | B | 否(需回写 P0) | diff --git a/docs/design/04_Appendix/README.md b/docs/design/04_Appendix/README.md index 613cb16..dae6dda 100644 --- a/docs/design/04_Appendix/README.md +++ b/docs/design/04_Appendix/README.md @@ -10,6 +10,7 @@ - `02_Database_Design_CA.md`:CA 数据库设计 - `03_CA_Integration_Summary.md`:CA 集成总结 - `Archive/`:历史资料归档区 +- `Archive/00_Archive_Tag_Index.md`:归档标签索引(来源、用途、可信级别) ## Archive 使用边界 @@ -21,4 +22,3 @@ - 迁移历史文档时,必须与同名 `_images/` 目录成组处理 - 迁移后需修复相对路径并执行链接校验 - diff --git a/scripts/README.md b/scripts/README.md index 1270664..1d164ce 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -15,10 +15,11 @@ ## AI 治理脚本 - `check-ai-doc-governance.sh`:检查目录索引、主文档元数据与 AI 维护资产完整性 +- `generate-archive-tag-index.sh`:生成 Archive 标签索引(来源、用途、可信级别) +- `ai-weekly-audit-diff.sh`:生成 AI 抽检差异清单(口径与编号差异) ## 使用建议 - 本地快速校验:`make validate-file FILE=<目标文件>` - 跨文档校验:`make check-links`、`make validate-mermaid` - 提交前演练:`pre-commit run --files <变更文件>` - diff --git a/scripts/ai-weekly-audit-diff.sh b/scripts/ai-weekly-audit-diff.sh new file mode 100755 index 0000000..4830771 --- /dev/null +++ b/scripts/ai-weekly-audit-diff.sh @@ -0,0 +1,189 @@ +#!/usr/bin/env bash +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +default_output="$repo_root/docs/design/00_Management/14_AI_Audit_Diff_Latest.md" +output_file="$default_output" +strict_mode="false" + +while [[ $# -gt 0 ]]; do + case "$1" in + --output) + output_file="$2" + shift 2 + ;; + --strict) + strict_mode="true" + shift + ;; + *) + echo "未知参数: $1" + echo "用法: $0 [--output <输出文件>] [--strict]" + exit 1 + ;; + esac +done + +formal_files=( + "docs/design/01_Overview/03_Summary_Design.md" + "docs/design/02_Detailed_Design/01_Detailed_Design.md" + "docs/design/03_Technical_Design/01_Database_Design.md" + "docs/design/03_Technical_Design/03_Interface_Design.md" + "docs/design/03_Technical_Design/04_Security_Design.md" + "docs/design/03_Technical_Design/05_Deployment_Design.md" + "docs/design/00_Management/04_Writing_Guide.md" + "docs/design/00_Management/10_AI_Retrieval_Whitelist.md" + "docs/design/00_Management/11_Main_Doc_Chapter_Index.md" +) + +archive_root="$repo_root/docs/design/04_Appendix/Archive" +archive_tag_index="$archive_root/00_Archive_Tag_Index.md" + +tmp_diff="$(mktemp)" +trap 'rm -f "$tmp_diff"' EXIT + +diff_id=0 + +add_diff() { + local category="$1" + local file="$2" + local line_no="$3" + local symptom="$4" + local suggestion="$5" + local severity="$6" + + diff_id=$((diff_id + 1)) + symptom="${symptom//|/\\|}" + suggestion="${suggestion//|/\\|}" + printf "%s\t%s\t%s\t%s\t%s\t%s\t%s\n" \ + "$diff_id" "$category" "$file" "$line_no" "$symptom" "$suggestion" "$severity" >>"$tmp_diff" +} + +scan_pattern() { + local category="$1" + local pattern="$2" + local suggestion="$3" + local severity="$4" + + for rel_file in "${formal_files[@]}"; do + local abs_file="$repo_root/$rel_file" + [[ -f "$abs_file" ]] || continue + + while IFS= read -r row; do + [[ -z "$row" ]] && continue + local file_part="${row%%:*}" + local rest="${row#*:}" + local line_no="${rest%%:*}" + local content="${rest#*:}" + local file_rel="${file_part#"$repo_root/"}" + + if [[ "$category" == "数据库口径" ]] && grep -q "替换为达梦数据库" <<<"$content"; then + continue + fi + + add_diff "$category" "$file_rel" "$line_no" "$content" "$suggestion" "$severity" + done < <(rg -n --no-heading --color never --with-filename --pcre2 "$pattern" "$abs_file" || true) + done +} + +# 规则 1:系统名称混用 +scan_pattern \ + "系统名称口径" \ + "营业收费系统|数智营收管理系统|客户服务平台" \ + "统一使用“福建水务营收系统”(引用原文除外)" \ + "P2" + +# 规则 2:数据库旧口径 +scan_pattern \ + "数据库口径" \ + "OpenGauss|openGauss" \ + "统一为“达梦数据库 8.0+”,历史记录场景需显式标注" \ + "P1" + +# 规则 3:接口占位编号 +scan_pattern \ + "接口编号规范" \ + "IF-XXX|EXT-XXX" \ + "使用 IF-UP/IF-REV/IF-CS/IF-METER/IF-INST/IF-EXT 规则" \ + "P1" + +# 规则 4:旧模块编号残留 +scan_pattern \ + "模块编号规范" \ + "SERVICE-[0-9]{3}" \ + "统一使用 CS-00x 编号规则" \ + "P2" + +# 规则 5:Archive 标签覆盖检查 +if [[ ! -f "$archive_tag_index" ]]; then + add_diff \ + "Archive 标签覆盖" \ + "docs/design/04_Appendix/Archive/00_Archive_Tag_Index.md" \ + "-" \ + "缺少 Archive 标签索引文件" \ + "先执行 make archive-tag-index 生成标签索引" \ + "P1" +else + while IFS= read -r abs_md; do + rel_md="${abs_md#"$repo_root/"}" + if ! grep -Fq "\`$rel_md\`" "$archive_tag_index"; then + add_diff \ + "Archive 标签覆盖" \ + "$rel_md" \ + "-" \ + "未在 Archive 标签索引中登记" \ + "执行 make archive-tag-index 更新标签清单" \ + "P2" + fi + done < <(find "$archive_root" -type f -name "*.md" ! -name "00_Archive_Tag_Index.md" | sort) +fi + +total_count="$(wc -l < "$tmp_diff" | tr -d ' ')" +p1_count="$(awk -F'\t' '$7=="P1"{c++} END{print c+0}' "$tmp_diff")" +p2_count="$(awk -F'\t' '$7=="P2"{c++} END{print c+0}' "$tmp_diff")" + +output_dir="$(dirname "$output_file")" +mkdir -p "$output_dir" + +{ + echo "# 福建水务营收系统 AI 抽检差异清单(自动生成)" + echo + echo "## 1. 生成信息" + echo + echo "| 项目 | 内容 |" + echo "| --- | --- |" + echo "| 生成时间 | $(date '+%Y-%m-%d %H:%M:%S') |" + echo "| 扫描范围 | P0 主文档 + P1 治理入口(非 Archive) |" + echo "| 差异总数 | $total_count |" + echo "| P1 差异数 | $p1_count |" + echo "| P2 差异数 | $p2_count |" + echo + echo "## 2. 差异明细" + echo + echo "| 编号 | 类别 | 文件 | 行号 | 现象 | 建议 | 级别 |" + echo "| --- | --- | --- | --- | --- | --- | --- |" + + if [[ "$total_count" -eq 0 ]]; then + echo "| - | - | - | - | 未发现口径差异 | 无需修复 | - |" + else + while IFS=$'\t' read -r id category file line_no symptom suggestion severity; do + printf '| %s | %s | `%s` | %s | %s | %s | %s |\n' \ + "$id" "$category" "$file" "$line_no" "$symptom" "$suggestion" "$severity" + done < "$tmp_diff" + fi + + echo + echo "## 3. 建议动作" + echo + echo "1. 先修复 P1 差异,再处理 P2 优化项。" + echo '2. 修复后执行:`make check-links`、`make validate-mermaid`、`make check-ai-governance`。' + echo '3. 周检归档可复用 `docs/design/00_Management/12_AI_Weekly_Audit_Template.md`。' +} >"$output_file" + +echo "✅ AI 抽检差异清单已生成: $output_file" +echo " 差异总数: $total_count (P1=$p1_count, P2=$p2_count)" + +if [[ "$strict_mode" == "true" && "$total_count" -gt 0 ]]; then + echo "❌ 严格模式下存在差异,返回失败。" + exit 1 +fi diff --git a/scripts/check-ai-doc-governance.sh b/scripts/check-ai-doc-governance.sh index cc6cf9c..1947ca2 100755 --- a/scripts/check-ai-doc-governance.sh +++ b/scripts/check-ai-doc-governance.sh @@ -34,6 +34,14 @@ required_ai_assets=( "docs/design/00_Management/10_AI_Retrieval_Whitelist.md" "docs/design/00_Management/11_Main_Doc_Chapter_Index.md" "docs/design/00_Management/12_AI_Weekly_Audit_Template.md" + "docs/design/00_Management/14_AI_Audit_Diff_Latest.md" + "docs/design/04_Appendix/Archive/00_Archive_Tag_Index.md" +) + +required_ai_scripts=( + "scripts/check-ai-doc-governance.sh" + "scripts/generate-archive-tag-index.sh" + "scripts/ai-weekly-audit-diff.sh" ) failure_count=0 @@ -60,6 +68,16 @@ for file in "${required_ai_assets[@]}"; do fi done +echo "检查 AI 治理脚本..." +for file in "${required_ai_scripts[@]}"; do + if [[ -f "$file" ]]; then + echo "✅ $file" + else + echo "❌ 缺少: $file" + failure_count=$((failure_count + 1)) + fi +done + echo "检查主文档 Front Matter..." for file in "${required_main_docs[@]}"; do if [[ ! -f "$file" ]]; then @@ -98,4 +116,3 @@ if [[ "$failure_count" -gt 0 ]]; then fi echo "AI 文档治理检查通过" - diff --git a/scripts/generate-archive-tag-index.sh b/scripts/generate-archive-tag-index.sh new file mode 100755 index 0000000..6fa595e --- /dev/null +++ b/scripts/generate-archive-tag-index.sh @@ -0,0 +1,99 @@ +#!/usr/bin/env bash +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +archive_root="$repo_root/docs/design/04_Appendix/Archive" +output_file="$archive_root/00_Archive_Tag_Index.md" + +if [[ ! -d "$archive_root" ]]; then + echo "❌ Archive 目录不存在: $archive_root" + exit 1 +fi + +tmp_file="$(mktemp)" +trap 'rm -f "$tmp_file"' EXIT + +cat >"$tmp_file" <<'EOF' +# 福建水务营收系统 Archive 标签索引 + +## 文档定位 + +本文档用于对 `docs/design/04_Appendix/Archive/` 下历史资料进行标签化管理,统一标注: + +- 来源标签(source) +- 用途标签(usage) +- 可信级别(trust_level) + +> 说明:Archive 资料仅用于追溯与核对,**不得直接替代 P0 主文档口径**。 + +## 标签定义 + +| 维度 | 标签 | 说明 | +| --- | --- | --- | +| 来源标签 | `REQ` | 需求规格或需求澄清原文 | +| 来源标签 | `MANUAL` | 操作手册或使用说明资料 | +| 来源标签 | `DESIGN_LEGACY` | 历史设计稿或旧版设计产物 | +| 来源标签 | `ORIGINAL_ATTACH` | 原始附件导出稿或原始副本 | +| 来源标签 | `DATA_DICT` | 数据字典与字段口径资料 | +| 来源标签 | `INTEGRATION` | 外部集成、接口协同类资料 | +| 可信级别 | `A` | 原始来源资料,可信但需结合当前主文档裁剪 | +| 可信级别 | `B` | 整编/映射资料,需交叉核对 | +| 可信级别 | `C` | 历史方案资料,仅作参考线索 | + +## 归档文档标签清单 + +| 文档路径 | 来源标签 | 用途标签 | 可信级别 | 正式口径可直接引用 | +| --- | --- | --- | --- | --- | +EOF + +while IFS= read -r abs_path; do + rel_path="${abs_path#"$repo_root/"}" + after_archive="${rel_path#docs/design/04_Appendix/Archive/}" + top_dir="${after_archive%%/*}" + + source_tag="UNKNOWN" + usage_tag="待补充" + trust_level="C" + + case "$top_dir" in + "01_Requirements") + source_tag="REQ" + usage_tag="需求追溯" + trust_level="A" + ;; + "02_Manuals") + source_tag="MANUAL" + usage_tag="流程核对" + trust_level="A" + ;; + "03_Design_Docs") + source_tag="DESIGN_LEGACY" + usage_tag="历史方案对照" + trust_level="C" + ;; + "04_Original_Attachments") + source_tag="ORIGINAL_ATTACH" + usage_tag="原始附件取证" + trust_level="A" + ;; + "05_Data_Dictionary") + source_tag="DATA_DICT" + usage_tag="字段口径追溯" + trust_level="B" + ;; + "07_Integration") + source_tag="INTEGRATION" + usage_tag="跨系统集成核对" + trust_level="B" + ;; + esac + + printf '| `%s` | `%s` | %s | %s | 否(需回写 P0) |\n' \ + "$rel_path" "$source_tag" "$usage_tag" "$trust_level" >>"$tmp_file" +done < <(find "$archive_root" -type f -name "*.md" ! -name "00_Archive_Tag_Index.md" | sort) + +mv "$tmp_file" "$output_file" +chmod 644 "$output_file" +trap - EXIT + +echo "✅ Archive 标签索引已生成: $output_file"