# 架构设计文档

> **事实纪律**:模块、目录、指标、技术与运行能力必须来自当前项目或已确认决策。未知项写“待确认”；合法不适用项写 `N/A（原因）`。

> **产物定位**:design 能力域的架构产出。把"怎么做"想清楚,承接需求分析中的根本目标。
> **核心纪律**:高影响、难逆或跨模块的架构决策须有 ADR 留痕；技术选型须有当前项目依据，并考虑兼容、安全和退出方式。
> **反退化纪律**:模块划分/技术选型/风险登记 等表格与列表必须逐条填写,禁止「其余模块同上」「…」省略、禁止用一句话代替表格行。
> **完成判定**:见文末。

## 1. 决策记录与范围
- 架构决策记录：填写 project map 解析后的真实 reference 路径
- 根本目标引用:需求分析中的“根本目标”章节或当前项目等价位置
- 输入证据引用:

## 2. 需求概要

> 填需求分析第 2 节已有的真实 `REQ-*` 编号，不得自造编号或保留占位符。

| REQ-ID | 需求摘要 | 对应架构模块 |
|--------|---------|-------------|

| NFR-ID | 类别 | 指标 | 目标值 | 验证方式 | 架构支撑方案 |
|--------|------|------|-------|---------|------------|

> 非功能需求的支撑方案必须说明当前项目采用的机制和验证方式，不能用通用技术名词替代推导。

## 3. 约束条件
| 约束类型 | 描述 | 来源 | 影响范围 |
|---------|------|------|---------|

> 只填写真实约束；可检查技术、组织、法规、预算与时间等维度，但不得为了填表虚构约束。

## 4. 模块划分
- 模块清单与职责边界
- 核心接口契约(模块间调用方式)

### 模块依赖关系(禁循环依赖)

> 逐条声明模块→直接依赖,禁循环依赖。多个依赖用 `/` 分隔;无依赖填「无」。

| 模块 | 直接依赖(模块名,多个用 `/` 分隔) | 调用方式 |
|------|--------------------------------------|----------|
| | | |

## 5. 业务流程与数据流向
- 主流程数据流向图(Mermaid)
- 核心业务流程时序图（覆盖入口、关键状态/外部副作用与可观察结果；不适用环节不强行补造）
- 数据与状态承载方案（按当前项目实际使用的内存、关系/文档/键值/对象/事件、文件或外部系统填写）

## 6. 架构组成

### 6.1 系统上下文（C4 L1 或项目等价表达）
- 系统边界与外部系统交互
- 用户角色与接入方式

### 6.2 服务端/核心运行时架构（适用时；C4 L2-3 或项目等价表达）
- 服务拆分与职责
- 核心接口契约
- 数据存储方案

**后端工程目录**:`{当前项目目录}/`(后端工程根目录由用户或现有仓库决定;纯前端项目填「不适用」)。

### 6.3 前端架构（适用时；C4 L2-3 或项目等价表达）
- 应用结构与路由
- 状态管理策略
- 组件分层

#### 端模块清单(承接需求中的“系统形态与交付边界”,每端一个 FE-* 模块;无前端项目填「不适用」)

> **此表由 `soloforge project-modules` 命令输出注入(基于 intent.projects),AI 原样填入,勿增删端或改端 ID/项目目录/技术栈/发布拓扑。** 端名称、职责和需求端引用从需求中的“系统形态与交付边界”补充。

| 端 ID（FE-*） | 端名称 | 项目目录 | 技术栈 | 职责 | 对应需求端 | 发布拓扑 |
|--------------|--------|---------|--------|------|--------------|---------|

> 端 ID 使用稳定的 `FE-{语义标识}-{序号}`，语义标识可含多个连字符段；需求、架构和 `intent.projects` 必须逐字一致。「项目目录」和运行时工程目录必须来自当前项目，不得套用示例目录。
> 「发布拓扑」:`独立发版`/`统一发版`/`不发版`(shared 自动「不发版」)。

