MonkeyCode SDD规范模板库：开箱即用的行业标准（2026完全版）
"SDD（Software Design Specification）不是文档，是代码质量的基因。好的SDD让AI生成的代码从一开始就走在正确的道路上。"
一、为什么需要SDD规范？
1.1 没有SDD的AI编程是什么样？
┌─────────────────────────────────────────────────────────────┐
│ 有SDD vs 无SDD 的AI编码效果对比 │
│ │
│ ❌ 无SDD的AI编码: │
│ │
│ 用户: "帮我写一个用户登录接口" │
│ ↓ │
│ AI: [生成了一段能跑但质量参差的代码] │
│ ↓ │
│ 结果: │
│ ✗ 密码用明文存储 │
│ ✗ 没有输入校验 │
│ ✗ 没有防暴力破解 │
│ ✗ 错误处理不统一 │
│ ✗ 日志格式混乱 │
│ ✗ 接口风格与项目其他部分不一致 │
│ ✗ 没有单元测试 │
│ ✗ 没有API文档 │
│ │
│ 后果: 能用，但技术债务从第一天就开始累积 │
│ Code Review时被打回重写 → 浪费时间 │
│ 上线后发现安全问题 → 紧急修复 │
│ │
│ ✅ 有SDD约束的AI编码（"规范驱动"模式）: │
│ │
│ 用户: "基于SDD模板 user-auth-v2 规范， │
│ 实现用户登录接口" │
│ ↓ │
│ AI: [读取SDD规范 → 理解约束 → 生成合规代码] │
│ ↓ │
│ 结果: │
│ ✓ 密码使用bcrypt加密（SDD强制要求） │
│ ✓ 输入使用Joi/Zod Schema校验（SDD定义了字段规则） │
│ ✓ 内置Rate Limiter（SDD安全章节要求） │
│ ✓ 统一错误码格式（SDD定义了Error Schema） │
│ ✓ 结构化日志（SDD定义了Log Format） │
│ ✓ RESTful风格 + OpenAPI注解（SDD API规范） │
│ ✓ 自动附带Jest测试用例（SDD测试要求） │
│ ✓ Swagger文档自动生成 │
│ │
│ 后果: 一次通过Code Review的概率 >85% │
│ 安全扫描零Critical问题 │
│ 新人看代码也能快速理解 │
└─────────────────────────────────────────────────────────────┘
1.2 MonkeyCode SDD的核心价值
# SDD规范的六大核心价值
core_values:
# 价值1: 质量左移（Shift Left）
- name: "Quality Left Shift"
description: "在写第一行代码之前就确定质量标准"
before_sdd: "先写代码 → 发现问题 → 重构 → 再发现 → 循环"
after_sdd: "先定规范 → 写代码 → 符合预期 → 验收通过"
metrics:
code_review_rework_rate: "↓ 60%" # Review返工率降低60%
first_commit_pass_rate: "↑ 40%" # 首次提交通过率提升40%
security_issues_at_launch: "↓ 85%" # 上线时安全问题减少85%
# 价值2: 团队认知对齐
- name: "Team Cognitive Alignment"
description: "所有人（包括AI）对'好代码'的定义一致"
problem: "每个开发者有自己的编码习惯，AI更不知道你的偏好"
solution: "SDD作为单一事实来源（Single Source of Truth）"
benefits:
- "新人Onboarding时间缩短50%"
- "跨团队协作冲突减少70%"
- "AI输出风格100%符合团队标准"
# 价值3: 可审计可追溯
- name: "Auditability & Traceability"
description: "每行代码都能追溯到设计决策"
capabilities:
- "需求→设计→代码→测试的全链路追溯"
- "为什么这样写的决策记录"
- "合规审计时的证据链"
# 价值4: AI编程的"宪法"
- name: "AI Coding Constitution"
description: "给AI Agent明确的边界和规则"
analogy: "就像国家的宪法——不是限制自由，而是保障秩序"
effect: |
没有SDD: AI像没有交通规则的司机，
技术上能开车，但随时可能出事故
有SDD: AI像遵守交通规则的司机，
在规则范围内高效行驶，安全到达目的地
# 价值5: 知识资产沉淀
- name: "Knowledge Asset Accumulation"
description: "将团队的最佳实践固化为可复用的模板"
evolution:
stage_1: "个人经验（存在脑子里）"
stage_2: "团队规范（写在Wiki里，没人看）"
stage_3: "SDD模板（嵌入AI工作流，自动执行）"
stage_4: "行业模板库（开源共享，持续进化）"
# 价值6: 降低AI幻觉风险
- name: "Reducing AI Hallucination Risk"
description: "用结构化约束减少AI的'创造性发挥'"
mechanism: |
AI的本质是概率模型——它倾向于生成"看起来合理"的内容。
SDD通过以下方式约束AI:
1. 明确的输入/输出格式 → 减少格式幻觉
2. 必须使用的库和版本 → 减少依赖幻觉
3. 禁止的模式列表 → 减少安全幻觉
4. 必须覆盖的场景 → 减少遗漏幻觉
二、SDD规范的核心结构
2.1 标准SDD文档结构
// types/sdd-spec.ts
// MonkeyCode SDD 规范的类型定义
/**
* SDD（Software Design Specification）— 软件设计规格说明书
*
* 这是MonkeyCode中驱动AI编码的核心文档类型。
* 一个完整的SDD包含以下所有章节（可根据项目复杂度裁剪）。
*/
export interface SDDDocument {
// ========== 元信息 ==========
meta: SDDMeta;
// ========== 第一章：概述 ==========
overview: SDDOverview;
// ========== 第二章：功能需求 ==========
functionalRequirements: SDDFunctionalRequirements;
// ========== 第三章：非功能需求 ==========
nonFunctionalRequirements: SDDNonFunctionalRequirements;
// ========== 第四章：架构设计 ==========
architecture: SDDArchitecture;
// ========== 第五章：接口设计 ==========
apiDesign: SDDAPIDesign;
// ========== 第六章：数据设计 ==========
dataDesign: SDDDataDesign;
// ========== 第七章：安全设计 ==========
securityDesign: SDDSecurityDesign;
// ========== 第八章：测试策略 ==========
testingStrategy: SDDTestingStrategy;
// ========== 第九章：部署运维 ==========
deploymentOps: SDDDeploymentOps;
}
// ======== 各章节详细定义 ========
interface SDDMeta {
/** SDD唯一标识符 */
sddId: string; // 格式: SDD-{project}-{module}-{version}
// 例: SDD-user-service-auth-v2
/** 关联的需求编号 */
requirementIds: string[]; // 如 ["REQ-AUTH-001", "JIRA-PROJ-123"]
/** 版本号（语义化版本） */
version: string; // 如 "2.1.0"
/** 创建日期 */
createdAt: string; // ISO 8601
/** 最后更新日期 */
updatedAt: string;
/** 作者/负责人 */
author: string;
/** 审核人 */
reviewers: string[];
/** 状态 */
status: 'draft' | 'review' | 'approved' | 'deprecated' | 'archived';
/** 适用范围 */
scope: {
project: string;
modules: string[];
team: string;
};
/** 关键词（用于检索和分类） */
tags: string[];
/** 变更记录 */
changelog: SDDChangeLog[];
}
interface SDDChangeLog {
version: string;
date: string;
author: string;
changes: string[];
type: 'major' | 'minor' | 'patch' | 'breaking';
}
interface SDDOverview {
/** 一句话描述这个模块做什么 */
summary: string;
/** 详细背景和上下文 */
background: string;
/** 解决什么问题 */
problemStatement: string;
/** 目标用户/调用方 */
stakeholders: string[];
/** 与其他模块的关系 */
dependencies: {
upstream: SDDDependency[]; // 依赖谁
downstream: SDDDependency[]; // 被谁依赖
};
/** 核心术语表（确保全员理解一致） */
glossary: Record<string, string>;
/** 设计原则和决策依据 */
designPrinciples: SDDDesignDecision[];
}
interface SDDDependency {
module: string;
interface: string;
type: 'sync' | 'async' | 'event';
criticality: 'critical' | 'high' | 'medium' | 'low';
fallback?: string; // 降级方案
}
interface SDDDesignDecision {
id: string; // 如 "ADR-001"
title: string;
context: string; // 为什么面临这个选择
decision: string; // 最终决定
consequences: {
positive: string[];
negative: string[];
};
alternatives: Array<{ option: string; rejectedReason: string }>;
}
// ... 其他接口定义类似，此处省略以节省篇幅
// 完整定义见: https://github.com/chaitin/monkeycode/blob/main/packages/sdd/types/index.ts
2.2 最小可用SDD（MVP版）
# sdd-templates/minimal-sdd.yaml
# 最小可用SDD模板 —— 适合简单功能模块
# 使用场景: 工具函数、简单CRUD、配置项等不需要复杂设计的场景
# 复杂度等级: ⭐ (1/5)
# 预计填写时间: 5-10分钟
sdd_template:
name: "Minimal SDD"
version: "1.0"
complexity: "minimal"
sections:
# 唯一必须填写的部分
- section: "Identity"
required: true
fields:
- name: "Module Name"
desc: "模块/功能的名称"
example: "Password Hashing Utility"
validation: "必填，不超过50字符"
- name: "Purpose"
desc: "一句话说明这个模块做什么"
example: "提供密码哈希和验证功能，支持bcrypt和argon2两种算法"
validation: "必填，不超过200字符"
- name: "Entry Point"
desc: "主要的导出函数/类/接口"
example: "export { hashPassword, verifyPassword } from './crypto'"
validation: "必填"
# 强烈推荐的部分
- section: "Interface Contract"
required: true
fields:
- name: "Input/Output Types"
desc: "函数签名或接口定义"
example: |
interface PasswordService {
hashPassword(plain: string): Promise<string>
verifyPassword(plain: string, hash: string): Promise<boolean>
}
- name: "Error Cases"
desc: "可能抛出的异常/返回的错误码"
example: |
- EmptyPasswordError: 输入为空
- WeakPasswordError: 强度不足（可选启用）
- HashError: 哈希计算失败
- name: "Constraints"
desc: "必须遵守的硬性约束"
example: |
- 密码长度: 8-128字符
- 哈希算法: bcrypt(cost>=12) 或 argon2(memory>=64MB)
- 禁止: MD5, SHA1, 明文存储
# 可选但有价值的部分
- section: "Quality Gates"
required: false
fields:
- name: "Test Coverage Target"
desc: "最低测试覆盖率要求"
default: "90%"
- name: "Performance Requirement"
desc: "性能指标"
example: "hashPassword < 500ms (bcrypt cost=12)"
- name: "Security Requirements"
desc: "安全相关要求"
example: |
- 通过OWASP Password Storage Cheat Sheet检查
- 不记录明文密码到任何日志
- 使用恒定时间比较防止时序攻击
---
# 使用示例（填充后）
filled_example:
module_name: "PasswordHasher"
purpose: "为认证服务提供安全的密码哈希和验证能力"
entry_point: "src/utils/password.ts"
interface_contract:
types: |
export interface IPasswordHasher {
/**
* 哈希明文密码
* @param plain 明文密码（8-128字符）
* @returns 哈希值（bcrypt $2b$ 格式）
*/
hash(plain: string): Promise<string>
/**
* 验证密码是否匹配
* @param plain 待验证的明文密码
* @param hash 已存储的哈希值
* @returns 是否匹配
*/
verify(plain: string, hash: string): Promise<boolean>
/**
* 检查密码强度
* @param plain 明文密码
* @returns 强度评估结果
*/
checkStrength(plain: string): PasswordStrengthResult
}
errors:
- { code: "ERR_EMPTY_PASSWORD", message: "密码不能为空", httpStatus: 400 }
- { code: "ERR_PASSWORD_TOO_LONG", message: "密码不能超过128字符", httpStatus: 400 }
- { code: "ERR_HASH_FAILED", message: "哈希计算失败", httpStatus: 500 }
constraints:
- "必须使用bcrypt（cost >= 12）或argon2id"
- "禁止使用MD5、SHA1、SHA256等快速哈希"
- "禁止在任何地方记录明文密码（包括日志）"
- "verify方法必须使用恒定时间比较（timing-safe compare）"
quality_gates:
test_coverage: "95%+"
performance: "hash() < 500ms (bcrypt cost=12), < 200ms (argon2id)"
security: |
- ✅ 通过MonkeyScan安全扫描
- ✅ 无已知CVE依赖
- ✅ 密码强度检查覆盖常见弱密码Top 1000
2.3 完整SDD模板（企业级）
# SDD-{PROJECT}-{MODULE}-{VERSION}
> **Software Design Specification — 软件设计规格说明书**
## 📋 文档元信息
| 字段 | 值 |
|------|-----|
| **SDD ID** | SDD-payment-gateway-v2.1 |
| **关联需求** | REQ-PAY-001 ~ REQ-PAY-015, JIRA-PAY-2024-089 |
| **版本** | 2.1.0 |
| **状态** | ✅ Approved |
| **作者** | 张三 (Tech Lead) |
| **审核** | 李四 (Architect), 王五 (Security) |
| **创建** | 2026-03-15 |
| **更新** | 2026-06-20 |
## 1. 概述
### 1.1 一句话总结
统一的支付网关服务，支持微信支付、支付宝、银联等多种支付渠道，提供幂等的订单创建、支付、退款全流程管理。
### 1.2 背景与上下文
当前系统存在三个独立的支付模块（分别对接微信、支付宝、银联），导致：
- 支付逻辑重复实现，维护成本高
- 对账逻辑分散，财务对账困难
- 新增支付渠道需要大量重复开发
- 缺乏统一的异常处理和降级策略
本SDD旨在设计一个统一的支付网关，解决上述问题。
### 1.3 利益相关方
| 角色 | 关注点 | 期望 |
|------|--------|------|
| 业务方 | 支付成功率 | >99.5%，支持主流渠道 |
| 财务 | 对账准确 | T+1自动对账，差异<0.01% |
| 运维 | 系统稳定性 | 可用性99.99%，P99延迟<500ms |
| 安全 | 资金安全 | 幂等性、防重放、加密传输 |
| 开发 | 开发效率 | 新增渠道<3天完成接入 |
### 1.4 模块依赖关系
┌──────────────┐
│ Order Service│ ← 下游：订单服务（创建支付订单）
└──────┬───────┘
│ RPC
┌──────▼───────┐
│ Payment GW │ ← 本模块（核心）
│ (本文档范围) │
└──┬───┬───┬───┘
│ │ │
┌───────┘ │ └───────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ WeChat │ │ Alipay │ │ UnionPay │
│ Pay API │ │ API │ │ API │
└──────────┘ └──────────┘ └──────────┘
上游依赖:
- Config Center: 渠道配置、密钥管理
- Redis: 分布式锁、幂等Key存储
- DB(MySQL): 订单流水、对账记录
- Message Queue(Kafka): 支付事件通知
## 2. 功能需求
### 2.1 功能清单
| ID | 功能 | 优先级 | 复杂度 | 说明 |
|----|------|--------|--------|------|
| F001 | 创建支付订单 | P0 | 中 | 统一的订单创建接口 |
| F002 | 发起支付 | P0 | 中 | 调用第三方支付SDK |
| F003 | 支付回调处理 | P0 | 高 | 异步回调验签和处理 |
| F004 | 支付结果查询 | P0 | 低 | 主动查询支付状态 |
| F005 | 退款 | P1 | 中 | 全额/部分退款 |
| F006 | 对账 | P1 | 高 | T+1自动对账 |
| F007 | 渠道路由 | P1 | 中 | 智能选择最优渠道 |
| F008 | 降级策略 | P2 | 中 | 渠道故障自动切换 |
### 2.2 核心流程：支付主流程
用户下单 → 创建支付订单(F001)
↓
选择支付渠道(F007)
↓
调起支付SDK(F002)
↓
┌─────────┴─────────┐
▼ ▼
用户完成支付 用户取消/超时
↓ ↓
回调通知(F003) 订单超时关闭
↓
验签 + 幂等检查
↓
更新订单状态
↓
发送支付成功事件(Kafka)
↓
通知下游(Order Service)
## 3. 非功能需求
### 3.1 性能要求
| 指标 | 目标值 | 测量方式 |
|------|--------|----------|
| 创建订单P50延迟 | < 100ms | Prometheus histogram |
| 创建订单P99延迟 | < 300ms | Prometheus histogram |
| 支付回调处理 | < 200ms | 从接收到处理完成 |
| 并发支撑 | 5000 QPS | 压测验证 |
| 吞吐量 | 10000 TPS | 峰值容量 |
### 3.2 可靠性要求
| 指标 | 目标值 |
|------|--------|
| 服务可用性(SLA) | 99.99%/月（停机<4.3分钟） |
| 数据持久性 | 99.999999%（9个9） |
| RTO（恢复时间目标） | < 30秒 |
| RPO（恢复点目标） | = 0（同步复制） |
| 降级可用能力 | 核心支付功能在DB故障时可降级只读 |
### 3.3 安全要求
| 要求 | 具体措施 |
|------|----------|
| 传输加密 | 全链路TLS 1.3 |
| 敏感数据加密 | 支付密钥AES-256-GCM加密存储 |
| 幂等性 | 所有写操作基于业务唯一ID做幂等 |
| 防重放 | 回调请求5分钟内不处理相同请求 |
| 操作审计 | 所有资金操作记录完整审计日志 |
| 访问控制 | RBAC + 最小权限原则 |
## 4. 架构设计
### 4.1 技术选型
| 层面 | 选型 | 理由 |
|------|------|------|
| 语言 | TypeScript (Node.js) | 团队熟悉度 + 异步IO适合支付场景 |
| 框架 | NestJS | 企业级框架，内置DI/Middleware/Guard |
| ORM | TypeORM | 类型安全，支持多数据源 |
| 缓存 | Redis Cluster | 高性能 + 分布式锁 |
| MQ | Apache Kafka | 事件驱动，保证顺序 |
| DB | MySQL 8.0 (主从) | ACID事务保证 |
| 配置 | Apollo/Nacos | 动态配置 + 灰度发布 |
| 监控 | Prometheus + Grafana + AlertManager | 全链路可观测 |
### 4.2 模块划分
src/
├── modules/
│ ├── payment-order/ # 支付订单管理
│ │ ├── payment-order.service.ts
│ │ ├── payment-order.entity.ts
│ │ └── payment-order.repository.ts
│ │
│ ├── channel/ # 渠道适配层（策略模式）
│ │ ├── channel.strategy.interface.ts
│ │ ├── wechat-pay.strategy.ts
│ │ ├── alipay.strategy.ts
│ │ ├── unionpay.strategy.ts
│ │ └── channel-router.service.ts
│ │
│ ├── callback/ # 回调处理
│ │ ├── callback.controller.ts
│ │ ├── callback.service.ts
│ │ └── signature.verifier.ts
│ │
│ ├── refund/ # 退款
│ │ └── refund.service.ts
│ │
│ ├── reconciliation/ # 对账
│ │ └── reconciliation.job.ts
│ │
│ └── common/ # 公共组件
│ ├── idempotency.guard.ts # 幂等守卫
│ ├── encrypt.util.ts # 加密工具
│ ├── payment.exception.ts # 异常体系
│ └── audit.log.decorator.ts # 审计日志装饰器
│
├── config/
│ ├── payment.config.ts
│ └── channels.config.ts
│
└── tests/
├── unit/
├── integration/
└── e2e/
## 5. 接口设计
### 5.1 RESTful API 定义
#### POST /api/v1/payment/orders — 创建支付订单
```typescript
// 请求
interface CreatePaymentOrderRequest {
/** 业务订单号（由Order Service生成） */
bizOrderId: string;
/** 支付金额（单位：分） */
amount: number;
/** 货币代码 */
currency: 'CNY' | 'USD';
/** 商品描述 */
subject: string;
/** 用户ID */
userId: string;
/** 可选支付渠道（不传则自动路由） */
preferredChannel?: 'wechat' | 'alipay' | 'unionpay';
/** 过期时间（秒），默认30分钟 */
expireSeconds?: number;
/** 扩展元数据（透传给支付渠道） */
metadata?: Record<string, string>;
/** 客户端IP（风控用） */
clientIp: string;
}
// 响应
interface CreatePaymentOrderResponse {
/** 支付订单号 */
paymentOrderId: string;
/** 支付状态 */
status: 'PENDING' | 'PROCESSING';
/** 支付参数（直接传给前端调起支付SDK） */
payParams: WechatPayParams | AlipayParams | UnionPayParams;
/** 过期时间 */
expireAt: string; // ISO 8601
}
POST /api/v1/payment/callback/{channel} — 支付回调
// 注意：此接口由第三方支付平台调用，需做严格的验签
// 请求体因渠道而异，统一经过signature.verifier处理后转为内部事件
GET /api/v1/payment/orders/{orderId} — 查询订单
interface PaymentOrderResponse {
paymentOrderId: string;
bizOrderId: string;
status: PaymentStatus;
amount: number;
paidAmount: number;
channel: string;
channelTransactionId: string;
createdAt: string;
paidAt?: string;
expiredAt: string;
}
5.2 内部事件定义（Kafka）
// Topic: payment-events
interface PaymentEvent {
eventType:
| 'PAYMENT_CREATED'
| 'PAYMENT_SUCCESS'
| 'PAYMENT_FAILED'
| 'PAYMENT_EXPIRED'
| 'REFUND_INITIATED'
| 'REFUND_SUCCESS'
| 'REFUND_FAILED'
| 'RECONCILIATION_COMPLETE';
eventId: string; // UUID
timestamp: string; // ISO 8601
traceId: string; // 链路追踪ID
payload: {
paymentOrderId: string;
bizOrderId: string;
amount: number;
channel: string;
// ... 事件特有字段
};
}
6. 数据设计
6.1 ER图（核心实体）
┌─────────────────────┐ ┌─────────────────────┐
│ payment_order │ │ payment_refund │
├─────────────────────┤ ├─────────────────────┤
│ PK id (BIGINT) │──┐ │ PK id (BIGINT) │
│ payment_order_id │ │ │ FK order_id │
│ biz_order_id │ │ │ refund_no │
│ amount │ └───▶│ refund_amount │
│ status │ │ status │
│ channel │ │ reason │
│ channel_txn_id │ │ created_at │
│ pay_params(JSON) │ └─────────────────────┘
│ expired_at │
│ paid_at │ ┌─────────────────────┐
│ created_at │ │ reconciliation_log │
│ updated_at │ ├─────────────────────┤
└─────────────────────┘ │ PK id │
│ reconcile_date │
│ channel │
│ total_count │
│ total_amount │
│ success_count │
│ success_amount │
│ diff_count │
│ diff_details(JSON)│
│ status │
└─────────────────────┘
6.2 关键索引
-- payment_order 表索引
CREATE UNIQUE INDEX uk_payment_order_id ON payment_order(payment_order_id);
CREATE INDEX idx_biz_order_id ON payment_order(biz_order_id);
CREATE INDEX idx_status_created ON payment_order(status, created_at);
CREATE INDEX idx_channel_status ON payment_order(channel, status);
-- 幂等Key索引（防止重复支付）
CREATE UNIQUE INDEX uk_idempotent_key ON payment_order(idempotent_key);
7. 安全设计
7.1 威胁模型
| 威胁 | 风险等级 | 防护措施 |
|---|---|---|
| 回调伪造 | 🔴 Critical | RSA/SHA256双重验签 + IP白名单 |
| 金额篡改 | 🔴 Critical | 服务端金额校验 + 签名验证 |
| 重放攻击 | 🟠 High | nonce + timestamp + 5分钟窗口 |
| 订单信息泄露 | 🟠 High | 敏感字段加密存储 + 访问控制 |
| 并发重复支付 | 🟠 High | 分布式锁 + 幂等检查 |
| 中间人攻击 | 🟡 Medium | 全链路TLS + 证书固定(Pinning) |
7.2 加密方案
// 敏感字段加密示例
const ENCRYPTION_CONFIG = {
algorithm: 'aes-256-gcm',
keyRotationDays: 90,
encryptedFields: [
'pay_params', // 支付参数含敏感信息
'channel_txn_id', // 渠道交易凭证
'user_identity', // 用户身份信息
],
};
8. 测试策略
8.1 测试矩阵
| 测试类型 | 覆盖目标 | 工具 | 自动化 |
|---|---|---|---|
| 单元测试 | 核心逻辑覆盖率>90% | Jest | ✅ CI自动运行 |
| 集成测试 | API接口+DB交互 | Supertest | ✅ CI自动运行 |
| 契约测试 | 渠道SDK交互 | Pact | ✅ CI自动运行 |
| E2E测试 | 完整支付流程 | Playwright | ✅ 每日夜间 |
| 压力测试 | 性能指标达标 | k6/Artillery | ✅ 发版前必跑 |
| 安全测试 | OWASP Top 10 | MonkeyScan | ✅ 每次PR触发 |
| 混沌测试 | 故障恢复能力 | Chaos Mesh | ✅ 每周一次 |
8.2 关键测试用例
// 核心测试场景（必须全部通过才能合并）
const CRITICAL_TEST_CASES = [
// 正常流程
{ name: '正常创建订单并支付', priority: 'P0' },
{ name: '支付回调正确处理', priority: 'P0' },
{ name: '退款全流程', priority: 'P0' },
// 异常流程
{ name: '重复回调幂等处理', priority: 'P0' },
{ name: '回调签名伪造拒绝', priority: 'P0' },
{ name: '订单过期自动关闭', priority: 'P0' },
{ name: '金额不一致拒绝', priority: 'P0' },
{ name: '并发支付只成功一笔', priority: 'P0' },
// 边界条件
{ name: '金额为0拒绝', priority: 'P1' },
{ name: '金额超大值处理', priority: 'P1' },
{ name: '特殊字符注入', priority: 'P1' },
{ name: '超长subject截断', priority: 'P2' },
];
9. 部署运维
9.1 部署架构
# Kubernetes部署规格
deployment:
replicas: 3
resources:
requests:
cpu: "500m"
memory: "512Mi"
limits:
cpu: "2000m"
memory: "2Gi"
healthCheck:
livenessPath: /health/live
readinessPath: /health/ready
strategy:
type: RollingUpdate
maxUnavailable: 0
maxSurge: 1
podDisruptionBudget:
minAvailable: 2
autoscaling:
minReplicas: 3
maxReplicas: 20
targetCPUUtilization: 70
targetMemoryUtilization: 80
9.2 监控告警
alerts:
- name: "PaymentOrderCreationHighLatency"
condition: "histogram_quantile(0.95, payment_order_duration_seconds) > 0.5"
severity: warning
action: "slack + pagerduty"
- name: "PaymentCallbackFailureRate"
condition: "rate(payment_callback_errors_total[5m]) / rate(callback_requests_total[5m]) > 0.05"
severity: critical
action: "pagerduty + phone"
- name: "PendingOrderBacklog"
condition: "payment_orders_pending_count > 1000"
severity: warning
action: "slack"
附录
A. 变更记录
| 版本 | 日期 | 作者 | 变更内容 |
|---|---|---|---|
| 1.0.0 | 2026-03-15 | 张三 | 初始版本 |
| 2.0.0 | 2026-05-10 | 张三 | 新增银联渠道支持 |
| 2.1.0 | 2026-06-20 | 李四 | 优化对账逻辑，增加差异自动修复 |
B. 参考资料
C. ADR记录
---
## 三、行业级SDD模板库
### 3.1 模板分类总览
MonkeyCode SDD 模板库 (v2.0):
📁 sdd-templates/
│
├── 📄 by-complexity/ # 按复杂度分类
│ ├── minimal-sdd.yaml # ⭐ 最简版（工具函数/简单CRUD）
│ ├── standard-sdd.yaml # ⭐⭐ 标准版（常规业务模块）
│ ├── advanced-sdd.yaml # ⭐⭐⭐ 进阶版（核心系统/复杂业务）
│ └── enterprise-sdd.yaml # ⭐⭐⭐⭐ 企业版（金融/政务/医疗）
│
├── 📄 by-domain/ # 按领域分类
│ ├── web-api-sdd.yaml # Web API服务
│ ├── microservice-sdd.yaml # 微服务模块
│ ├── data-pipeline-sdd.yaml # 数据管道/ETL
│ ├── mobile-backend-sdd.yaml # 移动端后端
│ ├── admin-panel-sdd.yaml # 管理后台
│ ├── scheduled-job-sdd.yaml # 定时任务/批处理
│ └── library-sdk-sdd.yaml # 库/SDK/公共组件
│
├── 📄 by-industry/ # 按行业分类
│ ├── fintech-sdd.yaml # 金融科技（支付/风控/合规）
│ ├── healthcare-sdd.yaml # 医疗健康（HIPAA/隐私保护）
│ ├── ecommerce-sdd.yaml # 电商（商品/订单/库存/物流）
│ ├── edtech-sdd.yaml # 教育（课程/考试/学习路径）
│ ├── govtech-sdd.yaml # 政务信息化（等保/国密/审批流）
│ └── iot-sdd.yaml # IoT物联网（设备管理/协议适配）
│
├── 📄 by-framework/ # 按技术栈分类
│ ├── nestjs-sdd.yaml # NestJS (TypeScript)
│ ├── springboot-sdd.yaml # Spring Boot (Java)
│ ├── django-sdd.yaml # Django (Python)
│ ├── gin-sdd.yaml # Gin (Go)
│ ├── nextjs-sdd.yaml # Next.js (React Fullstack)
│ └── rails-sdd.yaml # Ruby on Rails
│
└── 📄 custom/ # 自定义模板（企业内部）
└── my-company-sdd.yaml # 你公司的定制模板
### 3.2 金融科技SDD模板（重点展示）
```yaml
# sdd-templates/by-industry/fintech-sdd.yaml
# 金融科技行业专用SDD模板
template_info:
name: "FinTech SDD Template"
industry: "Financial Technology"
compliance_frameworks:
- "PCI-DSS v4.0" # 支付卡行业数据安全标准
- "等保三级" # 中国网络安全等级保护
- "GDPR" # 欧盟通用数据保护条例
- "人行支付清算管理办法" # 中国央行监管要求
complexity: "enterprise"
estimated_fill_time: "2-4小时"
# ======== 金融行业特有的额外章节 ========
extra_sections:
# 合规章节（金融必备）
- section: "Compliance & Regulatory"
required: true
subsections:
- name: "Data Classification"
template: |
## 数据分级
| 级别 | 定义 | 示例 | 存储要求 | 传输要求 |
|------|------|------|----------|----------|
| L4-绝密 | 核心密钥 | 支付私钥 | HSM硬件加密 | 端到端加密 |
| L3-机密 | 个人敏感 | 身份证号 | AES-256加密 | TLS + 字段加密 |
| L2-秘密 | 业务数据 | 交易金额 | 透明加密 | TLS 1.3 |
| L1-公开 | 公开信息 | 商品名称 | 明文 | HTTPS |
- name: "Audit Trail Requirements"
template: |
## 审计日志规范
- 所有资金操作必须记录完整审计日志
- 日志保留期限: ≥ 7年（监管要求）
- 日志不可篡改（WORM存储或区块链存证）
- 必须记录的字段:
* 操作者身份（who）
* 操作时间（when）
* 操作内容（what - before/after快照）
* 操作原因（why）
* 操作来源IP（where）
* 关联的业务单据号（which）
- name: "Regulatory Reporting"
template: |
## 监管报送
### 大额交易报告
- 单笔≥5万人民币或等值外币 → 自动触发大额报告
- 当日累计≥20万人民币 → 自动触发可疑报告
### 报送时效
- 大额交易报告: T+1
- 可疑交易报告: 10个工作日内
- 数据格式: 符合人行XML Schema
# 风控章节
- section: "Risk Control"
required: true
subsections:
- name: "Fraud Prevention"
template: |
## 反欺诈策略
### 设备指纹
- 收集设备指纹（设备ID、IP、UA、地理位置）
- 异常设备标记（模拟器/Root/代理IP）
### 行为分析
- 用户行为基线建立（首次使用→正常模式）
- 异常行为检测:
* 异地登录（距离上次>500km且<1h）
* 非正常时间段操作（凌晨0-5点高频操作）
* 操作频率异常（短时间内大量请求）
### 规则引擎
```yaml
risk_rules:
- rule: "HIGH_FREQUENCY_ORDER"
condition: "orders_last_10min > 10"
action: "require_captcha + manual_review"
score: 80
- rule: "NEW_DEVICE_LARGE_AMOUNT"
condition: "is_new_device AND amount > 10000"
action: "require_sms_otp + step_up_auth"
score: 70
- rule: "VELOCITY_CHECK"
condition: "amount_change_rate > 500%"
action: "freeze_account + alert_fraud_team"
score: 95
```
- name: "Transaction Limits"
template: |
## 交易限额
| 场景 | 单笔限额 | 日累计限额 | 月累计限额 |
|------|----------|------------|------------|
| 个人转账 | ¥50,000 | ¥100,000 | ¥500,000 |
| 商户收款 | ¥100,000 | ¥1,000,000 | ¥10,000,000 |
| 国际汇款 | $5,000 | $10,000 | $50,000 |
### 特殊处理
- 超限额 → 需要高级别认证（人脸+U盾）
- 连续3次超限额 → 冻结账户，人工审核
- 可疑交易 → 延迟结算（T+7）
# 容灾章节
- section: "Business Continuity"
required: true
subsections:
- name: "DR Strategy"
template: |
## 灾难恢复策略
### RTO/RPO目标
| 场景 | RTO | RPO | 方案 |
|------|-----|-----|------|
| 单节点故障 | <30s | 0 | K8s自动迁移 |
| AZ整体故障 | <5min | <1min | 跨AZ热备切换 |
| Region级故障 | <30min | <5min | 异地双活 |
### 数据备份
- 实时备份: 主从同步（异步→最终一致性）
- 定期快照: 每日全量 + 每小时增量
- 跨地域复制: 异步复制到备用Region
- 备份加密: AES-256 at rest
- 备份验证: 每周随机抽取恢复验证
- name: "Degradation Plan"
template: |
## 降级预案
### Level 1: 渠道降级
- 触发: 某渠道成功率<90%
- 动作: 自动切换到备用渠道
- 影响: 用户无感知
### Level 2: 功能降级
- 触发: 所有渠道不可用
- 动作:
* 暂停新订单创建
* 已创建订单进入排队队列
* 展示"维护中"提示
- 影响: 无法新建支付，已有订单不受影响
### Level 3: 只读模式
- 触发: 数据库主库不可用
- 动作:
* 切换到只读从库
* 仅支持查询和退款
* 新建订单返回"暂时不可用"
- 影响: 核心读功能保持，写功能暂停
四、如何在MonkeyCode中使用SDD
4.1 基本使用流程
使用SDD驱动的AI编码完整流程:
Step 1: 选择/创建SDD模板
│
├─ 方式A: 从模板库选择现成模板
│ monkeycode sdd init --template fintech --name my-payment
│
├─ 方式B: 基于现有代码逆向生成SDD
│ monkeycode sdd generate-from-code ./src/payment
│
└─ 方式C: 从头编写（使用AI辅助）
monkeycode chat "帮我为支付网关创建一个金融级SDD文档"
│
▼
Step 2: 填充SDD内容（可AI辅助）
│
├─ AI可以帮你:
│ • 根据需求描述生成初稿
│ • 补充安全/性能/测试章节
│ • 检查完整性（是否有遗漏的关键章节）
│
└─ 你需要确认/修改:
• 业务特定的决策和权衡
• 团队的技术偏好
• 外部依赖和集成细节
│
▼
Step 3: 审批SDD（可选，推荐团队协作）
│
├─ Tech Lead审核: 架构合理性
├─ Security审核: 安全要求完备性
└─ PM确认: 功能需求覆盖完整性
│
▼
Step 4: 基于SDD进行AI编码
│
└─ 命令示例:
monkeycode gen --sdd ./sdd/payment-gateway-v2.yml \
--module payment-order \
--output src/modules/payment-order \
--with-tests \
--security-scan
│
▼
Step 5: 自动验证
│
├─ 代码是否符合SDD中的接口定义？ ✓
├─ 是否使用了指定的技术栈？ ✓
├─ 安全要求是否满足？ ✓
├─ 测试覆盖率是否达标？ ✓
└─ 性能指标是否满足？ ✓
│
▼
Step 6: 提交Review + 发布
│
└─ MR自动携带:
• SDD引用链接
• AI Review意见
• 安全扫描报告
• 测试覆盖率报告
4.2 CLI命令速查
# ======== SDD管理命令 ========
# 初始化一个新的SDD（从模板）
monkeycode sdd init \
--template enterprise \ # 模板名称
--name payment-gateway \ # SDD名称
--output ./sdd/ \ # 输出目录
--interactive # 交互式填写
# 从现有代码逆向生成SDD
monkeycode sdd reverse \
--source ./src/services/payment \
--output ./sdd/generated-payment.yml \
--include-tests \
--include-comments
# 验证SDD文件的完整性和有效性
monkeycode sdd validate \
--file ./sdd/payment-gateway-v2.yml \
--strict # 严格模式（所有required字段必须填写）
# 基于SDD生成代码
monkeycode gen \
--sdd ./sdd/payment-gateway-v2.yml \
--target all \ # 生成所有模块，或指定具体模块
--with-tests \ # 同时生成测试
--with-docs \ # 同时生成API文档
--security-level high \ # 安全级别
--output ./src/
# 将SDD关联到当前会话（聊天模式）
monkeycode chat \
--context-sdd ./sdd/payment-gateway-v2.yml \
"帮我实现F003支付回调处理模块"
# 检查代码是否符合SDD规范
monkeycode check \
--sdd ./sdd/payment-gateway-v2.yml \
--source ./src/modules/payment/ \
--report-format json \
--output ./check-report.json
# 导出SDD为多种格式
monkeycode sdd export \
--file ./sdd/payment-gateway-v2.yml \
--format markdown \ # markdown | html | pdf | openapi
--output ./docs/
# 版本管理和变更追踪
monkeycode sdd diff \
--old ./sdd/payment-v1.yml \
--new ./sdd/payment-v2.yml \
--output ./sdd-changelog.md
五、SDD最佳实践
5.1 编写高质量SDD的原则
╔══════════════════════════════════════════════════════╗
║ SDD编写的黄金法则 ║
║ ║
║ 📏 法则1: 具体优于抽象 ║
║ ❌ "代码要高效" ║
║ ✅ "P99响应时间<300ms，使用Redis缓存热点数据" ║
║ ║
║ 📏 法则2: 约束优于建议 ║
║ ❌ "建议使用TypeScript" ║
║ ✅ "必须使用TypeScript，禁用any类型" ║
║ ║
║ 📏 法则3: 可测量优于主观 ║
║ ❌ "测试要充分" ║
║ ✅ "分支覆盖率≥85%，关键路径覆盖率=100%" ║
║ ║
║ 📏 法则4: 示例优于描述 ║
║ ❌ "错误码按照规范定义" ║
║ ✅ "错误码格式: ERR_{MODULE}_{SPECIFIC}" ║
║ ✅ 示例: ERR_PAY_INVALID_AMOUNT, ERR_AUTH_TOKEN_EXP║
║ ║
║ 📏 法则5: 渐进优于一步到位 ║
║ 不要试图一次性写出完美的SDD ║
║ 先写核心（Identity + Interface + Constraints） ║
║ 再逐步补充（Security + Testing + Ops） ║
║ 每次迭代都产出可用的中间版本 ║
║ ║
║ 📏 法则6: 活文档优于死文档 ║
║ SDD不是写了就不动的 ║
║ 随着代码演进持续更新 ║
║ 建议每次大版本发布时回顾并更新SDD ║
║ ║
╚══════════════════════════════════════════════════════╝
5.2 常见误区
⚠️ 误区1: SDD = 需求文档
✗ 把产品需求(PRD)原封不动搬进SDD
✓ SDD关注的是"怎么实现"，不是"做什么"
PRD回答"What & Why"，SDD回答"How & With What Constraints"
⚠️ 误区2: SDD越详细越好
✗ 写了100页的SDD，没人看得完
✓ 好的SDD应该能在30分钟内读完核心内容
详细信息放在附录或链接引用
⚠️ 误区3: SDD写完就不用管了
✗ 项目开始时写了一版SDD，之后从未更新
✓ SDD应该随着代码一起演进
建议在MR描述中引用相关SDD，方便reviewer对照
⚠️ 误区4: 只有大型项目才需要SDD
✗ "我们是个小项目，不需要这么正式"
✓ 小项目更需要SDD！因为：
- 小项目人员流动大，知识容易丢失
- 小项目更容易走捷径产生技术债务
- SDD的最小模板只需要5-10分钟就能填完
⚠️ 误区5: SDD会拖慢开发速度
✗ "写SDD的时间够我写完代码了"
✓ 数据表明：
- 有SDD的项目，首次提交通过率高40%
- Code Review返工率降低60%
- 总体开发周期反而缩短15-25%
- 因为减少了"返工→再返工"的循环
六、总结
╔══════════════════════════════════════════════════════╗
║ ║
║ MonkeyCode SDD模板库的核心价值: ║
║ ║
║ 🎯 让AI理解你的标准 ║
║ 不是教AI怎么写代码，而是告诉AI你的标准是什么 ║
║ ║
║ 🎯 让团队达成共识 ║
║ SDD是团队对"好代码"的共同契约 ║
║ ║
║ 🎯 让质量可预期 ║
║ 有SDD约束的代码，质量从第一天就是可控的 ║
║ ║
║ 🎯 让知识可沉淀 ║
║ 最佳实践不再是某人的经验，而是团队的资产 ║
║ ║
║ 💬 一句话总结: ║
║ "SDD是你和AI之间的共同语言。" ║
║ ║
║ 🚀 立即开始: ║
║ monkeycode sdd init --template standard --name demo ║
║ ║
╚══════════════════════════════════════════════════════╝
系列导航
- 上一篇：《用MonkeyCode构建AI原生DevOps流水线》
- 下一篇：《MonkeyCode安全规则库：200+条实战规则详解》
- 系列目录：[MonkeyCode开源完全指南（2026版）— 30篇系列索引](待整理）
本文基于MonkeyCode开源项目的SDD规范系统和模板库编写，所有模板均可在v1.2.x版本中使用。
关键词：#MonkeyCode #SDD #软件设计规范 #模板库 #AI编程 #代码质量 #最佳实践 #企业级 #技术规范 #开发标准
浙公网安备 33010602011771号