init: 项目初始提交 - NeoZQYY Monorepo 完整代码

2026-02-15 14:58:14 +08:00
commit ded6dfb9d8
769 changed files with 182616 additions and 0 deletions
--- a/.kiro/specs/docs-optimization/.config.kiro
+++ b/.kiro/specs/docs-optimization/.config.kiro
@@ -0,0 +1 @@
+{"generationMode": "requirements-first"}
--- a/.kiro/specs/docs-optimization/design.md
+++ b/.kiro/specs/docs-optimization/design.md
@@ -0,0 +1,229 @@
+# 设计文档：文档体系整理与优化
+
+## 概述
+
+本设计针对飞球 ETL 系统的 `docs/` 目录进行结构性优化，包含三个核心工作流：
+
+1. **文档覆盖度补充**：新增 `architecture/`、`business-rules/`、`operations/` 三个缺失目录及骨架文档，新增项目级 `CHANGELOG.md`，更新文档总索引
+2. **审计一览表生成**：编写 Python 脚本解析 `docs/audit/changes/` 下的审计源记录，生成结构化的 `audit_dashboard.md` 汇总视图
+3. **业务规则文档迁移**：将 `index_algorithm_cn.md` 从 `docs/database/DWS/` 迁移至 `docs/business-rules/`，原位置保留重定向说明
+
+## 架构
+
+### 文档目录结构（目标状态）
+
+```
+docs/
+├── README.md                      ← 文档总索引（更新）
+├── CHANGELOG.md                   ← 新增：项目级变更日志
+├── architecture/                  ← 新增：架构设计文档
+│   ├── README.md                  ←   目录索引
+│   ├── system_overview.md         ←   系统整体架构
+│   └── data_flow.md               ←   数据流向详解
+├── business-rules/                ← 新增：业务规则文档
+│   ├── README.md                  ←   目录索引
+│   ├── index_algorithm_cn.md      ←   迁移自 database/DWS/
+│   ├── dws_metrics.md             ←   DWS 口径定义（骨架）
+│   └── scd2_rules.md              ←   SCD2 处理规则（骨架）
+├── operations/                    ← 新增：运维文档
+│   ├── README.md                  ←   目录索引
+│   ├── environment_setup.md       ←   环境搭建指南
+│   ├── scheduling.md              ←   调度配置说明
+│   └── troubleshooting.md         ←   故障排查手册
+├── audit/
+│   ├── audit_dashboard.md         ← 新增：审计一览表
+│   ├── changes/                   ←   审计源记录（不变）
+│   └── ...
+├── api-reference/                 ← 不变
+├── database/                      ← 不变（移除 index_algorithm_cn.md）
+├── etl_tasks/                     ← 不变
+├── reports/                       ← 不变
+└── requirements/                  ← 不变
+```
+
+### 审计一览表生成流程
+
+```mermaid
+graph LR
+    A["docs/audit/changes/*.md"] -->|Python 脚本解析| B["结构化数据列表"]
+    B -->|按时间倒序排列| C["时间线视图"]
+    B -->|按模块分类| D["模块索引视图"]
+    C --> E["audit_dashboard.md"]
+    D --> E
+```
+
+## 组件与接口
+
+### 组件 1：审计一览表生成脚本
+
+- 路径：`scripts/gen_audit_dashboard.py`
+- 职责：扫描 `docs/audit/changes/` 目录，解析每个 Markdown 文件，提取结构化信息，生成 `docs/audit/audit_dashboard.md`
+- 入口：`python scripts/gen_audit_dashboard.py`
+
+#### 解析逻辑
+
+脚本需要从审计源记录中提取以下字段：
+
+| 字段 | 提取方式 |
+|------|----------|
+| 日期 | 从文件名前缀 `YYYY-MM-DD` 提取 |
+| 标题/需求摘要 | 从 Markdown 一级标题 `# ...` 提取 |
+| slug | 从文件名 `__` 后的部分提取 |
+| 修改文件列表 | 从"修改文件清单"或"文件清单"章节的表格/列表中提取 |
+| 影响模块 | 根据修改文件路径推断所属模块（api/、tasks/、docs/ 等） |
+| 变更类型 | 从文件内容中提取（bugfix/新增/修改/删除/文档） |
+| 风险等级 | 从"风险点"章节推断（高/中/低/极低） |
+
+#### 模块分类规则
+
+根据修改文件路径前缀映射到功能模块：
+
+```python
+MODULE_MAP = {
+    "api/": "API 层",
+    "tasks/ods": "ODS 层",
+    "tasks/dwd": "DWD 层",
+    "tasks/dws": "DWS 层",
+    "tasks/index": "指数算法",
+    "loaders/": "数据装载",
+    "database/": "数据库",
+    "orchestration/": "调度",
+    "config/": "配置",
+    "cli/": "CLI",
+    "models/": "模型",
+    "scd/": "SCD2",
+    "docs/": "文档",
+    "scripts/": "脚本工具",
+    "tests/": "测试",
+    "quality/": "质量校验",
+    "gui/": "GUI",
+    "utils/": "工具库",
+}
+```
+
+### 组件 2：静态文档文件
+
+纯 Markdown 文件，无代码逻辑。包括：
+- 架构文档（`docs/architecture/`）
+- 业务规则文档（`docs/business-rules/`）
+- 运维文档（`docs/operations/`）
+- 变更日志（`docs/CHANGELOG.md`）
+- 更新后的文档总索引（`docs/README.md`）
+
+### 组件 3：文件迁移与重定向
+
+- 将 `docs/database/DWS/index_algorithm_cn.md` 内容迁移至 `docs/business-rules/index_algorithm_cn.md`
+- 在原位置 `docs/database/DWS/index_algorithm_cn.md` 替换为重定向说明
+
+## 数据模型
+
+### 审计记录解析结构
+
+```python
+@dataclass
+class AuditEntry:
+    """从单个审计源记录文件解析出的结构化数据"""
+    date: str                    # YYYY-MM-DD，从文件名提取
+    slug: str                    # 文件名中 __ 后的标识符
+    title: str                   # Markdown 一级标题
+    filename: str                # 源文件名（不含路径）
+    changed_files: list[str]     # 修改的文件路径列表
+    modules: set[str]            # 影响的功能模块集合
+    risk_level: str              # 风险等级：高/中/低/极低
+    change_type: str             # 变更类型：bugfix/功能/文档/重构/清理
+```
+
+### 审计一览表输出格式
+
+`audit_dashboard.md` 包含两个视图：
+
+1. **时间线视图**（按日期倒序）：
+
+```markdown
+| 日期 | 需求摘要 | 变更类型 | 影响模块 | 风险 | 详情 |
+|------|----------|----------|----------|------|------|
+| 2026-02-15 | docs/database 合并 | 重构 | 文档, 脚本工具 | 极低 | [链接](changes/...) |
+```
+
+2. **模块索引视图**（按模块分组）：
+
+```markdown
+### API 层
+| 日期 | 需求摘要 | 变更类型 | 风险 | 详情 |
+...
+
+### DWS 层
+| 日期 | 需求摘要 | 变更类型 | 风险 | 详情 |
+...
+```
+
+
+## 正确性属性
+
+*正确性属性是一种在系统所有合法执行路径上都应成立的特征或行为——本质上是对"系统应该做什么"的形式化陈述。属性是连接人类可读规格说明与机器可验证正确性保证之间的桥梁。*
+
+本特性中，大部分需求涉及静态文档文件的创建和目录组织，属于例子级别的验证（文件是否存在、内容是否包含特定条目）。可提取为通用属性的集中在审计一览表生成脚本的解析、分类和排序逻辑。
+
+### Property 1：审计记录解析-渲染完整性
+
+*For any* 格式合规的审计源记录 Markdown 文件（包含一级标题、日期行、修改文件清单章节），解析后生成的表格行应包含：日期、需求摘要、变更类型、影响模块和源文件链接。
+
+**Validates: Requirements 2.1, 2.2**
+
+### Property 2：文件路径模块分类正确性
+
+*For any* 文件路径字符串，模块分类函数的返回值应属于预定义的模块名称集合（API 层、ODS 层、DWD 层、DWS 层、指数算法、数据装载、数据库、调度、配置、CLI、模型、SCD2、文档、脚本工具、测试、质量校验、GUI、工具库、其他）。
+
+**Validates: Requirements 2.3**
+
+### Property 3：审计条目时间倒序排列
+
+*For any* 一组审计条目列表，经过排序函数处理后，输出列表中每个条目的日期应大于等于其后续条目的日期（严格非递增序）。
+
+**Validates: Requirements 2.4**
+
+## 错误处理
+
+### 审计记录解析容错
+
+| 场景 | 处理方式 |
+|------|----------|
+| 审计文件缺少一级标题 | 使用文件名 slug 作为标题替代 |
+| 审计文件缺少"修改文件清单"章节 | `changed_files` 返回空列表，`modules` 标记为 `{"其他"}` |
+| 审计文件名不符合 `YYYY-MM-DD__slug.md` 格式 | 跳过该文件，输出警告日志 |
+| 审计文件编码非 UTF-8 | 尝试 UTF-8 解码，失败则跳过并警告 |
+| `docs/audit/changes/` 目录为空 | 生成空的 dashboard 文件，包含"暂无审计记录"提示 |
+
+### 文件迁移容错
+
+| 场景 | 处理方式 |
+|------|----------|
+| `index_algorithm_cn.md` 源文件不存在 | 脚本报错退出，提示文件路径 |
+| 目标目录 `docs/business-rules/` 已存在同名文件 | 提示用户确认是否覆盖 |
+
+## 测试策略
+
+### 测试框架
+
+- 单元测试：`pytest`
+- 属性测试：`hypothesis`（Python 属性测试库）
+- 测试目录：`tests/unit/test_gen_audit_dashboard.py`
+
+### 属性测试
+
+每个正确性属性对应一个 `hypothesis` 属性测试，最少运行 100 次迭代：
+
+- **Property 1**：生成随机的审计 Markdown 内容（包含标题、日期、文件清单），验证解析+渲染后的表格行包含所有必要字段
+  - Tag: `Feature: docs-optimization, Property 1: 审计记录解析-渲染完整性`
+- **Property 2**：生成随机的文件路径字符串，验证分类结果属于预定义模块集合
+  - Tag: `Feature: docs-optimization, Property 2: 文件路径模块分类正确性`
+- **Property 3**：生成随机的日期列表构造审计条目，验证排序后严格非递增
+  - Tag: `Feature: docs-optimization, Property 3: 审计条目时间倒序排列`
+
+### 单元测试
+
+- 解析真实审计记录文件的具体例子（使用项目中已有的审计文件作为测试输入）
+- 边界情况：空目录、格式异常文件、缺少章节的文件
+- 文件存在性检查：验证所有新增目录和文件已创建
+- 文档总索引完整性：验证 `docs/README.md` 包含所有一级目录条目
+- 重定向文件验证：验证原 `index_algorithm_cn.md` 位置包含重定向说明
--- a/.kiro/specs/docs-optimization/requirements.md
+++ b/.kiro/specs/docs-optimization/requirements.md
@@ -0,0 +1,56 @@
+# 需求文档：文档体系整理与优化
+
+## 简介
+
+对飞球 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 的条目和说明
--- a/.kiro/specs/docs-optimization/tasks.md
+++ b/.kiro/specs/docs-optimization/tasks.md
@@ -0,0 +1,100 @@
+# 实施计划：文档体系整理与优化
+
+## 概述
+
+基于设计文档，将实施分为四个阶段：新增文档目录与骨架文件、业务规则文档迁移、审计一览表生成脚本开发、文档总索引更新。所有任务聚焦于文件创建/修改和 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
+- 每个任务引用了具体的需求编号以便追溯
+- 检查点用于增量验证
+- 属性测试验证通用正确性属性，单元测试验证具体例子和边界情况