### 6.4 安全架构
- 认证与授权方案
- 数据加密策略
- 安全边界与信任域

### 6.5 基础设施与部署
- 部署架构
- 真实环境规划与差异（仅列项目实际存在或明确新增的环境）
- CI/CD 策略
- 监控告警

## 7. 技术选型与依据
| 技术决策 | 候选方案 | 最终选择 | 选择理由 | 放弃方案原因 |
|---------|---------|---------|---------|------------|

> 选型须有依据(性能/成本/团队熟悉度/生态),禁止"业界主流所以选它"。

## 8. 专项产物引用

> database_design / api_spec 是否产出由 task.scope(scope.persistence / scope.api)决定。
> 只列当前项目真实存在的专项产物；未采用某类存储或接口时写 `N/A（具体原因）`，不得预填 SQL 或固定路径假设。

- 数据设计：
- API 规格：
- 机器可读 API 契约：
- 数据结构或迁移权威资产：

## 9. 状态机定义
- 核心业务状态流转
- 触发条件、守卫条件、失败/回滚动作

## 10. 风险与回滚(必填)

### 10.1 风险登记
| RISK-ID | 风险描述 | 概率 | 影响 | 应对方案 | 关联 ADR |
|---------|---------|------|------|---------|---------|

### 10.2 回滚与灾难恢复
| 场景 | RTO | RPO | 恢复策略 | 触发条件 |
|------|-----|-----|---------|---------|

> 恢复策略可以是回滚、前向修复、流量切回或备份恢复，必须与数据兼容性和真实基础设施能力一致。

## 11. 跨横切关注点
| 关注点 | 方案 | 影响模块 |
|--------|------|---------|

> 只列适用的横切关注点，例如观测、错误处理、配置、安全或缓存；不适用项无需制造方案。

## 11.5 菜单与路由映射(前端有菜单导航时必填,纯 API 服务无则省略本节)

> 每个菜单入口声明其对应的前端路由注册路径——build 域 FRONTEND-ROUTE-COVERAGE 按此校验
> 声明路由在前端 router 注册中真实存在(悬空路由=菜单入口指向不存在页面,高发真 bug)。
> 「对应前端路由」列填前端 router 注册的 path 字面量(动态参数统一写 `{param}` 形态,`:param` 会被归一化匹配)。

| 菜单名 | path | 对应前端路由 |
|--------|------|--------------|
| 工作台 | /platform/workbench | /platform/workbench |
| 设备管理 | /platform/devices | /platform/devices |

## 12. 算法与领域模型(有复杂内部逻辑时必填,无则填「无」)

> 复杂算法或领域模型只在业务确有复杂不变量时使用；简单数据读写不强制套 DDD。涉及持久化时仍须明确数据所有权、不变量和生命周期。

- **复杂算法**(如有):算法名 → 输入/输出/核心步骤/复杂度/边界条件
- **领域模型**(如有):聚合根/实体/值对象/领域事件(Mermaid classDiagram)

## 完成判定

- [ ] 高影响、难逆或跨模块决策有对应 ADR，重大选型经用户确认
- [ ] 已检查技术、组织、法规、预算等约束；不适用维度写明原因，没有为填表虚构约束
- [ ] 安全边界、身份/权限与数据保护按实际风险处理；不适用机制写明原因
- [ ] 含风险登记 + 与数据和运行能力匹配的恢复方案；适用的 RTO/RPO 有来源
- [ ] 适用的横切关注点（观测、错误、配置、安全、缓存等）有方案，不适用项有理由
- [ ] 适用的数据/API 专项产物引用指向 project map 的真实路径
- [ ] scope.frontend=true 时，“前端架构/端模块清单”承接需求端清单并与 `intent.projects` 一致；否则明确 N/A 原因
- [ ] 模块/选型/风险等表格逐条填写,无「其余同上」省略、无一句话代替