425 lines
16 KiB
Markdown
425 lines
16 KiB
Markdown
# 设计文档：仓库治理只读审计
|
||
|
||
## 概述
|
||
|
||
本设计描述三个 Python 审计脚本的实现方案，用于对 etl-billiards 仓库进行只读分析并生成三份 Markdown 报告。脚本仅读取文件系统和源代码，不连接数据库、不修改任何现有文件，仅在 `docs/audit/repo/` 目录下输出报告。
|
||
|
||
审计脚本采用模块化设计：一个共享的仓库扫描器负责遍历文件系统，三个独立的分析器分别生成文件清单、流程树和文档对齐报告。
|
||
|
||
## 架构
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[scripts/audit/run_audit.py<br/>审计主入口] --> B[scripts/audit/scanner.py<br/>仓库扫描器]
|
||
A --> C[scripts/audit/inventory_analyzer.py<br/>文件清单分析器]
|
||
A --> D[scripts/audit/flow_analyzer.py<br/>流程树分析器]
|
||
A --> E[scripts/audit/doc_alignment_analyzer.py<br/>文档对齐分析器]
|
||
|
||
B --> F[文件系统<br/>只读遍历]
|
||
C --> G[docs/audit/repo/file_inventory.md]
|
||
D --> H[docs/audit/repo/flow_tree.md]
|
||
E --> I[docs/audit/repo/doc_alignment.md]
|
||
|
||
C --> B
|
||
D --> B
|
||
E --> B
|
||
```
|
||
|
||
### 执行流程
|
||
|
||
1. `run_audit.py` 作为主入口，初始化扫描器并依次调用三个分析器
|
||
2. `scanner.py` 递归遍历仓库，构建文件元信息列表（路径、大小、类型）
|
||
3. 各分析器接收扫描结果，执行各自的分析逻辑，输出 Markdown 报告
|
||
4. 所有报告写入 `docs/audit/repo/` 目录
|
||
|
||
## 组件与接口
|
||
|
||
### 1. 仓库扫描器 (`scripts/audit/scanner.py`)
|
||
|
||
负责递归遍历仓库文件系统，返回结构化的文件元信息。
|
||
|
||
```python
|
||
@dataclass
|
||
class FileEntry:
|
||
"""单个文件/目录的元信息"""
|
||
rel_path: str # 相对于仓库根目录的路径
|
||
is_dir: bool # 是否为目录
|
||
size_bytes: int # 文件大小（目录为 0）
|
||
extension: str # 文件扩展名（小写，含点号）
|
||
is_empty_dir: bool # 是否为空目录
|
||
|
||
EXCLUDED_PATTERNS: list[str] = [
|
||
".git", "__pycache__", ".pytest_cache",
|
||
"*.pyc", ".kiro",
|
||
]
|
||
|
||
def scan_repo(root: Path, exclude: list[str] = EXCLUDED_PATTERNS) -> list[FileEntry]:
|
||
"""递归扫描仓库，返回所有文件和目录的元信息列表"""
|
||
...
|
||
```
|
||
|
||
### 2. 文件清单分析器 (`scripts/audit/inventory_analyzer.py`)
|
||
|
||
对扫描结果进行用途分类和处置标签分配。
|
||
|
||
```python
|
||
# 用途分类枚举
|
||
class Category(str, Enum):
|
||
CORE_CODE = "核心代码"
|
||
CONFIG = "配置"
|
||
DATABASE_DEF = "数据库定义"
|
||
TEST = "测试"
|
||
DOCS = "文档"
|
||
SCRIPTS = "脚本工具"
|
||
GUI = "GUI"
|
||
BUILD_DEPLOY = "构建与部署"
|
||
LOG_OUTPUT = "日志与输出"
|
||
TEMP_DEBUG = "临时与调试"
|
||
OTHER = "其他"
|
||
|
||
# 处置标签枚举
|
||
class Disposition(str, Enum):
|
||
KEEP = "保留"
|
||
CANDIDATE_DELETE = "候选删除"
|
||
CANDIDATE_ARCHIVE = "候选归档"
|
||
NEEDS_REVIEW = "待确认"
|
||
|
||
@dataclass
|
||
class InventoryItem:
|
||
"""清单条目"""
|
||
rel_path: str
|
||
category: Category
|
||
disposition: Disposition
|
||
description: str
|
||
|
||
def classify(entry: FileEntry) -> InventoryItem:
|
||
"""根据路径、扩展名等规则对单个文件/目录进行分类和标签分配"""
|
||
...
|
||
|
||
def build_inventory(entries: list[FileEntry]) -> list[InventoryItem]:
|
||
"""批量分类所有文件条目"""
|
||
...
|
||
|
||
def render_inventory_report(items: list[InventoryItem], repo_root: str) -> str:
|
||
"""生成 Markdown 格式的文件清单报告"""
|
||
...
|
||
```
|
||
|
||
**分类规则（按优先级从高到低）**：
|
||
|
||
| 路径模式 | 用途分类 | 默认处置 |
|
||
|---------|---------|---------|
|
||
| `tmp/` 下所有文件 | 临时与调试 | 候选删除/候选归档 |
|
||
| `logs/`、`export/` 下的运行时产出 | 日志与输出 | 候选归档 |
|
||
| `*.lnk`、`*.rar` 文件 | 其他 | 候选删除 |
|
||
| 空目录（如 `Deleded & backup/`） | 其他 | 候选删除 |
|
||
| `tasks/`、`loaders/`、`scd/`、`orchestration/`、`quality/`、`models/`、`utils/`、`api/` | 核心代码 | 保留 |
|
||
| `config/` | 配置 | 保留 |
|
||
| `database/*.sql`、`database/migrations/` | 数据库定义 | 保留 |
|
||
| `database/*.py` | 核心代码 | 保留 |
|
||
| `tests/` | 测试 | 保留 |
|
||
| `docs/` | 文档 | 保留 |
|
||
| `scripts/` 下的 `.py` 文件 | 脚本工具 | 保留/待确认 |
|
||
| `gui/` | GUI | 保留 |
|
||
| `setup.py`、`build_exe.py`、`*.bat`、`*.sh`、`*.ps1` | 构建与部署 | 保留 |
|
||
| 根目录散落文件（`Prompt用.md`、`Untitled`、`fix_symbols.py` 等） | 其他 | 待确认 |
|
||
|
||
### 3. 流程树分析器 (`scripts/audit/flow_analyzer.py`)
|
||
|
||
通过静态分析 Python 源码的 `import` 语句和类继承关系，构建从入口到末端模块的调用树。
|
||
|
||
```python
|
||
@dataclass
|
||
class FlowNode:
|
||
"""流程树节点"""
|
||
name: str # 节点名称（模块名/类名/函数名）
|
||
source_file: str # 所在源文件路径
|
||
node_type: str # 类型：entry/module/class/function
|
||
children: list["FlowNode"]
|
||
|
||
def parse_imports(filepath: Path) -> list[str]:
|
||
"""使用 ast 模块解析 Python 文件的 import 语句，返回被导入的本地模块列表"""
|
||
...
|
||
|
||
def build_flow_tree(repo_root: Path, entry_file: str) -> FlowNode:
|
||
"""从指定入口文件出发，递归追踪 import 链，构建流程树"""
|
||
...
|
||
|
||
def find_orphan_modules(repo_root: Path, all_entries: list[FileEntry], reachable: set[str]) -> list[str]:
|
||
"""找出未被任何入口直接或间接引用的 Python 模块"""
|
||
...
|
||
|
||
def render_flow_report(trees: list[FlowNode], orphans: list[str], repo_root: str) -> str:
|
||
"""生成 Markdown 格式的流程树报告（含 Mermaid 图和缩进文本）"""
|
||
...
|
||
```
|
||
|
||
**入口点识别**：
|
||
- CLI 入口：`cli/main.py` → `main()` 函数
|
||
- GUI 入口：`gui/main.py` → `main()` 函数
|
||
- 批处理入口：`run_etl.bat`、`run_gui.bat`、`run_ods.bat` → 解析其中的 `python` 命令
|
||
- 运维脚本：`scripts/*.py` → 各自的 `if __name__ == "__main__"` 块
|
||
|
||
**静态分析策略**：
|
||
- 使用 Python `ast` 模块解析源文件，提取 `import` 和 `from ... import` 语句
|
||
- 仅追踪项目内部模块（排除标准库和第三方包）
|
||
- 通过 `orchestration/task_registry.py` 的注册语句识别所有任务类及其源文件
|
||
- 通过类继承关系（`BaseTask`、`BaseLoader`、`BaseDwsTask` 等）识别任务和加载器层级
|
||
|
||
### 4. 文档对齐分析器 (`scripts/audit/doc_alignment_analyzer.py`)
|
||
|
||
检查文档与代码之间的映射关系、过期点、冲突点和缺失点。
|
||
|
||
```python
|
||
@dataclass
|
||
class DocMapping:
|
||
"""文档与代码的映射关系"""
|
||
doc_path: str # 文档文件路径
|
||
doc_topic: str # 文档主题
|
||
related_code: list[str] # 关联的代码文件/模块
|
||
status: str # 状态：aligned/stale/conflict/orphan
|
||
|
||
@dataclass
|
||
class AlignmentIssue:
|
||
"""对齐问题"""
|
||
doc_path: str
|
||
issue_type: str # stale/conflict/missing
|
||
description: str
|
||
related_code: str
|
||
|
||
def scan_docs(repo_root: Path) -> list[str]:
|
||
"""扫描所有文档文件路径"""
|
||
...
|
||
|
||
def extract_code_references(doc_path: Path) -> list[str]:
|
||
"""从文档中提取代码引用（文件路径、类名、函数名、表名等）"""
|
||
...
|
||
|
||
def check_reference_validity(ref: str, repo_root: Path) -> bool:
|
||
"""检查文档中的代码引用是否仍然有效"""
|
||
...
|
||
|
||
def find_undocumented_modules(repo_root: Path, documented: set[str]) -> list[str]:
|
||
"""找出缺少文档的核心代码模块"""
|
||
...
|
||
|
||
def check_ddl_vs_dictionary(repo_root: Path) -> list[AlignmentIssue]:
|
||
"""比对 DDL 文件与数据字典文档的覆盖度"""
|
||
...
|
||
|
||
def check_api_samples_vs_parsers(repo_root: Path) -> list[AlignmentIssue]:
|
||
"""比对 API 响应样本与 ODS 表结构/解析器的一致性"""
|
||
...
|
||
|
||
def render_alignment_report(mappings: list[DocMapping], issues: list[AlignmentIssue], repo_root: str) -> str:
|
||
"""生成 Markdown 格式的文档对齐报告"""
|
||
...
|
||
```
|
||
|
||
**文档来源识别**：
|
||
- `docs/` 目录下的 `.md`、`.txt`、`.csv` 文件
|
||
- 根目录的 `README.md`
|
||
- `开发笔记/` 目录
|
||
- 各模块内的 `README.md`（`gui/README.md`、`fetch-test/README.md`）
|
||
- `.kiro/steering/` 下的引导文件
|
||
- `docs/test-json-doc/` 下的 API 响应样本及分析文档
|
||
|
||
**对齐检查策略**：
|
||
- 过期点检测：文档中引用的文件路径、类名、函数名在代码中已不存在
|
||
- 冲突点检测：DDL 中的表/字段定义与数据字典文档不一致；API 样本字段与解析器不匹配
|
||
- 缺失点检测：核心代码模块（`tasks/`、`loaders/`、`orchestration/` 等）缺少对应文档
|
||
|
||
### 5. 审计主入口 (`scripts/audit/run_audit.py`)
|
||
|
||
```python
|
||
def run_audit(repo_root: Path | None = None) -> None:
|
||
"""执行完整审计流程，生成三份报告到 docs/audit/"""
|
||
...
|
||
|
||
if __name__ == "__main__":
|
||
run_audit()
|
||
```
|
||
|
||
## 数据模型
|
||
|
||
### FileEntry（文件元信息）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `rel_path` | `str` | 相对路径 |
|
||
| `is_dir` | `bool` | 是否为目录 |
|
||
| `size_bytes` | `int` | 文件大小 |
|
||
| `extension` | `str` | 扩展名 |
|
||
| `is_empty_dir` | `bool` | 是否为空目录 |
|
||
|
||
### InventoryItem（清单条目）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `rel_path` | `str` | 相对路径 |
|
||
| `category` | `Category` | 用途分类 |
|
||
| `disposition` | `Disposition` | 处置标签 |
|
||
| `description` | `str` | 简要说明 |
|
||
|
||
### FlowNode（流程树节点）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `name` | `str` | 节点名称 |
|
||
| `source_file` | `str` | 源文件路径 |
|
||
| `node_type` | `str` | 节点类型 |
|
||
| `children` | `list[FlowNode]` | 子节点列表 |
|
||
|
||
### DocMapping / AlignmentIssue（文档对齐）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `doc_path` | `str` | 文档路径 |
|
||
| `doc_topic` / `issue_type` | `str` | 主题/问题类型 |
|
||
| `related_code` | `list[str]` / `str` | 关联代码 |
|
||
| `status` / `description` | `str` | 状态/描述 |
|
||
|
||
|
||
## 正确性属性
|
||
|
||
*属性（Property）是指在系统所有合法执行路径上都应成立的特征或行为——本质上是对"系统应该做什么"的形式化陈述。属性是连接人类可读规格说明与机器可验证正确性保证之间的桥梁。*
|
||
|
||
### Property 1: classify 完整性
|
||
|
||
*对于任意* `FileEntry`，`classify` 函数返回的 `InventoryItem` 的 `category` 字段应属于 `Category` 枚举，`disposition` 字段应属于 `Disposition` 枚举，且 `description` 字段为非空字符串。
|
||
|
||
**Validates: Requirements 1.2, 1.3**
|
||
|
||
### Property 2: 清单渲染完整性
|
||
|
||
*对于任意* `InventoryItem` 列表，`render_inventory_report` 生成的 Markdown 文本中，每个条目对应的行应包含该条目的 `rel_path`、`category.value`、`disposition.value` 和 `description` 四个字段。
|
||
|
||
**Validates: Requirements 1.4**
|
||
|
||
### Property 3: 空目录标记为候选删除
|
||
|
||
*对于任意* `is_empty_dir=True` 的 `FileEntry`，`classify` 返回的 `disposition` 应为 `Disposition.CANDIDATE_DELETE`。
|
||
|
||
**Validates: Requirements 1.5**
|
||
|
||
### Property 4: .lnk/.rar 文件标记为候选删除
|
||
|
||
*对于任意* 扩展名为 `.lnk` 或 `.rar` 的 `FileEntry`，`classify` 返回的 `disposition` 应为 `Disposition.CANDIDATE_DELETE`。
|
||
|
||
**Validates: Requirements 1.6**
|
||
|
||
### Property 5: tmp/ 下文件处置范围
|
||
|
||
*对于任意* `rel_path` 以 `tmp/` 开头的 `FileEntry`，`classify` 返回的 `disposition` 应为 `Disposition.CANDIDATE_DELETE` 或 `Disposition.CANDIDATE_ARCHIVE` 之一。
|
||
|
||
**Validates: Requirements 1.7**
|
||
|
||
### Property 6: 运行时产出目录标记为候选归档
|
||
|
||
*对于任意* `rel_path` 以 `logs/` 或 `export/` 开头且非 `__init__.py` 的 `FileEntry`，`classify` 返回的 `disposition` 应为 `Disposition.CANDIDATE_ARCHIVE`。
|
||
|
||
**Validates: Requirements 1.8**
|
||
|
||
### Property 7: 扫描器排除规则
|
||
|
||
*对于任意* 文件树，`scan_repo` 返回的 `FileEntry` 列表中不应包含 `rel_path` 匹配排除模式（`.git`、`__pycache__`、`.pytest_cache`）的条目。
|
||
|
||
**Validates: Requirements 1.1**
|
||
|
||
### Property 8: 清单按分类分组
|
||
|
||
*对于任意* `InventoryItem` 列表，`render_inventory_report` 生成的 Markdown 中，同一 `Category` 的条目应连续出现（即按分类分组排列）。
|
||
|
||
**Validates: Requirements 1.10**
|
||
|
||
### Property 9: 流程树节点 source_file 有效性
|
||
|
||
*对于任意* `FlowNode` 树中的节点，`source_file` 字段应为非空字符串，且对应的文件在仓库中实际存在。
|
||
|
||
**Validates: Requirements 2.7**
|
||
|
||
### Property 10: 孤立模块检测正确性
|
||
|
||
*对于任意* 文件集合和可达模块集合，`find_orphan_modules` 返回的孤立模块列表中的每个模块都不应出现在可达集合中，且可达集合中的每个模块都不应出现在孤立列表中。
|
||
|
||
**Validates: Requirements 2.8**
|
||
|
||
### Property 11: 过期引用检测
|
||
|
||
*对于任意* 文档中提取的代码引用，若该引用指向的文件路径在仓库中不存在，则 `check_reference_validity` 应返回 `False`。
|
||
|
||
**Validates: Requirements 3.3**
|
||
|
||
### Property 12: 缺失文档检测
|
||
|
||
*对于任意* 核心代码模块集合和已文档化模块集合，`find_undocumented_modules` 返回的缺失列表应恰好等于核心模块集合与已文档化集合的差集。
|
||
|
||
**Validates: Requirements 3.5**
|
||
|
||
### Property 13: 统计摘要一致性
|
||
|
||
*对于任意* 报告的统计摘要，各分类/标签的计数之和应等于对应条目列表的总长度。
|
||
|
||
**Validates: Requirements 4.5, 4.6, 4.7**
|
||
|
||
### Property 14: 报告头部元信息
|
||
|
||
*对于任意* 报告输出，头部应包含一个符合 ISO 格式的时间戳字符串和仓库根目录路径字符串。
|
||
|
||
**Validates: Requirements 4.2**
|
||
|
||
### Property 15: 写操作仅限 docs/audit/
|
||
|
||
*对于任意* 审计执行过程，所有文件写操作的目标路径应以 `docs/audit/repo/` 为前缀。
|
||
|
||
**Validates: Requirements 5.2**
|
||
|
||
### Property 16: 文档对齐报告分区完整性
|
||
|
||
*对于任意* `render_alignment_report` 的输出，Markdown 文本应包含"映射关系"、"过期点"、"冲突点"、"缺失点"四个分区标题。
|
||
|
||
**Validates: Requirements 3.8**
|
||
|
||
## 错误处理
|
||
|
||
| 场景 | 处理方式 |
|
||
|------|---------|
|
||
| 文件读取权限不足 | 记录警告到报告的"错误"分区，跳过该文件，继续处理 |
|
||
| Python 源文件语法错误（`ast.parse` 失败） | 记录警告，将该文件标记为"待确认"，不中断流程树构建 |
|
||
| 文档中的代码引用格式无法解析 | 跳过该引用，不产生误报 |
|
||
| DDL 文件 SQL 语法不规范 | 使用正则提取 `CREATE TABLE` 和列定义，容忍非标准语法 |
|
||
| `docs/audit/repo/` 目录创建失败 | 抛出异常并终止，因为无法输出报告 |
|
||
| 编码问题（非 UTF-8 文件） | 尝试 `utf-8` → `gbk` → `latin-1` 回退读取，记录编码警告 |
|
||
|
||
## 测试策略
|
||
|
||
### 测试框架
|
||
|
||
- 单元测试与属性测试均使用 `pytest`
|
||
- 属性测试库：`hypothesis`（Python 生态最成熟的属性测试框架）
|
||
- 测试文件位于 `tests/unit/test_audit_*.py`
|
||
|
||
### 单元测试
|
||
|
||
针对具体示例和边界情况：
|
||
- 扫描器对实际仓库子集的遍历结果
|
||
- classify 对已知文件路径的分类正确性（如 `tmp/hebing.py` → 临时与调试/候选删除）
|
||
- 入口点识别对实际仓库的结果
|
||
- DDL 与数据字典的比对结果
|
||
- 文件读取失败时的容错行为
|
||
- `docs/audit/repo/` 目录不存在时的自动创建
|
||
|
||
### 属性测试
|
||
|
||
每个正确性属性对应一个属性测试，使用 `hypothesis` 生成随机输入：
|
||
|
||
- 每个属性测试至少运行 100 次迭代
|
||
- 每个测试用注释标注对应的设计属性编号
|
||
- 标注格式：**Feature: repo-audit, Property {N}: {属性标题}**
|
||
|
||
**生成器策略**：
|
||
- `FileEntry` 生成器：随机路径（含各种扩展名、目录层级）、随机大小、随机 is_dir/is_empty_dir
|
||
- `InventoryItem` 生成器：随机 Category/Disposition 组合、随机描述文本
|
||
- `FlowNode` 生成器：随机树结构（限制深度和宽度）
|
||
- 文件树生成器：构造临时目录结构用于扫描器测试
|