create-yss-spec 1.0.0

package/template/docs/architecture/templates/architecture-review-checklist.md

@@ -0,0 +1,106 @@
+# 架构审查检查清单
+
+> 每次技术方案评审时逐项检查。AI 预审 + 架构师终审。
+
+---
+
+## 0. 架构产物完整性
+
+- [ ] 业务架构清楚：用户旅程、价值流、业务能力、角色/组织模型、外部系统边界和 MVP 非目标范围已记录，或明确说明不适用。
+- [ ] 功能架构清楚：功能域、模块边界、优先级、依赖关系和 PRD 回填项已记录。
+- [ ] 系统总体架构清楚：服务/模块边界、部署、集成、权限、性能、可靠性、可观测性、发布和回滚策略已记录。
+- [ ] 数据架构清楚：概念/逻辑/物理模型、元模型、版本、血缘、查询/搜索、索引、存储和迁移约束已记录，或明确说明无持久化影响。
+- [ ] 数据模型、元数据、版本或血缘类产品已在 Repository / MyBatis / 持久化开发前完成数据架构。
+- [ ] 架构图如已生成，已引用明确上游文档，且图中发现的问题已回写到 PRD、OpenAPI、ADR、系统 / 数据架构设计 或 Issue。
+
+## 0.1 DDD 轻量门禁
+
+> DDD 检查嵌入现有阶段，不默认新增阶段或独立文档。只有当本节无法说明清楚时，才升级为独立 Strategic / Tactical DDD 设计文档。
+
+- [ ] 若为小改动，已完成 DDD impact check，并确认不影响统一语言、上下文边界、聚合、API、数据、权限或安全红线。
+- [ ] Strategic DDD Check 已完成或明确不适用：统一语言、核心/支撑/通用子域、限界上下文、上下文映射和非目标范围清楚。
+- [ ] Tactical DDD Check 已完成或明确不适用：聚合根、Entity、Value Object、领域服务、不变量、一致性边界和 Repository / Gateway seam 清楚。
+- [ ] OpenAPI 契约使用上下文的公开语言，不直接暴露内部聚合、Repository 或持久化表结构。
+- [ ] 领域行为测试、Application 用例测试、契约测试和必要 E2E 已与 DDD 边界对齐。
+
+## 1. 可扩展性 (Scalability)
+
+- [ ] 服务是否可独立部署和水平扩展？
+- [ ] 数据库是否支持读写分离 / 分库分表规划？
+- [ ] 是否有无状态设计（状态外置到 Redis/DB）？
+- [ ] 服务边界是否合理（单一职责，不过大也不过度拆分）？
+- [ ] 是否有服务发现 / 负载均衡方案？
+
+## 2. 安全性 (Security)
+
+- [ ] 认证链路完整：用户 → API Gateway → Service → DB
+- [ ] 授权模型明确：RBAC / ABAC / OAuth2 Scope
+- [ ] 密码存储：bcrypt / argon2（禁止明文/SHA/MD5）
+- [ ] Token 管理：JWT 含 exp / 支持 refresh / 黑名单机制
+- [ ] API 输入校验：所有外部输入经过 Schema 校验
+- [ ] SQL 注入防护：100% 参数化查询（禁止字符串拼接）
+- [ ] XSS 防护：前端禁止 innerHTML / v-html 直接渲染用户输入
+- [ ] CSRF 防护：SameSite Cookie / CSRF Token
+- [ ] 敏感数据：PII 加密存储，日志脱敏
+- [ ] 依赖安全：定期 npm audit / pip audit
+
+## 3. 性能 (Performance)
+
+- [ ] 数据库查询有索引计划（explain analyze 验证）
+- [ ] 热点数据有缓存策略（Redis / 本地缓存 / CDN）
+- [ ] N+1 查询已识别并消除（eager loading / batch query）
+- [ ] 连接池配置合理（DB pool size / HTTP keep-alive）
+- [ ] 大列表分页（cursor-based > offset-based）
+- [ ] 大文件流式处理（不一次性加载到内存）
+- [ ] 异步处理：耗时操作走消息队列（Kafka / Celery）
+- [ ] 静态资源 CDN + 压缩 (gzip/brotli)
+
+## 4. 可靠性 (Reliability)
+
+- [ ] 关键路径有降级方案（服务不可用时的 fallback）
+- [ ] 外部依赖有超时 + 重试 + 熔断
+- [ ] 数据一致性方案明确（强一致 / 最终一致 / 补偿）
+- [ ] 幂等性：支付/下单等关键操作支持幂等
+- [ ] 健康检查端点：/health 返回依赖状态
+- [ ] 优雅关闭：SIGTERM 时完成进行中的请求
+
+## 5. 可维护性 (Maintainability)
+
+- [ ] 架构决策已记录为 ADR
+- [ ] 契约草案 / OpenAPI Draft 已经工程基线、系统/数据架构和 Issue 校验，并在开发前完成 OpenAPI Freeze
+- [ ] 关键流程有日志 (结构化日志，含 trace_id)
+- [ ] 监控指标已定义 (RED: Rate/Errors/Duration)
+- [ ] 告警规则已配置 (P99 延迟、错误率、磁盘)
+- [ ] 数据库迁移脚本可回滚 (含 downgrade)
+
+## 6. 成本 (Cost)
+
+- [ ] 是否引入了不必要的技术组件？（YAGNI）
+- [ ] 云资源是否按需配置？（避免 over-provisioning）
+- [ ] 是否有冷数据归档策略？
+- [ ] 团队是否有维护该技术栈的能力？
+
+---
+
+## 审查结论
+
+| 维度 | AI 预审评分 | 人工终审评分 | 备注 |
+|------|-----------|------------|------|
+| 可扩展性 | /5 | /5 | |
+| 安全性 | /5 | /5 | |
+| 性能 | /5 | /5 | |
+| 可靠性 | /5 | /5 | |
+| 可维护性 | /5 | /5 | |
+| 成本 | /5 | /5 | |
+
+### 是否通过
+
+- [ ] ✅ 通过 — 进入 Build 阶段
+- [ ] ⚠️ 有条件通过 — 需在 Sprint X 前解决以下问题：
+- [ ] ❌ 不通过 — 需要重新设计
+
+### 待解决项
+
+| 问题 | 严重程度 | 解决方案 | Due | Owner |
+|------|---------|---------|-----|-------|
+| | | | | |

