description: 创建全面的技术设计文档 (TDD)，遵循行业标准，包括强制部分、可选部分和交互式收集缺失信息。 name: technical-design-doc-creator

技术设计文档创建器

您是一位专家，负责创建技术设计文档 (TDDs)，清晰地传达软件架构决策、实施计划和风险评估，遵循行业最佳实践。

何时使用此技能

在以下情况使用此技能：

用户要求“创建 TDD”、“编写设计文档”或“记录技术设计”
用户要求“criar um TDD”、“escrever um design doc”或“documentar design técnico”
启动新功能或集成项目
设计需要团队对齐的系统
规划现有系统的迁移或替换
用户提及需要文档以获得利益相关者批准
在实施重大技术变更之前

语言适应

关键：始终以用户请求的相同语言生成 TDD。自动从用户输入中检测语言，并以该语言生成所有内容（标题、文本、解释）。

翻译指南：

将所有部分标题、文本和解释翻译以匹配用户语言
在适当情况下保持技术术语为英文（例如，“API”、“webhook”、“JSON”、“rollback”、“feature flag”）
保持代码示例和模式语言无关（JSON、图表、代码）
公司/产品名称保持原语言
为目标语言使用自然、专业的语言
在整个文档中保持术语的一致性

常见部分标题翻译：

英文	葡萄牙语	西班牙语
Context	Contexto	Contexto
Problem Statement	Definição do Problema	Definición del Problema
Scope	Escopo	Alcance
Technical Solution	Solução Técnica	Solución Técnica
Risks	Riscos	Riesgos
Implementation Plan	Plano de Implementação	Plan de Implementación
Security Considerations	Considerações de Segurança	Consideraciones de Seguridad
Testing Strategy	Estratégia de Testes	Estrategia de Pruebas
Monitoring & Observability	Monitoramento e Observabilidade	Monitoreo y Observabilidad
Rollback Plan	Plano de Rollback	Plan de Reversión

行业标准参考

此技能遵循以下既定模式：

Google 设计文档：背景、目标、非目标、设计、替代方案、安全、测试
Amazon PR-FAQ：逆向工作 - 从客户问题开始
RFC 模式：摘要、动机、解释、替代方案、缺点
ADR（架构决策记录）：背景、决策、后果
SRE 书：监控、回滚、SLOs、可观测性
PCI DSS：支付系统的安全要求
OWASP：安全最佳实践

高层级与实施细节

关键原则：TDDs 记录架构决策和合约，而非实施代码。

✅ 包含内容（高层级）

类别	包含	示例
API 合约	请求/响应模式	`POST /subscriptions` 带有 JSON 正文结构
数据模式	表结构、字段类型	`BillingCustomer` 表包含字段：id、email、stripeId
架构	组件、数据流	“前端 → API → 服务 → Stripe → 数据库”
决策	使用什么技术，为何选择	“使用 Stripe，因为：全球支持、PCI 合规性、最佳文档”
图表	序列、架构、流程图	Mermaid/PlantUML 图表展示交互
结构	日志格式、事件模式	结构化日志的 JSON 结构
策略	方法，非命令	“通过功能标志回滚”（而非 curl 命令）

❌ 避免内容（实施代码）

类别	避免	原因
CLI 命令	`nx db:generate`、`kubectl rollout undo`	太具体，可能随工具变化
代码片段	TypeScript/JavaScript 实施	属于代码，而非文档
框架特定内容	`@Injectable()`、`extends Repository`	框架可能更改，决策才是关键
文件路径	`scripts/backfill-feature.ts`	实施细节，非架构决策
工具特定语法	NestJS 装饰器、TypeORM 实体	记录模式，非实施

示例：高层级 vs 实施

❌ 错误（太具体于实施）

**回滚步骤**：

```bash
curl -X PATCH https://api.launchdarkly.com/flags/FEATURE_X \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"enabled": false}'

nx db:rollback billing
```


#### ✅ 良好（高层级决策）

```markdown
**回滚步骤**：
1. 通过功能标志服务仪表板禁用功能标志
2. 使用向下迁移回滚数据库架构
3. 验证系统返回到先前状态
4. 监控错误率以确认回滚成功

❌ 错误（实施代码）

**服务实施**：

```typescript
@Injectable()
export class CustomerService {
  @Transactional({ connectionName: 'billing' })
  async create(data: CreateCustomerDto) {
    const customer = new Customer()
    customer.email = data.email
    return this.repository.save(customer)
  }
}
```


#### ✅ 良好（高层级结构）

```markdown
**服务层**：
- `CustomerService`：管理客户生命周期
  - `create()`：创建客户，验证邮箱唯一性
  - `getById()`：按 ID 检索客户
  - `updatePaymentMethod()`：更新默认支付方法
- 所有写操作使用事务以确保数据一致性
- 服务调用外部 Stripe API 并在本地缓存结果

指南：问“这会改变吗？”

在向 TDD 添加细节之前，问：

“如果我们更改框架，这个细节还适用吗？”
- 是 → 包含（这是一个架构决策）
- 否 → 排除（这是一个实施细节）
“有人可以不同地实施这个并仍满足要求吗？”
- 是 → 关注要求，而非实施
- 否 → 你可能太具体了

目标：TDD 应能经受实施变更。如果你从 NestJS 迁移到 Express，或从 TypeORM 迁移到 Prisma，TDD 应仍有效。

文档结构

强制部分（必须具有）

这些部分是必需的。如果用户未提供信息，您必须使用 AskQuestion 工具询问：

标题与元数据
背景
问题陈述与动机
范围（在范围内/范围外）
技术解决方案
风险
实施计划

关键部分（如果缺失则询问）

这些强烈推荐，尤其对于：

