127 lines
4.4 KiB
Markdown
127 lines
4.4 KiB
Markdown
---
|
||
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/`。
|