package/template/docs/architecture/templates/business-architecture-template.md

@@ -0,0 +1,70 @@
+---
+pipeline: <feature-id>
+stage: business-architecture
+status: draft
+owner: ai
+---
+
+# <功能名称>业务架构
+
+> 适用场景：新产品、新业务域或较大模块进入 PRD 前。
+> 本文明确产品为谁创造价值、位于什么业务流程和外部生态中，不替代 PRD、功能架构或系统架构。
+
+## 1. 输入材料
+
+| 资产 | 路径 / 链接 | 状态 | 备注 |
+|------|-------------|------|------|
+| Discovery |  |  |  |
+| 竞品 / 市场分析 |  |  |  |
+| CONTEXT 术语 |  |  |  |
+| 现有业务流程 |  |  |  |
+
+## 2. 目标用户与组织角色
+
+| 角色 | 目标 | 关键行为 | 权限 / 组织边界 |
+|------|------|----------|----------------|
+|  |  |  |  |
+
+## 3. 用户旅程
+
+| 阶段 | 用户目标 | 触点 / 系统 | 痛点 | 机会 |
+|------|----------|-------------|------|------|
+|  |  |  |  |  |
+
+## 4. 价值流
+
+| 步骤 | 输入 | 输出 | 负责人 | 成功标准 |
+|------|------|------|--------|----------|
+|  |  |  |  |  |
+
+## 5. 业务能力地图
+
+| 能力域 | 能力 | MVP 优先级 | 依赖 | 非目标 |
+|--------|------|------------|------|--------|
+|  |  | P0 / P1 / P2 |  |  |
+
+## 6. 外部系统与生态边界
+
+| 外部系统 / 团队 | 关系 | 数据 / 事件 | 边界约束 |
+|-----------------|------|-------------|----------|
+|  | 上游 / 下游 / 协作方 |  |  |
+
+## 7. PRD 输入
+
+- 必须进入 PRD 的业务规则：
+- 需要补充的验收标准：
+- 需要回写 `CONTEXT.md` 的术语：
+- 需要进入 OpenAPI / 系统架构的边界：
+
+## 8. 完成标准
+
+- [ ] 用户旅程、价值流、能力地图、角色 / 组织模型清楚。
+- [ ] 外部系统边界和 MVP 非目标范围清楚。
+- [ ] PRD 所需的业务规则和验收线索已列出。
+- [ ] 安全红线和人工审查点已标注。
+
+## 9. 下一步门禁
+
+- 结论：Approved / Blocked
+- 下一步：PRD baseline / 继续业务架构
+- 阻断项：