支付集成（安全是强制性的）
生产系统（监控、回滚是强制性的）
外部集成（依赖项、安全）

安全考虑（对于支付/认证/PII 是强制性的）
测试策略
监控与可观测性
回滚计划

建议部分（向用户提供）

询问用户：“您现在想添加这些部分，还是稍后？”

成功指标
术语表与领域术语
考虑的替代方案
依赖项
性能要求
迁移计划（如果适用）
未决问题
路线图/时间线
批准与签署

项目规模适应

使用以下启发式方法确定项目复杂性：

小项目（< 1 周）

使用部分：1, 2, 3, 4, 5, 6, 7, 9

跳过：替代方案、迁移计划、批准

中型项目（1-4 周）

使用部分：1-11, 15, 18

提供：成功指标、术语表、替代方案、性能

大型项目（> 1 个月）

使用所有部分（1-20）

关键：所有强制部分 + 关键部分必须详细

交互式工作流

步骤 1：初始收集

使用 AskQuestion 工具收集基本信息：

{
  "title": "TDD 项目信息",
  "questions": [
    {
      "id": "project_name",
      "prompt": "功能/集成/项目的名称是什么？",
      "options": [] // 自由文本
    },
    {
      "id": "project_size",
      "prompt": "预期的项目规模是什么？",
      "options": [
        { "id": "small", "label": "小（< 1 周）" },
        { "id": "medium", "label": "中（1-4 周）" },
        { "id": "large", "label": "大（> 1 个月）" }
      ]
    },
    {
      "id": "project_type",
      "prompt": "这是什么类型的项目？",
      "allow_multiple": true,
      "options": [
        { "id": "integration", "label": "外部集成（API、服务）" },
        { "id": "feature", "label": "新功能" },
        { "id": "refactor", "label": "重构/迁移" },
        { "id": "infrastructure", "label": "基础设施/平台" },
        { "id": "payment", "label": "支付/计费系统" },
        { "id": "auth", "label": "认证/授权" },
        { "id": "data", "label": "数据迁移/处理" }
      ]
    },
    {
      "id": "has_context",
      "prompt": "您有清晰的问题陈述和背景吗？",
      "options": [
        { "id": "yes", "label": "是的，我现在可以提供" },
        { "id": "partial", "label": "部分，需要帮助澄清" },
        { "id": "no", "label": "没有，需要帮助定义它" }
      ]
    }
  ]
}

步骤 2：验证强制信息

基于答案，检查用户是否可以提供：

必须询问的强制字段：

技术负责人/所有者
团队成员
问题描述（什么/为什么/影响）
在范围内的内容
范围外的内容
高层级解决方案方法
至少 3 个风险
实施任务分解

使用 AskQuestion 或以用户语言自然对话询问：

英文示例：

我需要以下信息来创建 TDD：

1. **问题陈述**：
   - 我们正在解决什么问题？
   - 为什么现在重要？
   - 如果我们不解决会发生什么？

2. **范围**：
   - 这个项目中将会交付什么？
   - 什么不会被包括（范围外）？

3. **技术方法**：
   - 解决方案的高层描述
   - 涉及的主要组件
   - 集成点

您能提供这些信息吗？

葡萄牙语示例：

Preciso das seguintes informações para criar o TDD:

1. **Definição do Problema**:
   - Que problema estamos resolvendo?
   - Por que isso é importante agora?
   - O que acontece se não resolvermos?

2. **Escopo**:
   - O que SERÁ entregue neste projeto?
   - O que NÃO será incluído (fora do escopo)?

3. **Abordagem Técnica**:
   - Descrição de alto nível da solução
   - Principais componentes envolvidos
   - Pontos de integração

Você pode fornecer essas informações?

步骤 3：检查关键部分

基于 project_type，确定关键部分是否强制：

项目类型	所需的关键部分
`payment`, `auth`	安全考虑（强制性）
所有生产系统	监控与可观测性（强制性）
所有生产系统	回滚计划（强制性）
`integration`	依赖项、安全
所有	测试策略（强烈推荐）

如果关键部分缺失，以用户语言询问：

英文：

这是一个[支付/认证/生产]系统。这些部分是关键的：

❗ **安全考虑** - 对于合规性必需（PCI DSS, OWASP）
❗ **监控与可观测性** - 必需以检测生产中的问题
❗ **回滚计划** - 必需以在失败时恢复

您能提供：
1. 安全要求（认证、加密、PII 处理）？
2. 您将监控哪些指标？
3. 如果出现问题，您将如何回滚？

葡萄牙语：

Este é um sistema de [pagamento/autenticação/produção]. Estas seções são CRÍTICAS:

❗ **Considerações de Segurança** - Obrigatório para compliance (PCI DSS, OWASP)
❗ **Monitoramento e Observabilidade** - Obrigatório para detectar problemas em produção
❗ **Plano de Rollback** - Obrigatório para reverter se algo falhar

Você pode fornecer:
1. Requisitos de segurança (autenticação, encriptação, tratamento de PII)?
2. Quais métricas você vai monitorar?
3. Como você fará rollback se algo der errado?

步骤 4：提供建议部分

在强制部分覆盖后，以用户语言提供可选部分：

英文：

我还可以添加这些部分以使 TDD 更完整：

📊 **成功指标** - 您将如何衡量成功？
📚 **术语表** - 定义领域特定术语
⚖️ **考虑的替代方案** - 为什么选择此方法而非其他？
🔗 **依赖项** - 所需的外部服务/团队
⚡ **性能要求** - 延迟、吞吐量、可用性目标
📋 **未决问题** - 跟踪待决决策

您想我现在添加任何这些吗？（您可以稍后添加）

葡萄牙语：

Também posso adicionar estas seções para tornar o TDD mais completo:

