Neo-ZQYY/.kiro/specs/docs-optimization/tasks.md

实施计划：文档体系整理与优化

概述

基于设计文档，将实施分为四个阶段：新增文档目录与骨架文件、业务规则文档迁移、审计一览表生成脚本开发、文档总索引更新。所有任务聚焦于文件创建/修改和 Python 脚本编写。

任务

• 1. 新增文档目录与骨架文件

  • 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

  • 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

  • 1.3 创建 docs/CHANGELOG.md

    • 基于 docs/audit/changes/ 中的审计记录，整理项目级版本变更历史
    • 包含日期、变更摘要和影响范围
    • Requirements: 1.6

• 2. 业务规则文档迁移与目录建设

  • 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

  • 2.2 创建业务规则骨架文档

    • 创建 docs/business-rules/dws_metrics.md（DWS 口径定义骨架）
    • 创建 docs/business-rules/scd2_rules.md（SCD2 处理规则骨架）
    • Requirements: 3.4

• 3. 检查点 — 确认文档目录结构正确

  • 确认所有新增目录和文件已创建，如有问题请提出。

• 4. 审计一览表生成脚本

  • 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

  • 4.2 编写属性测试：审计记录解析-渲染完整性

    • Property 1: 审计记录解析-渲染完整性
    • 使用 hypothesis 生成随机审计 Markdown 内容，验证解析+渲染后表格行包含所有必要字段
    • Validates: Requirements 2.1, 2.2

  • 4.3 编写属性测试：文件路径模块分类正确性

    • Property 2: 文件路径模块分类正确性
    • 使用 hypothesis 生成随机文件路径，验证分类结果属于预定义模块集合
    • Validates: Requirements 2.3

  • 4.4 实现审计一览表渲染模块

    • 实现 render_timeline_table(entries) 函数：按时间倒序生成 Markdown 表格
    • 实现 render_module_index(entries) 函数：按模块分组生成 Markdown 章节
    • 实现 render_dashboard(entries) 函数：组合时间线和模块索引生成完整 dashboard
    • Requirements: 2.2, 2.3, 2.4

  • 4.5 编写属性测试：审计条目时间倒序排列

    • Property 3: 审计条目时间倒序排列
    • 使用 hypothesis 生成随机日期列表，验证排序后严格非递增
    • Validates: Requirements 2.4

  • 4.6 编写单元测试

    • 使用真实审计文件作为测试输入验证解析正确性
    • 测试边界情况：空目录、格式异常文件、缺少章节的文件
    • Requirements: 2.1, 2.3

  • 4.7 实现主入口并生成 audit_dashboard.md

    • 实现 main() 函数：扫描 → 解析 → 渲染 → 写入 docs/audit/audit_dashboard.md
    • 运行脚本生成实际的 audit_dashboard.md 文件
    • Requirements: 2.5, 2.6

• 5. 更新文档总索引

  • 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

• 6. 最终检查点 — 确认所有文件完整

  • 确认所有测试通过，所有文档文件已创建，审计一览表已生成，如有问题请提出。

备注

• 标记 * 的任务为可选测试任务，可跳过以加速 MVP
• 每个任务引用了具体的需求编号以便追溯
• 检查点用于增量验证
• 属性测试验证通用正确性属性，单元测试验证具体例子和边界情况