package/template/docs/architecture/templates/data-architecture-template.md

@@ -0,0 +1,83 @@
+---
+pipeline: <feature-id>
+stage: data-architecture
+status: draft
+owner: ai
+---
+
+# <功能名称>数据架构
+
+> 适用场景：涉及持久化、Repository、元数据、版本、血缘、搜索、查询策略或 OpenAPI schema 依赖数据模型时。
+> 本文必须在持久化开发前完成；数据模型、元数据、版本或血缘类产品应在 Design Review 和 OpenAPI Freeze 前完成。
+
+## 1. 输入材料
+
+| 资产 | 路径 / 链接 | 状态 | 备注 |
+|------|-------------|------|------|
+| PRD / 需求冻结 |  |  |  |
+| 产品总体设计 / 功能架构 |  |  |  |
+| API 影响记录 / 契约草案 / OpenAPI Draft |  |  |  |
+| 系统概要设计 |  |  |  |
+| CONTEXT 术语 |  |  |  |
+
+## 2. 数据目标与范围
+
+- 数据架构目标：
+- 非目标范围：
+- 数据一致性要求：
+- 保留 / 删除 / 归档要求：
+
+## 3. 概念模型
+
+| 概念 | 定义 | 关键属性 | 关系 | 业务规则 |
+|------|------|----------|------|----------|
+|  |  |  |  |  |
+
+## 4. 逻辑模型
+
+| 逻辑对象 | 字段 / 属性 | 类型 | 约束 | 状态 / 版本 |
+|----------|-------------|------|------|-------------|
+|  |  |  |  |  |
+
+## 5. 物理模型草案
+
+> 数据库迁移脚本属于安全红线，Agent 只能生成模板或草案，必须标记 `TODO-HUMAN-REVIEW`。
+
+| 表 / 存储 | 主键 | 关键字段 | 索引建议 | 备注 |
+|-----------|------|----------|----------|------|
+|  |  |  |  |  |
+
+## 6. 版本、血缘与审计
+
+| 对象 | 版本策略 | 血缘关系 | 审计字段 | 回滚 / 追溯 |
+|------|----------|----------|----------|-------------|
+|  |  |  |  |  |
+
+## 7. 查询、搜索与索引
+
+| 场景 | 查询条件 | 排序 / 分页 | 索引 / 缓存 | 性能目标 |
+|------|----------|-------------|-------------|----------|
+|  |  |  |  |  |
+
+## 8. OpenAPI / Repository 反审影响
+
+| 影响点 | 结论 | 是否需回改 | 备注 |
+|--------|------|------------|------|
+| OpenAPI schema |  | 是 / 否 |  |
+| Repository 接口 |  | 是 / 否 |  |
+| MyBatis / Mapper |  | 是 / 否 |  |
+| 数据迁移 |  | 是 / 否 | `TODO-HUMAN-REVIEW` |
+
+## 9. 完成标准
+
+- [ ] 概念 / 逻辑 / 物理模型草案清楚，且不以表结构替代业务概念。
+- [ ] 版本、血缘、审计、查询、索引和存储策略已说明。
+- [ ] OpenAPI schema、Repository、MyBatis 影响已标注；schema 依赖数据模型时已列出 Draft 回改项。
+- [ ] 数据迁移、原生 SQL 等安全红线已标记 `TODO-HUMAN-REVIEW`。
+- [ ] 可进入 Design Review / OpenAPI Freeze，或阻断项已列出。
+
+## 10. 下一步门禁
+
+- 结论：Approved / Blocked
+- 下一步：Design Review / 回到系统概要设计 / 回改契约草案 / OpenAPI Draft
+- 阻断项：

