Technical Design

系统架构与前期技术方案设计规范技能 (Technical Design & Architecture Skill)

概述 (Overview)

本技能定义了研发工程师与 AI 编码助手在面对新需求、新系统立项、复杂业务模块重构或核心基础设施升级时的前期系统架构设计、技术方案编写（RFC / Technical Design Document, TDD）与评审交互红线。

吸纳业界卓越工程纪律与框架（如 obra/superpowers 的资深工程师纪律），彻底告别凭感觉写代码（Vibe Coding）。“前期设计跑偏一步，后期维护百倍代价；任务缺乏验证命令，执行必成半吊子工程”。本技能旨在保障在动手写任何业务代码之前，架构设计在需求边界、数据建模、时序交互、算法公式、异常推演、微任务拆解与铁证检验七大维度上均实现严密闭环，并经由用户严格审阅确认后方可投产。

1. 核心设计铁律（五大绝对红线）

在开始编写代码前，必须时刻无条件遵守以下铁律：

🚨 铁律一：复杂需求必须“方案先行、审阅确认后再编码” (Design-First Rule)

• 凡涉及新增独立模块、多表关联改造、跨服务调用、资金/资产交互或底层重构，坚决禁止在拿到需求后直接写业务代码。
• 强制执行机制：必须先输出结构化的《技术方案设计文档》（TDD/RFC），向用户清晰汇报架构选型、数据模型、流程图与潜在风险。只有在获得用户的明确确认后，方可进入编码实现阶段。

🚨 铁律二：坚决禁止静默添加重试、兜底与补偿逻辑 (No Silent Fallback/Retry)

• 在方案推演或接口设计过程中，若评估认为某些外部调用、数据库查询或 MQ 消费可能失败，坚决禁止在方案或代码中静默直接加入自动重试（Retry）、默认值兜底降级（Fallback）或数据补偿逻辑。
• 必须履行的告知义务：方案中必须设立专门章节，向用户主动分析：
  1. 为什么需要重试/兜底/补偿？
  2. 潜在副作用与次生风险（防好心办坏事：如脏数据静默写入、重复扣款/重复建单、雪崩重试风暴、掩盖真实线上故障等）；
  3. 可行的备选方案对比。 在方案审阅时由用户显式拍板确认后，方可纳入实现计划。

🚨 铁律三：苏格拉底式需求收敛协议 (Socratic Refinement Protocol)

• 如果给出的需求指令信息不足以支撑写出高精度架构方案时，严禁凭空脑补核心业务边界，严禁长篇大论凭感觉规划 (Vibe Planning)。
• 应对准则：
  1. 基于业内成熟通用最佳实践，先提炼出设计基调框架；
  2. 启动单点聚焦提问机制：在方案开头明确列出 2-3 个最关键的决策确认点（例如：高并发峰值容忍、读多写少还是强一致性写入、超时兜底偏好、冷热数据隔离周期）；
  3. 通过针对性问答收敛出确定性的产品技术契约（Spec Contract），杜绝返工。

🚨 铁律四：复杂算法与数学模型标准 LaTeX 规范 (Mathematical Rigor)

• 方案中若涉及复杂的业务计费公式、评分排名算法、加权负载均衡、概率模型、密码学或几何计算，必须使用标准的 LaTeX 公式进行原理解释与数学推导：
  • 行内公式使用 $公式$（例如：加权耗损计算 $W_i = \alpha \cdot C_i + (1 - \alpha) \cdot R_i$）；
  • 独立公式块使用 $$ ... $$。
• 严禁使用模糊口语化的自然语言指代关键数学公式，必须给出公式定义域、边界极值与输入输出示例。

🚨 铁律五：完成前铁证验证门禁 (Verification Evidence Gate)

• 严禁口头声明完成：严禁在未经过真实命令验证的情况下向用户汇报“已实现/已完成”。
• 方案中每个实施微任务，必须配有可执行的自动化验证命令（测试用例、编译检查、脚本断言）。
• 落地执行时，必须在终端真实运行检验命令并输出 Exit Code 0 与测试通过证据，形成铁证闭环。

2. 技术方案设计标准交付规范 (TDD / RFC 结构)

