---
doc_id: DOC-AA-007
title: 模块边界规则
version: 0.1.0
status: reviewed
owners:
  - 林然
upstream:
  - ./02a-layered-architecture.md
  - ./02-modules.csv
downstream:
  - ./06-codebase-alignment.csv
updated_at: 2026-03-23
---

# 模块边界规则

## 1. 跨模块依赖规则

### 允许的依赖方向
- MOD-SCANNER → MOD-DESIGN（Scanner 生成 Design 实体，调用 Design 约束规则）
- MOD-GRAPH → MOD-DESIGN（Graph 读取 Design 实体转换为图结构）
- MOD-EDITOR → MOD-DESIGN, MOD-SCANNER, MOD-GRAPH（Phase 2）
- MOD-IMPL-TRACKER → MOD-DESIGN, MOD-SCANNER（Phase 2）

### 禁止的依赖
- MOD-DESIGN 不依赖任何其他业务模块（它是被依赖的核心）
- MOD-PROJECT 不依赖其他业务模块（独立管理项目元数据）
- MOD-GRAPH 不直接读文件系统（通过 Design 实体获取数据）
- 前端模块之间不直接调用（通过 Pinia store 或事件通信）

## 2. 数据边界

- 每个模块只通过 domain 层的公共接口暴露数据
- 模块间传递的是 domain 实体或其 DTO，不是原始文件内容
- MOD-DESIGN 的实体是跨模块共享的"通用语言"

## 3. 反模式清单

| 反模式 | 说明 |
|--------|------|
| Scanner 包含业务规则 | 业务规则（如"capability 必须关联 module"）属于 MOD-DESIGN |
| Graph 直接读文件 | Graph 应该从 Design 实体构建图，不应该自己解析文件 |
| Editor 绕过 Scanner 修改文件 | 修改后必须触发重新扫描保证数据一致 |
| Domain 层引入框架依赖 | domain 层纯 Python，不导入 FastAPI/Pydantic/SQLAlchemy 等 |
| 前端组件硬编码 API 地址 | API 调用封装在模块的 api/ 目录，组件通过 composables 调用 |
| 前端模块间直接 import 组件 | 通过 shared/ 或事件通信 |

## 4. 演进策略

- MVP 阶段 MOD-DESIGN 是被动的纯模型库
- Phase 2 可以在 MOD-DESIGN 中增加更复杂的校验服务（如跨文件一致性检查）
- 如果 MOD-SCANNER 变得过大，可以按文件类型拆分（csv-parser、md-parser、yaml-parser），但保持在 Scanner 的 infrastructure 层内