8.2 KiB
8.2 KiB
需求文档：仓库治理只读审计
简介
对飞球 ETL 系统 (etl-billiards) 仓库进行全面的只读审计分析，产出三份结构化报告：文件/目录清单（含处置建议）、项目流程树（从入口到末端逻辑）、文档对齐报告（文档与代码的映射关系）。本阶段不修改任何文件，所有处置决策留待用户逐一确认后再执行。
术语表
- 审计脚本 (Audit_Script)：执行只读分析并生成报告的 Python 脚本集合
- 文件清单 (File_Inventory)：按用途归类的仓库文件与目录列表，每项附带处置标签
- 处置标签 (Disposition_Tag)：对文件/目录的处置建议，取值为：保留、候选删除、候选归档、待确认
- 流程树 (Flow_Tree)：从程序入口出发，沿调用链展开到各子模块/子逻辑的树状结构
- 文档对齐报告 (Doc_Alignment_Report)：文档与代码之间映射关系的分析报告，包含过期点、冲突点、缺失点
- 入口 (Entry_Point)：程序的顶层启动点，如
cli/main.py、gui/main.py、scripts/*.py - ODS/DWD/DWS：数据仓库三层架构——操作数据存储层/明细数据层/数据服务层
- SCD2：缓慢变化维度类型 2，维度表的历史版本管理策略
需求
需求 1：文件与目录清单生成
用户故事： 作为项目维护者，我希望获得一份按用途归类的仓库文件与目录清单，以便了解每个文件的角色并决定其去留。
验收标准
- WHEN 审计脚本扫描仓库根目录时，THE Audit_Script SHALL 递归遍历所有文件和目录（排除
.git/、__pycache__/、.pytest_cache/等运行时缓存目录） - WHEN 审计脚本处理每个文件或目录时，THE Audit_Script SHALL 将其归入以下用途分类之一：核心代码、配置、数据库定义、测试、文档、脚本工具、GUI、构建与部署、日志与输出、临时与调试、其他
- WHEN 审计脚本完成归类后，THE Audit_Script SHALL 为每个条目分配一个处置标签（保留/候选删除/候选归档/待确认）
- WHEN 审计脚本生成清单时，THE File_Inventory SHALL 包含以下字段：相对路径、用途分类、处置标签、简要说明
- WHEN 审计脚本遇到空目录（如
database/Deleded & backup/、scripts/Deleded & backup/）时，THE Audit_Script SHALL 将其标记为"候选删除" - WHEN 审计脚本遇到
.lnk快捷方式文件或.rar压缩包时，THE Audit_Script SHALL 将其标记为"候选删除" - WHEN 审计脚本遇到
tmp/目录下的文件时，THE Audit_Script SHALL 逐一评估并标记为"候选删除"或"候选归档" - WHEN 审计脚本遇到
logs/、export/目录下的运行时产出文件时，THE Audit_Script SHALL 将其标记为"候选归档" - IF 审计脚本无法确定某文件的用途分类，THEN THE Audit_Script SHALL 将其标记为"待确认"并在说明中注明原因
- WHEN 审计脚本完成清单生成后，THE File_Inventory SHALL 以 Markdown 表格格式输出，按用途分类分组排列
需求 2：项目流程树生成
用户故事： 作为项目维护者，我希望获得一份从入口到各子模块的调用流程树，以便理解系统的执行路径和模块依赖关系。
验收标准
- WHEN 审计脚本分析项目入口时，THE Audit_Script SHALL 识别以下入口点：
cli/main.py（CLI 主入口）、gui/main.py（GUI 主入口）、scripts/*.py（运维脚本）、批处理文件（run_etl.bat、run_gui.bat、run_ods.bat等） - WHEN 审计脚本从 CLI 入口展开时，THE Flow_Tree SHALL 追踪以下调用链：CLI 参数解析 → 配置加载 → 调度器初始化 → 任务注册表查询 → 任务执行（Extract → Transform → Load）→ 加载器调用 → 数据库操作
- WHEN 审计脚本从 GUI 入口展开时，THE Flow_Tree SHALL 追踪以下调用链：GUI 主窗口初始化 → 各面板/组件加载 → 后台工作线程 → CLI 命令构建 → 任务执行
- WHEN 审计脚本分析任务模块时，THE Flow_Tree SHALL 区分以下任务类型：ODS 抓取任务、DWD 加载任务、DWS 汇总任务、校验任务、Schema 初始化任务
- WHEN 审计脚本分析加载器模块时，THE Flow_Tree SHALL 区分以下加载器类型：ODS 通用加载器、维度加载器（SCD2）、事实表加载器
- WHEN 审计脚本生成流程树时，THE Flow_Tree SHALL 以缩进文本或 Mermaid 图的形式输出，层级深度至少达到函数/方法级别
- WHEN 审计脚本分析模块依赖时，THE Flow_Tree SHALL 标注每个节点所在的源文件路径
- IF 审计脚本发现存在孤立模块（未被任何入口直接或间接引用的代码文件），THEN THE Flow_Tree SHALL 在报告末尾单独列出这些孤立模块
需求 3：文档对齐报告生成
用户故事： 作为项目维护者，我希望了解现有文档与代码之间的对齐状况，以便识别过期、冲突和缺失的文档。
验收标准
- WHEN 审计脚本扫描文档目录时，THE Audit_Script SHALL 识别以下文档来源：
docs/目录、README.md、开发笔记/、各模块内的README.md（如gui/README.md、fetch-test/README.md）、.kiro/steering/下的引导文件 - WHEN 审计脚本分析每份文档时，THE Doc_Alignment_Report SHALL 建立文档与代码模块之间的映射关系
- WHEN 审计脚本检测到文档引用了已不存在的代码实体（函数、类、文件路径）时，THE Doc_Alignment_Report SHALL 将该引用标记为"过期点"
- WHEN 审计脚本检测到文档描述与代码实际行为不一致时，THE Doc_Alignment_Report SHALL 将该处标记为"冲突点"
- WHEN 审计脚本检测到核心代码模块缺少对应文档时，THE Doc_Alignment_Report SHALL 将该模块标记为"缺失点"
- WHEN 审计脚本分析 DDL 文件（
database/schema_*.sql）时，THE Doc_Alignment_Report SHALL 检查数据字典文档（docs/dwd_main_tables_dictionary.md、docs/dws_tables_dictionary.md）是否覆盖了所有表和字段 - WHEN 审计脚本分析
docs/test-json-doc/下的 API 响应样本时，THE Doc_Alignment_Report SHALL 检查样本字段是否与 ODS 表结构和解析器（models/parsers.py）一致 - WHEN 审计脚本完成分析后，THE Doc_Alignment_Report SHALL 以 Markdown 格式输出，包含以下分区：映射关系表、过期点列表、冲突点列表、缺失点列表
需求 4：报告输出与格式规范
用户故事： 作为项目维护者，我希望审计报告以统一、可读的格式输出，以便后续逐项决策和执行。
验收标准
- THE Audit_Script SHALL 将三份报告输出到
docs/audit/repo/目录下，文件名分别为file_inventory.md、flow_tree.md、doc_alignment.md - THE Audit_Script SHALL 在每份报告的头部包含生成时间戳和仓库根目录路径
- WHEN 报告引用代码标识符（类名、函数名、变量名、文件路径）时，THE Audit_Script SHALL 保留英文原文，使用行内代码格式（反引号）
- WHEN 报告包含说明性文字时，THE Audit_Script SHALL 使用简体中文
- THE Audit_Script SHALL 在文件清单报告末尾附加统计摘要：各用途分类的文件数量、各处置标签的文件数量
- THE Audit_Script SHALL 在流程树报告末尾附加统计摘要：入口点数量、任务数量、加载器数量、孤立模块数量
- THE Audit_Script SHALL 在文档对齐报告末尾附加统计摘要：过期点数量、冲突点数量、缺失点数量
需求 5：只读安全保障
用户故事： 作为项目维护者，我希望审计过程不会修改仓库中的任何文件，以确保分析阶段的安全性。
验收标准
- THE Audit_Script SHALL 仅执行文件系统的读取操作（读取文件内容、列出目录、获取文件元信息）
- THE Audit_Script SHALL 仅在
docs/audit/repo/目录下创建新文件，该目录为报告专用输出目录 - IF 审计脚本在执行过程中遇到权限错误或文件读取失败，THEN THE Audit_Script SHALL 在报告中记录该错误并继续处理其余文件
- THE Audit_Script SHALL 在运行前检查
docs/audit/repo/目录是否存在，若不存在则创建该目录