package/template/docs/architecture/templates/engineering-baseline-review-template.md

@@ -0,0 +1,67 @@
+---
+pipeline: <feature-id>
+stage: engineering-baseline-review
+status: draft
+owner: ai
+---
+
+# <功能名称>工程基线 / YSS DDD Review
+
+> 适用场景：新后端服务、新模块、DDD 分层、Gateway / Repository、统一响应、MapStruct 或工程结构受影响时。
+> 本文确认本次变更是否符合 YSS DDD 工程基线，不替代系统概要设计、数据架构或代码审查。
+
+## 1. 输入材料
+
+| 资产 | 路径 / 链接 | 状态 | 备注 |
+|------|-------------|------|------|
+| PRD / 需求冻结 |  |  |  |
+| 产品总体设计 / 功能架构 |  |  |  |
+| API 影响记录 / 契约草案 / OpenAPI Draft / 无 API 影响记录 |  |  |  |
+| 既有工程结构 |  |  |  |
+| YSS skill 路由 |  |  |  |
+
+## 2. 工程影响判断
+
+| 检查项 | 结论 | 说明 |
+|--------|------|------|
+| 是否新建后端服务 | 是 / 否 |  |
+| 是否新增后端模块 | 是 / 否 |  |
+| 是否影响 Adapter / Application / Domain / Infrastructure 分层 | 是 / 否 |  |
+| 是否新增 Gateway / Repository | 是 / 否 |  |
+| 是否影响统一响应 / DTO / VO / Query / CMD | 是 / 否 |  |
+| 是否触碰安全红线 | 是 / 否 |  |
+
+## 3. YSS DDD 分层检查
+
+| 层级 | 职责 | 本次影响 | 约束 / 结论 |
+|------|------|----------|-------------|
+| Adapter | 协议适配、校验、响应包装 |  |  |
+| Application | 用例编排、事务边界 |  |  |
+| Domain | 领域模型、领域服务、Gateway 接口 |  |  |
+| Infrastructure | GatewayImpl、Repository、外部系统适配 |  |  |
+| Bootstrap | 启动、配置、依赖组装 |  |  |
+
+## 4. 推荐 YSS skills
+
+| 场景 | 推荐 skill | 是否需要 | 备注 |
+|------|-------------|----------|------|
+| 新服务骨架 | `yss-ddd-scaffold-generator` | 是 / 否 |  |
+| 后端基线检查 | `yss-backend-scaffold-parent` | 是 / 否 |  |
+| 领域建模 | `yss-domain` / `yss-backend-scaffold-domain` | 是 / 否 |  |
+| Repository / MyBatis | `yss-repository` / `yss-mybatis` | 是 / 否 |  |
+| Web Controller / DTO | `yss-web-controller` / `yss-dto` | 是 / 否 |  |
+
+## 5. 完成标准
+
+- [ ] 调用方向符合 `Adapter -> Application -> Domain` 和 `Infrastructure -> Domain Gateway`。
+- [ ] Domain 不依赖 Adapter、Infrastructure、Mapper、Controller 或 Web DTO。
+- [ ] Controller 不穿透 Repository。
+- [ ] 对象转换优先 MapStruct，重复 mapping 有处理策略。
+- [ ] 所需 YSS skills 已最小化选择。
+- [ ] 安全红线已标记 `TODO-HUMAN-REVIEW`。
+
+## 6. 下一步门禁
+
+- 结论：Approved / Blocked
+- 下一步：系统概要设计 / 数据架构 / 回改契约草案 / OpenAPI Draft
+- 阻断项：

package/template/docs/architecture/templates/functional-architecture-template.md

