57 lines
4.0 KiB
Markdown
57 lines
4.0 KiB
Markdown
# 需求文档：文档体系整理与优化
|
||
|
||
## 简介
|
||
|
||
对飞球 ETL 系统（etl-billiards）的 `docs/` 目录进行文档体系整理与优化，涵盖三个核心诉求：文档覆盖度评估与缺失类别补充、审计一览表生成、业务规则文档独立目录建设。目标是让项目文档从宏观架构到微观实现形成完整闭环，同时提供可快速检索的审计变更视图。
|
||
|
||
## 术语表
|
||
|
||
- **文档总索引（Docs_Index）**：`docs/README.md`，项目文档的统一入口与导航页
|
||
- **审计一览表（Audit_Dashboard）**：基于 `docs/audit/changes/` 源数据生成的汇总视图文件
|
||
- **审计源记录（Audit_Record）**：`docs/audit/changes/` 目录下的单个审计 Markdown 文件
|
||
- **业务规则文档目录（Business_Rules_Dir）**：`docs/business-rules/`，存放指数算法、DWS 口径定义、SCD2 规则等业务逻辑文档
|
||
- **架构设计文档目录（Architecture_Dir）**：`docs/architecture/`，存放系统整体架构、数据流、模块交互等设计文档
|
||
- **运维文档目录（Operations_Dir）**：`docs/operations/`，存放环境搭建、调度配置、故障排查等运维指南
|
||
- **变更日志（Changelog）**：`docs/CHANGELOG.md`，项目级版本变更历史记录
|
||
- **指数算法文档（Index_Algorithm_Doc）**：当前位于 `docs/database/DWS/index_algorithm_cn.md` 的指数算法说明文件
|
||
|
||
## 需求
|
||
|
||
### 需求 1：文档覆盖度评估与缺失类别补充
|
||
|
||
**用户故事：** 作为项目开发者，我希望文档体系涵盖从宏观架构到微观实现的完整说明，以便新成员快速上手、现有成员高效查阅。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE Docs_Index SHALL 包含指向所有一级文档目录的链接和简要说明
|
||
2. WHEN 新增文档目录时，THE Docs_Index SHALL 同步更新对应的目录条目和说明
|
||
3. THE Architecture_Dir SHALL 包含系统整体架构文档，涵盖数据流向图（ODS→DWD→DWS）、模块交互关系和技术栈说明
|
||
4. THE Business_Rules_Dir SHALL 包含独立的业务规则与算法文档目录，与数据库表结构文档分离
|
||
5. THE Operations_Dir SHALL 包含环境搭建指南、调度配置说明和常见故障排查手册
|
||
6. THE Changelog SHALL 记录项目级版本变更历史，包含日期、变更摘要和影响范围
|
||
|
||
### 需求 2：审计一览表生成
|
||
|
||
**用户故事：** 作为项目管理者，我希望基于审计源记录生成一个汇总视图，以便一眼了解项目的修改痕迹并按功能模块检索。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE Audit_Dashboard SHALL 从 Audit_Record 文件中提取日期、需求摘要、修改内容和影响范围信息
|
||
2. THE Audit_Dashboard SHALL 以表格形式展示每条审计记录的时间日期、用户需求摘要、修改/新增/删除的内容概要和对项目的影响
|
||
3. THE Audit_Dashboard SHALL 提供按功能模块分类的索引（如 API 层、ODS 层、DWD 层、DWS 层、文档、基础设施）
|
||
4. THE Audit_Dashboard SHALL 提供按时间倒序排列的完整变更列表
|
||
5. WHEN 新的 Audit_Record 被添加到 `docs/audit/changes/` 时，THE Audit_Dashboard SHALL 通过手动重新生成的方式保持同步
|
||
6. THE Audit_Dashboard SHALL 存放于 `docs/audit/` 目录下，文件名为 `audit_dashboard.md`
|
||
|
||
### 需求 3：业务规则文档独立目录
|
||
|
||
**用户故事：** 作为项目开发者，我希望业务规则和算法文档有独立的存放目录，以便与数据库表结构文档清晰分离，方便查阅和维护。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE Business_Rules_Dir SHALL 作为独立目录存在于 `docs/business-rules/` 路径下
|
||
2. WHEN Index_Algorithm_Doc 从 `docs/database/DWS/` 迁移至 Business_Rules_Dir 时，THE 原路径 SHALL 保留一个指向新位置的重定向说明
|
||
3. THE Business_Rules_Dir SHALL 包含目录级 README 文件，列出所有业务规则文档的索引
|
||
4. THE Business_Rules_Dir SHALL 按业务域组织文档（如指数算法、DWS 口径定义、SCD2 规则、薪酬计算规则）
|
||
5. THE Docs_Index SHALL 包含 Business_Rules_Dir 的条目和说明
|