arch-design-agent-skill-dashboard/design/application-architecture/02a-layered-architecture.md

doc_id	title	version	status	owners	upstream	downstream	updated_at
DOC-AA-002	模块内部代码分层	0.1.0	reviewed	林然	./02b-solution-layering.md	./06-codebase-alignment.csv ./07-module-boundary-rules.md	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/。