---
doc_id: DOC-AA-002
title: 模块内部代码分层
version: 0.1.0
status: reviewed
owners:
  - 林然
upstream:
  - ./02b-solution-layering.md
downstream:
  - ./06-codebase-alignment.csv
  - ./07-module-boundary-rules.md
updated_at: 2026-03-23
---

# 模块内部代码分层

## 1. 总体规则

每个后端模块采用 DDD 四层结构：

```
modules/<module>/
├── domain/          # 纯 Python，零框架依赖
│   ├── entities/    # 实体、值对象
│   ├── repositories/# 仓储抽象接口（ABC）
│   └── services/    # 核心业务逻辑
├── application/     # 用例编排，调用 domain 层
│   └── services/    # 应用服务（use case）
├── infrastructure/  # 外部适配（文件 I/O、JSON 持久化、解析器）
│   ├── parsers/     # CSV/MD/YAML/OpenAPI 解析器
│   └── repositories/# 仓储实现
└── interfaces/      # HTTP 入口
    └── http/
        └── routers/ # FastAPI 路由
```

## 2. 层间依赖规则

```
interfaces → application → domain ← infrastructure
```

- **domain 层绝对不导入其他三层**，也不导入任何框架包（FastAPI、Pydantic 的 BaseModel 等）
- domain 层的实体用纯 Python dataclass 或普通类
- infrastructure 层实现 domain 层定义的抽象接口
- application 层通过依赖注入获取 infrastructure 的实现
- interfaces 层只做 HTTP 协议适配（入参校验、响应序列化），不含业务逻辑

## 3. 各模块 domain 层内容

### MOD-DESIGN（架构设计领域）

核心模块，定义所有设计领域的实体和业务规则。

**实体：**
- `Capability` — 能力（ID、名称、优先级、关联价值流）
- `Module` — 功能模块（ID、名称、层、依赖、关联能力）
- `Entity` — 数据实体（ID、名称、owner module）
- `ValueFlow` — 价值流（ID、触发、步骤、结果）
- `UserJourney` — 用户旅程（ID、前置条件、步骤、后置条件）
- `Integration` — 集成关系（源模块、目标、协议、方向）
- `DataFlow` — 数据流（源、目标、数据内容、触发）
- `TraceabilityLink` — 追溯关系（capability→module→entity）
- `DesignDocument` — 非结构化设计文件元数据（frontmatter: upstream/downstream/status/doc_id）
- `ExternalSystem` — 外部系统
- `RuntimeComponent` — 运行时组件
- `TechnologySelection` — 技术选型项
- `Environment` — 环境定义

**值对象：**
- `FileStatus` — ok / sparse / missing / template-residue / placeholder-heavy
- `ArchitectureLayer` — business / application / data / technology
- `ModuleLayer` — domain / application / infrastructure / interfaces

**约束规则（domain services）：**
- 每个 Capability 至少关联一个 Module
- 每个 Entity 必须有一个 owner Module
- TraceabilityLink 中引用的 ID 必须在对应实体列表中存在
- DesignDocument 的 upstream/downstream 引用的文件必须存在

### MOD-SCANNER（设计扫描与解析）

**domain：**
- `ScanResult` — 一次扫描的完整输出（所有解析出的 Design 实体 + 文件状态列表）
- `ScanPolicy` — 扫描策略（哪些文件类型要解析、忽略规则）

### MOD-GRAPH（关系图引擎）

**domain：**
- `GraphNode` — 图节点（类型、ID、标签、状态、所属分组）
- `GraphEdge` — 图边（source、target、关系类型）
- `GraphGroup` — 分组（架构层级）
- `GraphView` — 完整图视图（nodes + edges + groups），支持按层级过滤

### MOD-PROJECT（项目管理）

**domain：**
- `Project` — 项目（ID、名称、设计目录路径、代码目录路径、创建时间）
- `ProjectRepository`（ABC）— 项目持久化抽象接口

### MOD-EDITOR（文件编辑器，Phase 2）

**domain：**
- `EditableFile` — 可编辑文件（路径、格式、内容）
- `ImpactResult` — 影响分析结果（受影响的文件列表和原因链）

### MOD-IMPL-TRACKER（实现进度追踪，Phase 2）

**domain：**
- `ImplProgress` — 模块实现进度（模块 ID、百分比、来源：auto/llm/manual）
- `CodeStructure` — 代码目录结构扫描结果

## 4. 前端分层

前端模块采用 Vue 3 组件化结构：

```
src/modules/<module>/
├── components/   # Vue 组件
├── composables/  # 组合式函数（业务逻辑）
├── types/        # TypeScript 类型定义
└── api/          # 后端 API 调用封装
```

共享代码放 `src/shared/`。