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

# 设计文档：文档体系整理与优化

## 概述

本设计针对飞球 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` 位置包含重定向说明