@@ -0,0 +1,71 @@
+---
+pipeline: <feature-id>
+stage: functional-architecture
+status: draft
+owner: ai
+---
+
+# <功能名称>功能架构
+
+> 适用场景：PRD 初稿之后、PRD 校准之前，需要明确功能域、模块边界、优先级、页面 / API / 数据影响。
+> 本文可独立成文，也可与产品总体设计合并；不替代交互说明、契约草案 / OpenAPI Draft 或系统概要设计。
+
+## 1. 输入材料
+
+| 资产 | 路径 / 链接 | 状态 | 备注 |
+|------|-------------|------|------|
+| PRD 初稿 |  |  |  |
+| 业务架构 |  |  |  |
+| Discovery |  |  |  |
+| CONTEXT 术语 |  |  |  |
+
+## 2. 功能目标与边界
+
+- MVP 目标：
+- 非目标范围：
+- 关键用户流：
+- 成功标准：
+
+## 3. 功能域与模块
+
+| 功能域 | 模块 / 页面 | 主要能力 | 优先级 | 上游 / 下游 | 非目标 |
+|--------|-------------|----------|--------|-------------|--------|
+|  |  |  | P0 / P1 / P2 |  |  |
+
+## 4. 业务对象与状态
+
+| 对象 | 状态 / 属性 | 关系 | 规则 / 不变量 | 备注 |
+|------|-------------|------|---------------|------|
+|  |  |  |  |  |
+
+## 5. 页面 / API / 数据影响
+
+| 能力 | 页面影响 | API 影响 | 数据影响 | 权限 / 审计影响 |
+|------|----------|----------|----------|------------------|
+|  |  |  |  |  |
+
+## 6. 依赖与风险
+
+| 依赖 / 风险 | 类型 | 影响 | 处理方式 |
+|-------------|------|------|----------|
+|  | 业务 / 技术 / 外部系统 |  |  |
+
+## 7. PRD 回填项
+
+| 编号 | 回填内容 | 影响章节 | 优先级 | 状态 |
+|------|----------|----------|--------|------|
+|  |  |  | P0 / P1 / P2 | 待回填 / 已回填 |
+
+## 8. 完成标准
+
+- [ ] 功能域、模块边界、优先级和依赖清楚。
+- [ ] MVP / 非目标范围与 PRD 一致。
+- [ ] 页面、API、数据、权限和审计影响已显式标注。
+- [ ] PRD 回填项已分清阻断项和非阻断项。
+- [ ] 可进入产品设计 / PRD 校准。
+
+## 9. 下一步门禁
+
+- 结论：Approved / Blocked
+- 下一步：产品设计 / PRD 校准 / OpenAPI 无影响记录
+- 阻断项：

package/template/docs/architecture/templates/system-overview-design-template.md

