101 lines
5.1 KiB
Markdown
101 lines
5.1 KiB
Markdown
# 实施计划：文档体系整理与优化
|
||
|
||
## 概述
|
||
|
||
基于设计文档，将实施分为四个阶段：新增文档目录与骨架文件、业务规则文档迁移、审计一览表生成脚本开发、文档总索引更新。所有任务聚焦于文件创建/修改和 Python 脚本编写。
|
||
|
||
## 任务
|
||
|
||
- [x] 1. 新增文档目录与骨架文件
|
||
- [x] 1.1 创建 `docs/architecture/` 目录及文档
|
||
- 创建 `docs/architecture/README.md`（目录索引）
|
||
- 创建 `docs/architecture/system_overview.md`（系统整体架构：数据流向图、模块交互、技术栈）
|
||
- 创建 `docs/architecture/data_flow.md`（ODS→DWD→DWS 数据流向详解）
|
||
- 从根 `README.md` 和 `.kiro/steering/` 中提取架构信息填充内容
|
||
- _Requirements: 1.3_
|
||
|
||
- [x] 1.2 创建 `docs/operations/` 目录及文档
|
||
- 创建 `docs/operations/README.md`（目录索引）
|
||
- 创建 `docs/operations/environment_setup.md`（环境搭建指南：Python、PostgreSQL、依赖安装）
|
||
- 创建 `docs/operations/scheduling.md`（调度配置说明：CLI 参数、定时任务、管道模式）
|
||
- 创建 `docs/operations/troubleshooting.md`（故障排查手册：常见错误与解决方案）
|
||
- _Requirements: 1.5_
|
||
|
||
- [x] 1.3 创建 `docs/CHANGELOG.md`
|
||
- 基于 `docs/audit/changes/` 中的审计记录，整理项目级版本变更历史
|
||
- 包含日期、变更摘要和影响范围
|
||
- _Requirements: 1.6_
|
||
|
||
- [x] 2. 业务规则文档迁移与目录建设
|
||
- [x] 2.1 创建 `docs/business-rules/` 目录并迁移指数算法文档
|
||
- 创建 `docs/business-rules/README.md`（目录索引，按业务域列出文档）
|
||
- 将 `docs/database/DWS/index_algorithm_cn.md` 内容复制到 `docs/business-rules/index_algorithm_cn.md`
|
||
- 将原 `docs/database/DWS/index_algorithm_cn.md` 替换为重定向说明
|
||
- _Requirements: 3.1, 3.2, 3.3, 3.4_
|
||
|
||
- [x] 2.2 创建业务规则骨架文档
|
||
- 创建 `docs/business-rules/dws_metrics.md`（DWS 口径定义骨架）
|
||
- 创建 `docs/business-rules/scd2_rules.md`（SCD2 处理规则骨架）
|
||
- _Requirements: 3.4_
|
||
|
||
- [x] 3. 检查点 — 确认文档目录结构正确
|
||
- 确认所有新增目录和文件已创建，如有问题请提出。
|
||
|
||
- [x] 4. 审计一览表生成脚本
|
||
- [x] 4.1 实现审计记录解析模块
|
||
- 在 `scripts/gen_audit_dashboard.py` 中实现 `AuditEntry` 数据类
|
||
- 实现 `parse_audit_file(filepath)` 函数：从文件名提取日期/slug，从内容提取标题/修改文件/风险等级
|
||
- 实现 `classify_module(filepath)` 函数：根据 MODULE_MAP 将文件路径映射到功能模块
|
||
- 实现 `scan_audit_dir(dirpath)` 函数：扫描目录并返回 AuditEntry 列表
|
||
- _Requirements: 2.1, 2.3_
|
||
|
||
- [x] 4.2 编写属性测试：审计记录解析-渲染完整性
|
||
- **Property 1: 审计记录解析-渲染完整性**
|
||
- 使用 hypothesis 生成随机审计 Markdown 内容，验证解析+渲染后表格行包含所有必要字段
|
||
- **Validates: Requirements 2.1, 2.2**
|
||
|
||
- [x] 4.3 编写属性测试：文件路径模块分类正确性
|
||
- **Property 2: 文件路径模块分类正确性**
|
||
- 使用 hypothesis 生成随机文件路径，验证分类结果属于预定义模块集合
|
||
- **Validates: Requirements 2.3**
|
||
|
||
- [x] 4.4 实现审计一览表渲染模块
|
||
- 实现 `render_timeline_table(entries)` 函数：按时间倒序生成 Markdown 表格
|
||
- 实现 `render_module_index(entries)` 函数：按模块分组生成 Markdown 章节
|
||
- 实现 `render_dashboard(entries)` 函数：组合时间线和模块索引生成完整 dashboard
|
||
- _Requirements: 2.2, 2.3, 2.4_
|
||
|
||
- [x] 4.5 编写属性测试：审计条目时间倒序排列
|
||
- **Property 3: 审计条目时间倒序排列**
|
||
- 使用 hypothesis 生成随机日期列表，验证排序后严格非递增
|
||
- **Validates: Requirements 2.4**
|
||
|
||
- [x] 4.6 编写单元测试
|
||
- 使用真实审计文件作为测试输入验证解析正确性
|
||
- 测试边界情况：空目录、格式异常文件、缺少章节的文件
|
||
- _Requirements: 2.1, 2.3_
|
||
|
||
- [x] 4.7 实现主入口并生成 audit_dashboard.md
|
||
- 实现 `main()` 函数：扫描 → 解析 → 渲染 → 写入 `docs/audit/audit_dashboard.md`
|
||
- 运行脚本生成实际的 audit_dashboard.md 文件
|
||
- _Requirements: 2.5, 2.6_
|
||
|
||
- [x] 5. 更新文档总索引
|
||
- [x] 5.1 更新 `docs/README.md`
|
||
- 添加 `architecture/`、`business-rules/`、`operations/` 三个新目录的条目和说明
|
||
- 添加 `CHANGELOG.md` 条目
|
||
- 添加 `audit/audit_dashboard.md` 条目
|
||
- 移除过时条目（如 `data_exports/`、`templates/`、`test-json-doc/` 如果不存在）
|
||
- 确保所有一级目录都有对应链接
|
||
- _Requirements: 1.1, 1.2, 3.5_
|
||
|
||
- [x] 6. 最终检查点 — 确认所有文件完整
|
||
- 确认所有测试通过，所有文档文件已创建，审计一览表已生成，如有问题请提出。
|
||
|
||
## 备注
|
||
|
||
- 标记 `*` 的任务为可选测试任务，可跳过以加速 MVP
|
||
- 每个任务引用了具体的需求编号以便追溯
|
||
- 检查点用于增量验证
|
||
- 属性测试验证通用正确性属性，单元测试验证具体例子和边界情况
|