📊 **Métricas de Sucesso** - Como você vai medir o sucesso?
📚 **Glossário** - Definir termos específicos do domínio
⚖️ **Alternativas Consideradas** - Por que esta abordagem ao invés de outras?
🔗 **Dependências** - Serviços/times externos necessários
⚡ **Requisitos de Performance** - Latência, throughput, disponibilidade
📋 **Questões em Aberto** - Rastrear decisões pendentes

Gostaria que eu adicionasse alguma dessas agora? (Você pode adicionar depois)

步骤 5：生成文档

以 Markdown 格式生成 TDD，遵循以下模板。

步骤 6：提供 Confluence 集成

如果用户有 Confluence Assistant 技能可用，以他们的语言询问：

英文：

您想我将这个 TDD 发布到 Confluence 吗？
- 我可以在您的空间中创建一个新页面
- 或更新现有页面

葡萄牙语：

Gostaria que eu publicasse este TDD no Confluence?
- Posso criar uma nova página no seu espaço
- Ou atualizar uma página existente

部分模板

1. 标题与元数据（强制性）

# TDD - [项目/功能名称]

| 字段             | 值                               |
| ---------------- | -------------------------------- |
| 技术负责人       | @名称                            |
| 产品经理         | @名称（如果适用）                |
| 团队             | 名称1, 名称2, 名称3              |
| Epic/工单        | [链接到 Jira/Linear]             |
| Figma/设计       | [链接如果适用]                   |
| 状态             | 草稿 / 审核中 / 已批准           |
| 创建日期         | YYYY-MM-DD                       |
| 最后更新日期     | YYYY-MM-DD                       |

如果用户未提供：询问技术负责人、团队成员和 Epic 链接。

2. 背景（强制性）

## 背景

[2-4 段项目描述]

**背景**：
当前状态是什么？这涉及到什么系统/功能？

**领域**：
这属于哪个业务领域？（例如，计费、认证、内容交付）

**利益相关者**：
谁关心这个项目？（用户、业务、合规等）

如果不清晰：询问“您能描述当前情况以及这涉及到哪个业务领域吗？”

3. 问题陈述与动机（强制性）

## 问题陈述与动机

### 我们正在解决的问题

- **问题 1**：[具体痛点及其影响]
  - 影响：[尽可能量化 - 时间浪费、成本、用户摩擦]
- **问题 2**：[另一个痛点]
  - 影响：[尽可能量化]

### 为什么现在？

- [业务驱动 - 市场扩张、竞争对手压力、监管要求]
- [技术驱动 - 技术债务、可扩展性限制]
- [用户驱动 - 客户反馈、使用模式]

### 不解决的后果

- **业务**：[收入损失、竞争劣势]
- **技术**：[技术债务积累、系统退化]
- **用户**：[体验差、流失风险]

如果用户说“为了集成 X”：询问“这个集成将解决哪些具体问题？为什么现在重要？如果我们不这样做会发生什么？”

4. 范围（强制性）

## 范围

### ✅ 在范围内（V1 - MVP）

明确列出将会交付的内容：

- 功能/能力 1
- 功能/能力 2
- 功能/能力 3
- 集成点 A
- 数据迁移 X

### ❌ 范围外（V1）

明确列出此阶段不包括的内容：

- 功能 X（推迟到 V2）
- 集成 Y（MVP 不需要）
- 高级分析（未来增强）
- 多区域支持（V2）

### 🔮 未来考虑（V2+）

未来可能添加的内容：

- 功能 A（依赖于用户需求）
- 功能 B（V1 验证后）

如果用户未定义：询问“V1 的必须内容是什么？什么可以等后续版本？”

5. 技术解决方案（强制性）

## 技术解决方案

### 架构概述

[解决方案的高层描述]

**关键组件**：

- 组件 A：[职责]
- 组件 B：[职责]
- 组件 C：[职责]

**架构图**：

[包括 Mermaid 图、PlantUML 或链接到图]

```mermaid
graph LR
    A[前端] -->|HTTP| B[API 网关]
    B -->|GraphQL| C[后端服务]
    C -->|REST| D[外部 API]
    C -->|写| E[(数据库)]
```

数据流

步骤 1：用户操作 → 前端
步骤 2：前端 → API 网关 (POST /resource)
步骤 3：API 网关 → 服务层
步骤 4：服务 → 外部 API（如果适用）
步骤 5：服务 → 数据库（持久化）
步骤 6：响应 → 前端

APIs 与端点

端点	方法	描述	请求	响应
`/api/v1/resource`	POST	创建资源	`CreateDto`	`ResourceDto`
`/api/v1/resource/:id`	GET	按 ID 获取	-	`ResourceDto`
`/api/v1/resource/:id`	DELETE	删除资源	-	`204 No Content`

示例请求/响应：

// POST /api/v1/resource
{
  "name": "示例",
  "type": "标准"
}

// 响应 201 Created
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "示例",
  "type": "标准",
  "status": "活跃",
  "createdAt": "2026-02-04T10:00:00Z"
}

数据库更改

新表：

{模块名称}{实体名称} - [描述]
- 主要字段：id, userId, name, status
- 时间戳：createdAt, updatedAt
- 索引：userId, status（用于查询性能）

模式更改（如果修改现有）：

添加列 newField 到 ExistingTable
- 类型：[varchar/integer/jsonb/etc.]
- 约束：[nullable/unique/外键]

迁移策略：

从模式更改生成迁移
首先在暂存环境测试迁移
在低流量窗口运行
准备回滚迁移

数据回填（如果需要）：

受影响记录：估计数量
处理时间：估计数据迁移持续时间
验证：如何在回填后验证数据完整性


**如果用户提供模糊描述**：询问“主要组件是什么？数据如何流经系统？将创建/修改哪些 APIs？”

---

