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