技术方案必须严格按照以下结构化模板编写交付，重点突出架构图、关键设计与微任务拆解：

# 🏛️ [功能模块名称] 技术架构方案设计 (Technical Design Document)

## 1. 业务场景与需求收敛 (Socratic Refinement)
- **需求概述**：[简明扼要说明本次设计解决的核心业务价值]
- **核心决策待确认点 (若需求模糊)**：
  - [ ] 待确认点 1：[明确列出需用户拍板的技术/业务分支，如选择 Redis ZSet 还是自研发号器]
  - [ ] 待确认点 2：[明确列出性能、事务边界或降级约束]
- **设计边界**：明确 In-Scope（本次交付）与 Out-of-Scope（明确不做的延伸项）。
- **性能与容量指标**：预期并发（QPS/TPS 峰值）、数据增长估算、时延要求（P99 < 200ms）。

## 2. 领域建模与数据存储设计 (Data Architecture)
- **库表结构与实体关系 (ER)**：
  - 核心字段设计、主键生成策略（ULID / 分布式雪花算法 / 自增 ID）；
  - **索引与约束规划**：聚簇索引、最左匹配联合索引、防重唯一索引（考虑软删除兼容性）；
  - 归档与按月分表规划（如满足按月自愈分表红线）。
- **缓存与状态存储 (Redis)**：
  - 标准分环境 Key 命名空间：`{project}:{env}:{module}:{business_key}`；
  - 数据结构选型（String / Hash / ZSet / HyperLogLog）与明确的 TTL 过期时间。

## 3. 业务流程、时序交互与状态机 (Workflow & State Machine)
- **核心业务时序图 (Mermaid Sequence Diagram)**：
  （严格遵循 Mermaid 防崩语法：双引号包裹节点，纯文本连线条件）
- **有限状态机跃迁图 (FSM State Diagram)**：
  - 覆盖所有正向流（如：待支付 -> 已支付 -> 履约中 -> 已完成）；
  - 覆盖所有逆向流（如：超时取消、风控拦截、申请退款、原路退回）；
  - 明确禁止非法反向跃迁。

## 4. 复杂算法与数学公式推导 (若涉及)
- 业务数学模型与公式推导：
  $$S_{final} = \sum_{i=1}^{n} w_i \cdot \frac{x_i - \min(X_i)}{\max(X_i) - \min(X_i)}$$
- 参数边界说明与极值处理（防除零、防溢出）。

## 5. 健壮性、幂等与异常补偿方案 (Robustness & Fallback)
- **幂等与防并发竞态设计**：
  - 业务唯一 Idempotency Key 机制；
  - 分布式锁粒度（精准锁定业务最小维度，严禁大范围粗粒度锁）。
- **兜底、重试与补偿策略评估（核心提醒）**：
  - 拟定重试/兜底逻辑：[说明具体策略]
  - 潜在次生风险：[如是否可能导致脏数据写入、重复消费]
  - 备选方案：[列出替代方案]
  - **👉 请用户确认是否采纳该兜底策略**。

## 6. 实施路线与可验证微任务拆解 (Bite-Sized Verifiable Tasks)
严禁粗粒度“一步到位”，强制拆解为 10~20 分钟粒度的可检验原子任务：

- [ ] **Task 1: [契约与数据模型定义]**
  - **Target Files**: `api/order.api`, `model/order_model.sql`
  - **Intent & Spec**: 声明 API 契约与 SQL Schema，建立防重唯一索引。
  - **Automated Verification**:
    ```bash
    goctl api validate --api api/order.api
    ```
  - **Evidence Gate**: 命令退出码 0，契约校验通过。

- [ ] **Task 2: [核心业务 Logic 编排与事务闭环]**
  - **Target Files**: `internal/logic/create_order_logic.go`
  - **Intent & Spec**: 实现下单编排、分布式防重锁与库存原子预扣。
  - **Automated Verification**:
    ```bash
    go test -v -run TestCreateOrderLogic_Success ./internal/logic/...
    ```
  - **Evidence Gate**: 单元测试 Pass，包含零库存与并发扣减测试。