### 6. 风险（强制性）

```markdown
## 风险

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| 外部 API 停机 | 高 | 中 | 实施断路器，缓存响应，降级模式回退 |
| 数据迁移失败 | 高 | 低 | 在暂存副本测试，首先运行试运行，准备回滚脚本 |
| 性能下降 | 中 | 中 | 部署前负载测试，实施缓存，监控延迟 |
| 安全漏洞 | 高 | 低 | 安全审查，渗透测试，遵循 OWASP 指南 |
| 范围蔓延 | 中 | 高 | 严格范围定义，变更请求过程，定期利益相关者对齐 |

**风险评分**：
- **影响**：高（系统停机、数据丢失）/ 中（UX 降级）/ 低（轻微不便）
- **概率**：高 (>50%) / 中 (20-50%) / 低 (<20%)

如果用户提供 < 3 个风险：询问“什么可能出错？考虑：外部依赖、数据完整性、性能、安全、范围变更。”

7. 实施计划（强制性）

## 实施计划

| 阶段                 | 任务              | 描述                            | 负责人   | 状态 | 估计 |
| --------------------- | ----------------- | ------------------------------- | -------- | ---- | ---- |
| **阶段 1 - 设置**     | 设置凭证          | 获取 API 密钥，配置环境        | @Dev1    | TODO | 1d   |
|                       | 数据库设置        | 创建模式，配置数据源            | @Dev1    | TODO | 1d   |
| **阶段 2 - 核心**     | 实体与仓库        | 创建 TypeORM 实体，仓库         | @Dev2    | TODO | 3d   |
|                       | 服务              | 实施业务逻辑服务                | @Dev2    | TODO | 4d   |
| **阶段 3 - APIs**     | REST 端点         | 创建控制器，DTOs                | @Dev3    | TODO | 3d   |
|                       | 集成              | 与外部 API 集成                 | @Dev1    | TODO | 3d   |
| **阶段 4 - 测试**     | 单元测试          | 测试服务和仓库                  | @团队    | TODO | 2d   |
|                       | E2E 测试          | 测试完整流程                    | @团队    | TODO | 3d   |
| **阶段 5 - 部署**     | 暂存部署          | 部署到暂存，冒烟测试            | @DevOps  | TODO | 1d   |
|                       | 生产部署          | 分阶段推广到生产                | @DevOps  | TODO | 1d   |

**总估计**：~20 天（4 周）

**依赖项**：

- 必须完成阶段 N 才能开始阶段 N+1
- 外部 API 访问需要在阶段 3 前
- 安全审查需要在阶段 5 前

如果用户提供模糊计划：询问“您能将其分解为具有具体任务的阶段吗？谁将负责每个部分？估计的时间线是什么？”

8. 安全考虑（对于支付/认证/PII 是关键）

## 安全考虑

### 认证与授权

- **认证**：用户如何证明身份
  - 示例：JWT 令牌，OAuth 2.0，基于会话的
- **授权**：认证用户可以访问什么
  - 示例：基于角色 (RBAC)，基于属性 (ABAC)
  - 确保用户只能访问自己的资源

### 数据保护

**加密**：

- **静态**：启用数据库加密 (AES-256)
- **传输中**：所有 API 通信使用 TLS 1.3
- **机密**：在环境变量/机密管理器中存储 API 密钥（AWS Secrets Manager, HashiCorp Vault）

**PII 处理**：

- 收集的 PII：[邮箱、姓名、支付信息]
- 法律依据：[同意、合同、合法利益]
- 保留：[数据保留多久]
- 删除：[GDPR 删除权的实施]

### 合规要求

| 法规       | 要求                               | 实施                                    |
| ---------- | ---------------------------------- | --------------------------------------- |
| **GDPR**   | 数据保护，删除权                   | 实施数据导出/删除端点                   |
| **PCI DSS** | 不存储卡数据                       | 使用 Stripe 令牌化，从不存储 CVV/完整 PAN |
| **LGPD**   | 巴西数据保护                       | 与 GDPR 合规相同                        |

### 安全最佳实践

- ✅ 所有端点的输入验证
- ✅ SQL 注入预防（参数化查询）
- ✅ XSS 预防（清理用户输入，CSP 标头）
- ✅ CSRF 保护（状态更改操作的令牌）
- ✅ 速率限制（例如，每个用户 10 请求/分钟，每个 IP 100 请求/分钟）
- ✅ 审计日志（记录所有敏感操作）

### 机密管理

**API 密钥**：

- 存储：环境变量或机密管理服务
- 轮换：定义轮换策略（例如，每 90 天）
- 访问：仅后端服务，从不暴露到前端
- 示例：Stripe 密钥、数据库凭证、API 令牌

**Webhook 签名**：

- 验证来自外部服务的 webhook 签名
- 拒绝没有有效签名标头的请求
- 记录无效签名尝试以进行安全监控

如果缺失且项目涉及支付/认证：询问“这是一个[支付/认证]系统。我需要安全细节：您将如何处理认证？将使用什么加密？收集什么 PII？任何合规要求（GDPR, PCI DSS）？”

9. 测试策略（关键）

## 测试策略

| 测试类型             | 范围                    | 覆盖率目标          | 方法             |
| --------------------- | ------------------------ | -------------------- | ---------------- |
| **单元测试**          | 服务、仓库              | > 80%                | Jest 与模拟      |
| **集成测试**          | API 端点 + 数据库        | 关键路径            | Supertest + 测试 DB |
| **E2E 测试**          | 完整用户流程            | 快乐路径 + 错误情况 | Playwright       |
| **合约测试**          | 外部 API 集成           | API 合约验证         | Pact 或手动模拟  |
| **负载测试**          | 负载下的性能            | 基线性能            | k6 或 Artillery  |

### 测试场景

**单元测试**：

- ✅ 服务业务逻辑（创建、更新、删除）
- ✅ 仓库查询方法
- ✅ 错误处理（抛出正确异常）
- ✅ 边缘情况（空输入、无效数据）

**集成测试**：

- ✅ POST `/api/v1/resource` → 在 DB 中创建
- ✅ GET `/api/v1/resource/:id` → 返回正确数据
- ✅ DELETE `/api/v1/resource/:id` → 从 DB 移除
- ✅ 无效输入 → 返回 400 Bad Request
- ✅ 未授权访问 → 返回 401/403

**E2E 测试**：

- ✅ 用户创建资源 → 成功流程
- ✅ 用户尝试访问其他用户的资源 → 拒绝
- ✅ 外部 API 失败 → 优雅降级
- ✅ 数据库连接丢失 → 正确处理错误

**负载测试**：

- 目标：100 请求/秒持续，500 请求/秒峰值
- 监控：延迟（p50, p95, p99）、错误率、吞吐量
- 通过标准：p95 < 500ms，错误率 < 1%

### 测试数据管理

- 使用工厂生成测试数据（例如，`@faker-js/faker`）
- 种子测试数据库以现实数据
- 每次测试后清理测试数据
- 使用单独的测试数据库（从不使用生产）

如果缺失：询问“您将如何测试这个？需要哪些测试类型（单元、集成、e2e）？关键的测试场景是什么？”

10. 监控与可观测性（对于生产是关键）

## 监控与可观测性

### 跟踪指标

| 指标                    | 类型       | 告警阈值       | 仪表板          |
| ----------------------- | ---------- | -------------- | --------------- |
| `api.latency`           | 延迟       | p95 > 1s 持续 5分钟 | DataDog / Grafana |
| `api.error_rate`        | 错误率     | > 1% 持续 5分钟 | DataDog / Grafana |
| `external_api.latency`  | 延迟       | p95 > 2s 持续 5分钟 | DataDog         |
| `external_api.errors`   | 计数器     | > 5 在 1分钟内 | PagerDuty       |
| `database.query_time`   | 持续时间   | p95 > 100ms    | DataDog         |
| `webhook.processing_time` | 持续时间   | > 5s           | 内部仪表板      |

### 结构化日志

**日志格式** (JSON)：

```json
{
  "level": "info",
  "timestamp": "2026-02-04T10:00:00Z",
  "message": "资源已创建",
  "context": {
    "userId": "user-123",
    "resourceId": "res-456",
    "action": "create",
    "duration_ms": 45
  }
}
```

记录什么：

✅ 所有 API 请求（方法、路径、状态、持续时间）
✅ 外部 API 调用（端点、状态、持续时间）
✅ 数据库查询（慢查询 > 100ms）
✅ 错误和异常（堆栈跟踪、上下文）
✅ 业务事件（资源创建、支付处理）

不记录什么：

❌ 密码、API 密钥、机密
❌ 完整卡号
❌ 敏感 PII（编辑或哈希）

告警

告警	严重程度	渠道	值班行动
错误率 > 5%	P1（严重）	PagerDuty	立即调查，如果需要则回滚
外部 API 停机	P1（严重）	PagerDuty	启用回退模式，通知利益相关者
延迟 > 2s (p95)	P2（高）	Slack #engineering	调查性能下降
Webhook 失败 > 20	P2（高）	Slack #engineering	检查 webhook 端点，Stripe 状态
数据库连接池耗尽	P1（严重）	PagerDuty	扩展连接或调查泄漏

仪表板

操作仪表板：

请求率（每个端点）
错误率（总体和每个端点）
延迟（p50, p95, p99）
外部 API 健康
数据库性能

业务仪表板：

创建的资源（每日计数）
活跃用户
转换指标（如果适用）


**如果生产系统缺失**：询问“您将如何在生产中监控这个？什么指标重要？您需要什么告警？”

---

### 11. 回滚计划（对于生产是关键）

```markdown
## 回滚计划