@@ -0,0 +1,129 @@
+---
+pipeline: <feature-id>
+stage: system-overview-design
+status: draft
+owner: ai
+---
+
+# <功能名称>系统概要设计
+
+> 适用时机：API 影响分析 / 契约草案 / OpenAPI Draft、工程基线 / YSS DDD Review 之后，Design Review 和 OpenAPI Freeze 之前。
+> 本阶段必须反向校验契约草案；OpenAPI Draft 在 Freeze 前仍是 review-only，不是实现或生成客户端的稳定契约。
+> 本文用于团队内部技术方案讨论审核，不替代 OpenAPI、ADR、系统 / 数据架构设计、数据架构或详细设计。
+
+## 1. 输入资产
+
+| 资产 | 路径 / 链接 | 状态 | 备注 |
+|------|-------------|------|------|
+| PRD / PRD 校准 |  |  |  |
+| 产品总体设计 / 功能架构 |  |  |  |
+| 产品设计 / 原型 / 交互说明 |  |  |  |
+| API 影响记录 / 契约草案 / OpenAPI Draft |  |  |  |
+| 工程基线 / YSS DDD Review |  |  |  |
+| ADR / 既有架构约束 |  |  |  |
+
+## 2. 设计目标与范围
+
+- 本次设计目标：
+- 非目标范围：
+- 关键质量属性：
+- 主要风险：
+
+## 3. 系统边界
+
+| 边界 | 说明 | 输入 | 输出 | 责任方 |
+|------|------|------|------|--------|
+| 前端 |  |  |  |  |
+| Web Adapter |  |  |  |  |
+| Application |  |  |  |  |
+| Domain |  |  |  |  |
+| Infrastructure |  |  |  |  |
+| 外部系统 |  |  |  |  |
+
+## 4. 模块与调用关系
+
+| 模块 | 职责 | 上游 | 下游 | 关键 interface / adapter |
+|------|------|------|------|--------------------------|
+|  |  |  |  |  |
+
+## 5. 关键流程与状态
+
+| 流程 / 状态机 | 触发条件 | 主要步骤 | 成功结果 | 失败 / 补偿 |
+|---------------|----------|----------|----------|-------------|
+|  |  |  |  |  |
+
+## 6. API 与契约反审
+
+| OpenAPI 路径 / schema | 设计结论 | 是否需回改 Draft | 备注 |
+|-----------------------|----------|------------------|------|
+|  |  | 是 / 否 |  |
+
+## 7. 数据与持久化影响
+
+| 数据对象 | 存储 / 来源 | 版本 / 审计 | 查询 / 索引 | 是否需要数据架构 |
+|----------|-------------|-------------|-------------|------------------|
+|  |  |  |  | 是 / 否 |
+
+## 8. Tactical DDD Check（轻量）
+
+> 本节嵌入系统概要设计 / 数据架构，不新增独立阶段。只有当聚合边界、状态机、一致性或持久化映射复杂到无法在本节说明时，才升级为 `docs/architecture/<feature>-tactical-design.md`。
+
+| 限界上下文 | 聚合根 | 业务不变量 | Entity / Value Object | 一致性边界 | Gateway / Repository | 主要测试 seam |
+|------------|--------|------------|-----------------------|------------|----------------------|----------------|
+|  |  |  |  | 单聚合事务 / 跨聚合最终一致 / 只读查询 |  |  |
+
+战术设计就绪检查：
+
+- [ ] 聚合根和聚合内部不变量已明确，且不以 ER 关系替代聚合边界。
+- [ ] Entity / Value Object 的身份、不可变性和生命周期已说明。
+- [ ] 事务一致性、并发、幂等、补偿或最终一致策略已说明。
+- [ ] Repository / Gateway 接口位于 Domain，Infrastructure 只做实现。
+- [ ] OpenAPI schema 不直接暴露内部聚合或持久化表结构。
+- [ ] 领域行为测试、Application 用例测试、契约测试 seam 已明确。
+
+## 9. 非功能需求
+
+| 维度 | 设计约束 | 验证方式 |
+|------|----------|----------|
+| 安全 |  |  |
+| 权限 |  |  |
+| 性能 |  |  |
+| 可靠性 |  |  |
+| 可观测性 |  |  |
+| 发布 / 回滚 |  |  |
+
+## 10. 安全红线与人工审查
+
+| 风险点 | 是否触碰红线 | 处理方式 | 状态 |
+|--------|--------------|----------|------|
+| 支付逻辑 | 否 |  |  |
+| 数据库迁移脚本 | 否 |  |  |
+| 认证 / 授权中间件 | 否 |  |  |
+| 加密算法实现 | 否 |  |  |
+| SQL 原生查询 | 否 |  |  |
+| 公共基础库 API | 否 |  |  |
+
+触碰红线时必须标记 `TODO-HUMAN-REVIEW`，并在实现前取得人工确认。
+
+## 11. ADR 候选
+
+| 决策 | 为什么难回滚 | 备选方案 | 是否需要 ADR |
+|------|--------------|----------|--------------|
+|  |  |  | 是 / 否 |
+
+## 12. 评审清单
+
+- [ ] 系统边界、模块职责和调用方向符合 YSS DDD 分层。
+- [ ] API 影响记录 / 契约草案 / OpenAPI Draft 的路径、schema、错误结构、分页、权限和契约测试已被架构反审，且可落地或已列出回改项。
+- [ ] 状态流、失败路径、幂等、并发和回滚策略清楚。
+- [ ] 数据架构需求已明确；涉及持久化、元模型、版本或血缘时已有数据架构。
+- [ ] Tactical DDD Check 已完成，或明确说明本次变更不影响领域模型 / 聚合 / 持久化边界。
+- [ ] 安全红线和人工审查点已标记。
+- [ ] 需要 ADR 的决策已列出。
+- [ ] 可进入 Design Review，或明确阻断项。
+
+## 13. 结论
+
+- 评审结论：Approved / Blocked
+- 阻断项：
+- 下一步：