- [ ] **Task 3: [异常分支覆盖与铁证回归]**
  - **Target Files**: `internal/logic/create_order_logic_test.go`
  - **Intent & Spec**: 覆盖超时回滚与重复提交幂等拦截分支。
  - **Automated Verification**:
    ```bash
    go test -v -race -cover ./internal/logic/...
    ```
  - **Evidence Gate**: 单测覆盖率 >= 80%，Race 竞态检测 0 警告。

3. 领域与技术栈专属设计规范

3.1 Go & go-zero 架构设计前置规范

• 契约先行：严禁在未定义 .api 或 .proto 文件前编写任何 Handler 或 Logic 代码；
• 资源依赖收敛：新增的数据库引擎、Redis 连接、RPC 客户端，必须在方案中明确声明挂载于 ServiceContext，保持单例无状态；
• 分层穿透规避：Handler 严禁越权调用 Model，必须经由 Logic 编排；
• 统一响应与错误码规划：在方案中预先分配好本模块的业务错误码段（如 20101 ~ 20199）。

3.2 Python & FastAPI 架构设计前置规范

• Schema 契约前置：优先定义 Pydantic v2 Request/Response Schema，显式声明 Field(description="...")；
• 事务边界规划：写操作的 session.commit() 必须收敛在单一 Service 方法末尾，方案中禁止出现多个并发写操作共享同一脏 Session 的时序设计。

3.3 网络爬虫与数据采集设计前置规范

• 协议逆向优先评估：前期方案必须包含接口抓包可行性验证，优先抓取 XHR/JSON 接口；
• 反爬风险定级：前置评估目标站点的 WAF 级别、TLS/JA3 指纹要求与频控阈值，选定客户端驱动（httpx vs curl_cffi vs playwright）。

4. 设计方案评审 Checklist

在方案提交给用户审阅前，逐项检查：

• 若需求存在模糊之处，是否已通过苏格拉底式提问列出 2-3 个核心确认点？
• 实施任务是否已拆解为携带【Target Files】与【Automated Verification】的微任务（Bite-Sized Verifiable Tasks）？
• 是否存在私自静默加入的重试或兜底降级？若有，是否已向用户充分说明原因与风险？
• 复杂业务算法是否已使用标准 LaTeX 公式进行清晰推导？
• 状态机图是否包含了逆向分支与超时终态，避免出现无头悬挂状态？
• 接口是否具备幂等机制防范重复提交？
• 技术术语是否合规（严禁出现敏感机房代号，统一使用通用术语）？

5. 高级架构治理：ADR、可观测性与安全前置 (Advanced Architecture Patterns)

吸纳业界顶尖工程架构标准，技术方案必须包含以下前置防护模块：

5.1 架构决策记录 (Architecture Decision Record, ADR)

在重大选型或方案折中时，必须在方案中保留 ADR 决策块：

• Context (背景上下文)：面临什么业务挑战与性能约束？
• Decision (最终裁定方案)：选用了哪种技术路线/设计模式？
• Rejected Alternatives (被否决的备选方案与原因)：
  • 方案 B (已否决)：原因（如：写入并发无法满足要求、改造成本过高、存在单点风险）。
• Consequences & Trade-offs (代价与妥协)：带来了哪些已知限制？如何防范技术债？

5.2 可观测性前置设计 (Observability-First Design)

严禁系统上线后再补救监控。前期方案必须明确：

1. 指标与 SLO/SLA 阈值：
   • 吞吐指标（QPS 预期峰值）；
   • 延迟指标（P95 < 100ms，P99 < 300ms）；
   • 错误率红线（5xx 比例 > 0.05% 立即触发 P1 告警）。
2. 全链路 Trace 穿透：HTTP Header (x-trace-id) -> RPC Context -> MQ 消息属性 -> 数据库 SQL 注释统一串联。

5.3 安全威胁建模前置 (Security & STRIDE)

• 水平与垂直越权防护 (Anti-IDOR)：所有基于 ID 操作的数据（如订单、设备、账单），必须在数据持有层校验当前请求租户/用户归属权（WHERE id = ? AND user_id = ?）；
• 敏感数据存储：手机号、身份证、密钥等字段在方案中必须注明脱敏加密策略（AES-256-GCM / 摘要哈希）。