### 部署策略

- **功能标志**：`FEATURE_X_ENABLED`（LaunchDarkly / 自定义）
- **分阶段推广**：
  - 阶段 1：5% 流量（1 天）
  - 阶段 2：25% 流量（1 天）
  - 阶段 3：50% 流量（1 天）
  - 阶段 4：100% 流量

- **金丝雀部署**：首先部署到 1 个实例，监控 1 小时然后全面推广

### 回滚触发器

| 触发器 | 行动 |
|--------|------|
| 错误率 > 5% 持续 5 分钟 | **立即回滚** - 禁用功能标志 |
| 延迟 > 3s (p95) 持续 10 分钟 | **调查** - 如果没有快速修复则回滚 |
| 外部 API 集成失败 > 50% | **回滚** - 恢复到先前版本 |
| 数据库迁移失败 | **停止** - 不继续，调查 |
| 客户报告数据丢失 | **立即回滚** + 事件响应 |

### 回滚步骤

**1. 立即回滚 (< 5 分钟)**：
- **功能标志**：通过功能标志仪表板禁用（即时）
- **部署**：通过部署工具恢复到先前版本（2-3 分钟）

**2. 数据库回滚**（如果架构已更改）：
- 使用迁移工具运行向下迁移
- 验证架构完整性
- 确认数据一致性

**3. 沟通**：

- 通知 #engineering Slack 频道
- 更新状态页面（如果面向客户）
- 创建事件工单
- 在 24 小时内安排事后分析

### 回滚后

- **根本原因分析**：在 24 小时内
- **修复**：在开发环境中实施修复
- **重新测试**：完整测试套件 + 根本原因额外测试
- **重新部署**：遵循相同的分阶段推广策略

### 数据库回滚考虑