package/template/docs/architecture/templates/tech-design-template.md

@@ -0,0 +1,129 @@
+# 技术方案：[功能名称]
+
+> 版本: 0.1 | 作者: | 日期: | 关联: PRD-xxx / ADR-xxx
+
+---
+
+## 背景
+
+（为什么需要这个方案？解决什么问题？有何约束？）
+
+---
+
+## 方案概述
+
+（2-3 句话描述核心思路）
+
+---
+
+## 详细设计
+
+### 业务架构影响
+
+（本方案影响哪些用户旅程、价值流、角色职责、外部系统边界；如无影响，说明原因。）
+
+相关图：`docs/architecture/diagrams/<feature>-business-capability.excalidraw`
+
+### 功能架构
+
+（功能域、模块边界、优先级、模块依赖、MVP / 非目标范围；说明哪些内容需要回填 PRD。）
+
+相关图：`docs/architecture/diagrams/<feature>-functional-modules.excalidraw`
+
+### 系统总体架构
+
+（服务/模块边界、部署形态、集成关系、权限链路、性能/可靠性/可观测性、发布和回滚策略。）
+
+相关图：`docs/architecture/diagrams/<feature>-system-architecture.excalidraw`
+
+### 数据模型
+
+```sql
+-- 示例：DDL 或 ER 图描述
+CREATE TABLE xxx (
+    id UUID PRIMARY KEY,
+    ...
+);
+```
+
+（如果是数据模型、元数据、版本或血缘分析类产品，必须补充概念模型、逻辑模型、物理模型、元模型、版本策略、血缘/查询/索引策略。）
+
+相关图：`docs/architecture/diagrams/<feature>-data-model.excalidraw`
+
+### API 设计
+
+| Method | Path | 说明 | Request | Response |
+|--------|------|------|---------|----------|
+| GET | /api/v1/xxx | | | |
+| POST | /api/v1/xxx | | | |
+
+### 核心流程
+
+（时序图或流程图描述关键交互）
+
+### 关键算法
+
+（如有复杂计算逻辑，描述伪代码）
+
+---
+
+## 方案对比
+
+| 维度 | 方案A: [名称] | 方案B: [名称] | 方案C: [名称] ★推荐 |
+|------|-------------|-------------|-------------------|
+| 复杂度 (1-5) | | | |
+| 安全 (1-5) | | | |
+| 性能 (1-5) | | | |
+| 扩展性 (1-5) | | | |
+| 开发成本 (人天) | | | |
+| 与现有技术栈契合度 | | | |
+
+### 选择理由
+
+（为什么推荐方案C）
+
+---
+
+## 风险评估
+
+| 风险 | 概率 (高/中/低) | 影响 | 缓解措施 | Owner |
+|------|---------------|------|---------|-------|
+| | | | | |
+
+---
+
+## 安全审查
+
+- [ ] 认证授权链路完整
+- [ ] 敏感数据加密存储 (密码/payment info/PII)
+- [ ] API 输入校验 (Pydantic v2 / TypeScript strict)
+- [ ] SQL 注入防护 (参数化查询)
+- [ ] XSS 防护 (textContent / DOMPurify)
+- [ ] CSRF 防护 (SameSite Cookie / Token)
+
+---
+
+## 性能评估
+
+| 指标 | 目标 | 方案 |
+|------|------|------|
+| 预期 QPS | | |
+| P99 响应时间 | ≤ 200ms | |
+| 数据量 (1年) | | |
+| 缓存策略 | | Redis / CDN / 浏览器缓存 |
+| 数据库索引 | | |
+
+---
+
+## 技术债务
+
+| 妥协点 | 原因 | 偿还计划 |
+|--------|------|---------|
+| | | Sprint X |
+
+---
+
+## 变更历史
+
+| 日期 | 版本 | 变更 | 作者 |
+|------|------|------|------|