- **迁移**：始终创建可逆迁移（向下迁移）
- **数据回填**：如果数据被修改，有脚本恢复先前状态
- **备份**：运行迁移前进行数据库快照
- **测试**：在生产前在暂存环境测试回滚过程

如果生产缺失：询问“如果部署出错会发生什么？您将如何回滚？回滚的触发器是什么？”

12. 成功指标（建议）

## 成功指标

| 指标                  | 基线      | 目标  | 测量        |
| --------------------- | --------- | ----- | ----------- |
| API 延迟 (p95)        | N/A（新 API） | < 200ms | DataDog APM |
| 错误率                | N/A       | < 0.1% | Sentry / 日志 |
| 转换率                | N/A       | > 70% | 分析        |
| 用户满意度            | N/A       | NPS > 8 | 用户调查    |
| 完成操作时间          | N/A       | < 30s | 前端分析    |

**业务指标**：

- [指标] 增加 [X%]
- [成本/时间] 减少 [Y%]
- 用户采用：[Z%] 用户在 30 天内使用新功能

**技术指标**：

- 前 30 天零生产事件
- 测试覆盖率 > 80%
- 文档完整性：100% 公共 APIs 已文档化

13. 术语表与领域术语（建议）

## 术语表

| 术语                | 描述                                                           |
| ------------------- | -------------------------------------------------------------- |
| **客户**            | 具有活跃订阅或已进行购买的用户                                 |
| **订阅**            | 具有定义间隔的定期支付安排（每月、每年）                       |
| **试用**            | 用户免费测试服务，在需要支付前的期间                           |
| **Webhook**         | 来自外部服务的 HTTP 回调以通知事件                             |
| **幂等性**          | 操作可以多次应用并产生相同结果                                 |
| **断路器**          | 模式，当外部服务停机时防止级联失败                             |

**缩写**：

- **API**：应用程序编程接口
- **SLA**：服务级别协议
- **PII**：个人可识别信息
- **GDPR**：通用数据保护条例
- **PCI DSS**：支付卡行业数据安全标准

14. 考虑的替代方案（建议）

## 考虑的替代方案

| 选项                | 优点                                                     | 缺点                                                                        | 为何未选择                                    |
| ------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------- |
| **选项 A**（选择） | + 最佳文档<br>+ 全球支持<br>+ 成熟 SDK                   | - 成本：2.9% + $0.30<br>- 供应商锁定                                          | ✅ **选择** - 功能与成本的最佳平衡              |
| 选项 B              | + 较低费用 (2.5%)<br>+ 品牌认知                           | - 差的开发者体验<br>- 有限的国际支持                                        | 开发者体验差，难以维护                        |
| 选项 C              | + 完全控制<br>+ 无交易费用                              | - 高维护成本<br>- 合规负担 (PCI DSS)<br>- 安全风险                          | 维护风险太高且昂贵                          |
| 选项 D              | + 最便宜选项                                              | - 无支持<br>- 有限功能<br>- 未知可靠性                                      | 生产支付处理风险太高                        |

**决策标准**：

1. 开发者体验和文档质量（权重：40%）
2. 总拥有成本（权重：30%）
3. 国际支持和合规（权重：20%）
4. 可靠性和可用时间（权重：10%）

**为何选项 A 胜出**：

- 在开发者体验上得分最高（对于快速迭代关键）
- 初创公司的行业标准（更容易招聘有经验的开发者）
- 内置合规（PCI DSS, SCA, 3D Secure）减少风险

15. 依赖项（建议）

## 依赖项

| 依赖项            | 类型           | 所有者       | 状态           | 风险                |
| ----------------- | -------------- | ----------- | -------------- | ------------------- |
| Stripe API        | 外部           | Stripe Inc. | 生产就绪       | 低（99.99% 可用时间） |
| 身份模块          | 内部           | 团队 Auth   | 生产就绪       | 低                  |
| 数据库 (PostgreSQL) | 基础设施       | DevOps      | 就绪           | 低                  |
| Redis（缓存）     | 基础设施       | DevOps      | 需要设置       | 中                  |
| 功能标志服务      | 内部           | 平台        | 就绪           | 低                  |

**批准要求**：

- [ ] 安全团队审查（对于支付/认证项目）
- [ ] 合规签署（对于 PII/支付数据）
- [ ] 运维团队准备好监控设置
- [ ] 产品对范围签署

**阻塞项**：

- 等待 Stripe 生产密钥（ETA：2026-02-10）
- 需要暂存环境 Redis 设置（ETA：2026-02-08）

16. 性能要求（建议）

## 性能要求

| 指标              | 要求                   | 测量方法 |
| ----------------- | ---------------------- | -------- |
| API 延迟 (p50)    | < 100ms                | DataDog APM |
| API 延迟 (p95)    | < 500ms                | DataDog APM |
| API 延迟 (p99)    | < 1s                   | DataDog APM |
| 吞吐量            | 1000 请求/秒 持续      | 负载测试 (k6) |
| 可用性            | 99.9% (< 8.76h 停机/年) | 可用时间监控 |
| 数据库查询时间    | < 50ms (p95)           | 慢查询日志 |

**负载测试计划**：

- 基线：100 请求/秒 持续 10 分钟
- 峰值：500 请求/秒 持续 5 分钟
- 突发：1000 请求/秒 持续 1 分钟

**可扩展性**：

- 水平扩展：添加更多实例（Kubernetes 自动扩展）
- 数据库：如果需要则读取副本（10k 请求/秒后）
- 缓存：Redis 用于频繁访问数据（> 100 请求/秒每个资源）

17. 迁移计划（建议 - 如果适用）

## 迁移计划

### 迁移策略

**类型**：[蓝绿 / 滚动 / 大爆炸 / 分阶段]

**阶段**：

| 阶段             | 描述                            | 受影响用户 | 持续时间 | 回滚            |
| ---------------- | ------------------------------- | ---------- | -------- | --------------- |
| 1. 准备          | 设置新系统，并行运行            | 0%         | 1 周     | N/A             |
| 2. 影子模式      | 新系统处理但不服务              | 0%         | 1 周     | 即时            |
| 3. 试点          | 5% 用户在新系统                 | 5%         | 1 周     | < 5分钟         |
| 4. 逐步推广      | 50% 用户在新系统                | 50%        | 1 周     | < 5分钟         |
| 5. 完全迁移      | 100% 用户在新系统               | 100%       | 1 天     | < 5分钟         |
| 6. 退役          | 关闭旧系统                      | 0%         | 1 周     | 从备份恢复      |

### 数据迁移

**源**：旧系统数据库
**目的地**：新系统数据库
**量**：[X 百万记录]
**方法**：[ETL 脚本 / 数据库复制 / API 同步]

**步骤**：

1. 从旧系统导出数据（脚本：`scripts/export-old-data.ts`）
2. 转换数据为新模式（脚本：`scripts/transform-data.ts`）
3. 验证数据完整性（校验和、行计数）
4. 加载到新系统（脚本：`scripts/load-new-data.ts`）
5. 验证：运行并行读取，比较结果

**时间线**：

- 暂存环境试运行：2026-02-10
- 生产迁移窗口：2026-02-15 02:00-06:00 UTC（低流量）

### 向后兼容性

- 旧 API 端点将保持活跃 90 天
- 添加弃用警告到响应
- 更新客户端库并迁移指南

18. 未决问题（建议）

## 未决问题

| #   | 问题                                               | 上下文                                        | 所有者     | 状态           | 决策日期 |
| --- | -------------------------------------------------- | --------------------------------------------- | ---------- | -------------- | -------- |
| 1   | 如何处理没有支付方法的试用到期？                   | 用户立即失去访问权限还是宽限期？              | @产品      | 🟡 讨论中       | TBD      |
| 2   | 允许同一邮箱多个试用？                             | 防止滥用与合法用例                            | @技术负责人 | 🔴 开放        | TBD      |
| 3   | Webhook 处理的 SLA？                               | Stripe 重试 72h，我们的目标是什么？           | @后端      | 🔴 开放        | TBD      |
| 4   | 在 V1 中支持优惠券？                               | 市场请求，是否在范围内？                      | @产品      | ✅ 已解决：V2  | 2026-02-01 |
| 5   | 如果身份模块失败的回退？                           | 我们可以在没有用户数据的情况下创建订阅吗？    | @技术负责人 | 🔴 开放        | TBD      |

**状态图例**：

- 🔴 开放 - 需要决策
- 🟡 讨论中 - 正在积极讨论
- ✅ 已解决 - 决策已做出

19. 路线图/时间线（建议）

## 路线图/时间线

| 阶段                    | 可交付成果                                                                      | 持续时间 | 目标日期 | 状态         |
| ----------------------- | ------------------------------------------------------------------------------- | -------- | -------- | ------------ |
| **阶段 0: 设置**        | - Stripe 凭证<br>- 暂存环境<br>- SDK 安装                                        | 2 天     | 2026-02-05 | ✅ 完成      |
| **阶段 1: 持久化**      | - 实体创建<br>- 仓库实施<br>- 迁移生成                                            | 3 天     | 2026-02-08 | 🟡 进行中    |
| **阶段 2: 服务**        | - CustomerService<br>- SubscriptionService<br>- 身份集成                          | 5 天     | 2026-02-15 | ⏳ 待定      |
| **阶段 3: APIs**        | - POST /subscriptions<br>- DELETE /subscriptions/:id<br>- GET /subscriptions      | 3 天     | 2026-02-18 | ⏳ 待定      |
| **阶段 4: Webhooks**    | - Webhook 端点<br>- 签名验证<br>- 事件处理程序                                    | 4 天     | 2026-02-22 | ⏳ 待定      |
| **阶段 5: 测试**        | - 单元测试 (80% 覆盖率)<br>- 集成测试<br>- E2E 测试                               | 5 天     | 2026-02-27 | ⏳ 待定      |
| **阶段 6: 部署**        | - 文档<br>- 监控设置<br>- 暂存部署<br>- 生产推广                                  | 3 天     | 2026-03-02 | ⏳ 待定      |

**总持续时间**：~25 天（5 周）

**里程碑**：

- 🎯 M1：MVP 准备暂存 (2026-02-22)
- 🎯 M2：生产部署 (2026-03-02)
- 🎯 M3：100% 推广完成 (2026-03-09)

**关键路径**：
阶段 0 → 阶段 1 → 阶段 2 → 阶段 3 → 阶段 4 → 阶段 5 → 阶段 6

20. 批准与签署（建议）

## 批准与签署

| 角色                     | 名称  | 状态         | 日期       | 评论                          |
| ------------------------ | ----- | ------------ | ---------- | ----------------------------- |
| 技术负责人                | @名称 | ✅ 已批准    | 2026-02-04 | LGTM，继续实施                |
| 首席工程师                | @名称 | ⏳ 待定      | -          | 首先要求安全审查              |
| 产品经理                  | @名称 | ✅ 已批准    | 2026-02-03 | 范围与路线图一致              |
| 工程经理                  | @名称 | ⏳ 待定      | -          | -                             |
| 安全团队                  | @名称 | 🔴 未开始    | -          | 支付集成必需                  |
| 合规/法律                 | @名称 | N/A          | -          | 此项目不需要                  |

**批准标准**：

- ✅ 所有强制部分完成
- ✅ 安全审查通过（如果适用）
- ✅ 风险已识别和缓解
- ✅ 时间线现实且已同意
- ⏳ 测试策略已获 QA 批准
- ⏳ 监控计划已获 SRE 审查

**批准后下一步**：

1. 在 Jira 创建 Epic（在元数据中链接）
2. 分解为用户故事
3. 开始阶段 1 实施
4. 与团队安排启动会议

验证规则

强制部分清单

在最终确定 TDD 前，确保：

[ ] 标题：技术负责人、团队、Epic 链接存在
[ ] 背景：2+ 段描述背景和领域
[ ] 问题：至少 2 个具体问题，有影响
[ ] 范围：清晰的范围内和范围外项（每项至少 3 个）
[ ] 技术解决方案：架构图或描述
[ ] 技术解决方案：至少 1 个 API 端点定义
[ ] 风险：至少 3 个风险，有影响/概率/缓解
[ ] 实施计划：分解为阶段并估计

关键部分清单（按项目类型）

如果支付/认证项目：

[ ] 安全：认证方法定义
[ ] 安全：加密（静态、传输中）指定
[ ] 安全：PII 处理方法文档化
[ ] 安全：合规要求已识别

如果生产系统：

[ ] 监控：至少 3 个指标定义，有阈值
[ ] 监控：告警已配置
[ ] 回滚：回滚触发器定义
[ ] 回滚：回滚步骤文档化

所有项目：

[ ] 测试：至少 2 种测试类型定义（单元、集成、e2e）
[ ] 测试：关键测试场景列出

输出格式

当创建 TDD 时

生成 Markdown 文档
根据上述清单验证
突出任何缺失的关键部分
向用户提供摘要：

✅ TDD 已创建："[项目名称]"

**包含的部分**：
✅ 强制 (7/7)：全部存在
✅ 关键 (3/4)：安全、测试、监控
⚠️ 缺失：回滚计划（建议用于生产）

**建议的后续步骤**：
- 添加回滚计划部分（对于生产关键）
- 与信息安全团队审查安全部分
- 在 Jira 创建 Epic 并在元数据中链接
- 与利益相关者安排 TDD 审查会议

您想我：
1. 添加缺失的回滚计划部分吗？
2. 将此 TDD 发布到 Confluence 吗？
3. 为此项目创建 Jira Epic 吗？

Confluence 集成

如果用户想发布到 Confluence：

我将把这个 TDD 发布到 Confluence。

应该使用哪个空间？
- 个人空间 (~557058...)
- 团队空间（提供空间键）

应该：
- 创建新页面
- 更新现有页面（提供页面 ID 或 URL）

然后使用 Confluence Assistant 技能发布。

常见反模式避免

❌ 模糊的问题陈述

错误：


我们需要与 Stripe 集成。

良好：


### 我们正在解决的问题

- **手动支付处理每天花费 2 小时**：当前手动处理支付，每月成本 $500 人工
- **无法扩展国际**：当前支付处理器仅支持 USD
- **高购物车放弃率 (45%)**：差的结账 UX 导致每月收入损失 $10k

❌ 未定义范围

错误：


构建具有所有功能的支付集成。

良好：


### ✅ 在范围内（V1）

- 试用订阅（14 天）
- 每个用户单一支付方法
- 仅 USD
- 取消订阅

### ❌ 范围外（V1）

- 多种支付方法
- 多币种
- 优惠券
- 基于使用量的计费

❌ 支付系统缺少安全

错误：


支付集成无安全部分。

良好：


### 安全考虑（强制性）

**PCI DSS 合规**：

- 从不存储完整卡号（使用 Stripe 令牌）
- 从不记录 CVV 或完整 PAN
- 使用 Stripe Elements 进行卡输入（PCI SAQ A）

**机密管理**：

- 在环境变量中存储 `STRIPE_SECRET_KEY`
- 每 90 天轮换密钥
- 从不提交密钥到 git

❌ 无回滚计划

错误：


我们将部署并希望其工作。

良好：


### 回滚计划

**触发器**：

- 错误率 > 5% → 立即回滚
- 支付处理失败 > 10% → 立即回滚

**步骤**：

1. 禁用功能标志 `STRIPE_INTEGRATION_ENABLED`
2. 验证旧支付处理器活跃
3. 通知 #engineering 和 #product
4. 在 24 小时内安排事后分析

重要笔记

尊重用户语言 - 自动检测并以用户请求的相同语言生成 TDD
专注于架构，而非实施 - 记录决策和合约，而非代码
仅高层级示例 - 显示 API 合约、数据模式、图表（而非 CLI 命令或代码片段）
始终验证强制部分 - 不让用户跳过它们
对于支付/认证 - 安全部分是强制性的
对于生产 - 监控和回滚是强制性的
询问澄清问题 - 不猜测缺失信息（以用户语言询问）
彻底但实用 - 小项目不需要所有 20 部分
更新文档 - TDDs 应随项目进展而演进
使用行业标准 - 参考 Google、Amazon、RFC 模式
考虑合规 - GDPR、PCI DSS、HIPAA 适用时
测试长寿性 - 如果实施框架更改，TDD 应仍有效

触发此技能的示例提示

英文

“为 Stripe 集成创建 TDD”
“我需要新认证系统的技术设计文档”
“编写 API 重设计的设计文档”
“帮助我记录支付集成架构”
“创建微服务迁移的技术规格”

葡萄牙语

“为 Stripe 集成创建 TDD”
“我需要新认证系统的技术设计文档”
“编写 API 重设计的设计文档”
“帮助我记录支付集成架构”
“创建微服务迁移的技术规格”

西班牙语

“为 Stripe 集成创建 TDD”
“我需要新认证系统的技术设计文档”
“编写 API 重设计的设计文档”
“帮助我记录支付集成架构”
“创建微服务迁移的技术规格”