ethan-skill 1.6.0 → 1.8.0

package/rules/windsurf/.windsurf/rules/smart-flow.md

@@ -1,12 +1,12 @@
 ---
-description: Ethan AI Workflow Assistant — 10 standardized workflow skills
+description: Ethan AI Workflow Assistant — 24 standardized workflow skills
 globs: ["**/*"]
 alwaysApply: true
 ---
 
-# Ethan - Windsurf Rules (v1.6.0)
+# Ethan - Windsurf Rules (v1.8.0)
 
-> Auto-generated from src/skills/ | 2026-03-26T15:25:56.504Z
+> Auto-generated from src/skills/ | 2026-03-31T16:55:43.257Z
 > Do not edit manually.
 
 ## IMPORTANT: Skill Activation Rules
@@ -738,3 +738,2936 @@ You are equipped with the **Ethan AI Workflow Assistant**. Follow these rules st
 - 评估维度权重要在调研开始前确定，避免"为结论找理由"的逆向推导
 - POC 代码要保留在仓库中，方便团队评审
 - 选型结论要包含"不选其他方案的原因"，方便后续追溯决策依据
+
+### 11. 接口设计 (api_design)
+
+**Triggers**: `接口设计`, `API 设计`, `api design`, `设计接口`, `接口规范`, `RESTful 设计`, `GraphQL 设计`, `设计 REST API`, `设计 API`, `@ethan api`, `@ethan 接口`, `/接口设计`
+
+**Goal**: 基于业务需求设计清晰、可演进的 RESTful / GraphQL 接口规范，输出接口文档
+
+**Steps**:
+
+1. **明确业务边界与资源模型**:
+   - 梳理本次需要暴露的**核心业务实体**（资源）
+   - 确定资源间的关联关系：一对一 / 一对多 / 多对多
+   - 识别操作类型：CRUD、操作型动作（如 /activate、/cancel）
+   - 确认调用方（Web / App / 第三方 / 内部服务）
+   - 确认认证方式：JWT / OAuth2 / API Key / Session
+
+2. **设计 URL 路径与 HTTP 方法**:
+   遵循 REST 语义设计路径：
+   
+   **命名规范**
+   - 使用复数名词表示集合：`/users`、`/orders`
+   - 资源嵌套不超过 2 层：`/users/{id}/orders`
+   - 动作使用子资源表达：`POST /orders/{id}/cancel`
+   - 使用小写 kebab-case：`/user-profiles`
+   
+   **HTTP 方法映射**
+   | 方法 | 场景 | 幂等性 |
+   |------|------|--------|
+   | GET | 查询（单个/列表） | ✅ |
+   | POST | 创建 / 触发动作 | ❌ |
+   | PUT | 全量更新 | ✅ |
+   | PATCH | 局部更新 | ✅ |
+   | DELETE | 删除 | ✅ |
+   
+   **版本控制**
+   - URL 版本：`/api/v1/users`（推荐，可见性高）
+   - Header 版本：`Accept: application/vnd.api+json;version=1`
+
+3. **设计请求与响应体**:
+   **请求体规范**
+   - Content-Type 统一 `application/json`
+   - 字段使用 camelCase（Web 侧）或 snake_case（按团队规范统一）
+   - 必填字段明确标注，给出示例值
+   - 枚举值给出完整列表和含义
+   
+   **统一响应体格式**
+   ```json
+   {
+     "code": 0,           // 0=成功，非0=错误码
+     "message": "ok",     // 描述信息
+     "data": { ... },     // 业务数据（成功时）
+     "requestId": "uuid"  // 链路追踪 ID
+   }
+   ```
+   
+   **分页响应**
+   ```json
+   {
+     "code": 0,
+     "data": {
+       "list": [...],
+       "total": 100,
+       "page": 1,
+       "pageSize": 20
+     }
+   }
+   ```
+   
+   **HTTP 状态码使用**
+   - 200 OK / 201 Created / 204 No Content
+   - 400 Bad Request（参数错误）/ 401 Unauthorized / 403 Forbidden
+   - 404 Not Found / 409 Conflict / 422 Unprocessable Entity
+   - 500 Internal Server Error（不暴露内部细节）
+
+4. **设计错误码体系**:
+   建立业务错误码规范，避免所有错误都返回 500：
+   
+   **错误码设计**
+   ```
+   模块前缀 + 序号：
+   1001xx — 用户模块
+   1002xx — 订单模块
+   1003xx — 支付模块
+   ```
+   
+   **示例**
+   ```json
+   {
+     "code": 100101,
+     "message": "用户不存在",
+     "data": null,
+     "requestId": "abc-123"
+   }
+   ```
+   
+   - 错误信息面向**开发者**（不直接展示给终端用户）
+   - 敏感错误（如数据库异常）统一返回 `"系统繁忙，请稍后重试"`
+   - 提供错误码文档（维护在 API 文档中）
+
+5. **安全与性能设计**:
+   **安全**
+   - 所有修改类操作（POST/PUT/PATCH/DELETE）必须鉴权
+   - 列表接口加入数据权限隔离（用户只能看自己的数据）
+   - 文件上传接口限制文件类型和大小
+   - 敏感字段（手机号、身份证）在响应中脱敏：`138****8888`
+   - 接口加入速率限制（Rate Limiting）
+   
+   **性能**
+   - 列表接口支持分页（禁止无限制全量返回）
+   - 大数据量接口提供游标分页（cursor-based）
+   - 支持字段过滤：`?fields=id,name,email`
+   - 耗时操作改为异步：POST 立即返回 `taskId`，GET 轮询状态
+
+6. **输出接口规范文档**:
+   按以下格式输出每个接口的文档：
+   
+   ```markdown
+   ## POST /api/v1/users — 创建用户
+   
+   **描述**：注册新用户账号
+   
+   **认证**：不需要
+   
+   **请求体**
+   | 字段 | 类型 | 必填 | 描述 |
+   |------|------|------|------|
+   | username | string | ✅ | 用户名，3-20字符，字母数字下划线 |
+   | email | string | ✅ | 邮箱地址 |
+   | password | string | ✅ | 密码，最少8位 |
+   
+   **响应示例（201 Created）**
+   ```json
+   {
+     "code": 0,
+     "message": "ok",
+     "data": {
+       "id": "usr_abc123",
+       "username": "john_doe",
+       "email": "john@example.com",
+       "createdAt": "2024-01-01T00:00:00Z"
+     }
+   }
+   ```
+   
+   **错误码**
+   | code | message | 场景 |
+   |------|---------|------|
+   | 100101 | 邮箱已被注册 | 邮箱重复 |
+   | 100102 | 用户名不合法 | 格式校验失败 |
+   ```
+
+**Output**: Markdown 接口规范文档，含路径设计、请求/响应体、错误码表、安全说明，风格参考 OpenAPI 3.0
+**Notes**: 
+- URL 路径不使用动词，操作语义由 HTTP 方法表达
+- GraphQL 场景用 Schema First 原则，先定义类型再实现 resolver
+- 接口变更优先保持向后兼容，破坏性变更必须升版本号
+- 内部服务间调用（RPC/gRPC）可不遵循 REST 规范
+
+### 12. 安全审查 (security_review)
+
+**Triggers**: `安全审查`, `安全扫描`, `安全检查`, `漏洞扫描`, `security review`, `security audit`, `OWASP`, `安全风险`, `代码安全`, `@ethan 安全`, `@ethan security`, `/安全审查`
+
+**Goal**: 基于 OWASP Top 10 对代码和依赖进行安全扫描，识别漏洞并给出修复建议
+
+**Steps**:
+
+1. **确定审查范围**:
+   - 明确审查对象：代码变更 / 整个模块 / 依赖包 / 部署配置
+   - 确认技术栈（Node.js / Java / Python / 前端框架等）
+   - 了解数据敏感程度：是否涉及 PII（用户个人信息）、金融数据
+   - 确认暴露面：公网 API / 内部服务 / 用户上传入口
+   - 收集现有安全策略（如 CSP、CORS 配置）
+
+2. **OWASP Top 10 逐项检查**:
+   按 OWASP 2021 Top 10 逐项扫描：
+   
+   **A01 失效的访问控制**
+   - 垂直越权：普通用户能否访问管理员接口？
+   - 水平越权：用户A能否读取用户B的数据？
+   - IDOR（不安全的直接对象引用）：接口参数是否直接暴露内部 ID？
+   - 前端隐藏菜单 ≠ 权限控制，后端必须强制校验
+   
+   **A02 加密失效**
+   - 密码是否使用 bcrypt/argon2（禁止 MD5/SHA1）
+   - 传输层是否强制 HTTPS
+   - 敏感字段（身份证、银行卡）是否静态加密存储
+   - Cookie 是否设置 Secure + HttpOnly + SameSite
+   
+   **A03 注入**
+   - SQL 注入：是否使用 ORM 参数化查询（禁止字符串拼接）
+   - XSS：用户输入是否经过 HTML 转义后再输出
+   - Command 注入：是否调用 shell 命令且参数含用户输入
+   - LDAP/XML/NOSQL 注入场景检查
+   
+   **A04 不安全设计**
+   - 是否存在无限重试（暴力破解风险）
+   - 重要操作缺少二次确认（如删除账号、大额转账）
+   - 密码重置流程是否可被枚举
+   
+   **A05 安全配置错误**
+   - 生产环境是否关闭 Debug 模式、详细错误堆栈
+   - 是否暴露 `.env`、`.git`、`node_modules` 等目录
+   - 默认账号/密码是否修改
+   - CORS 是否配置为 `*`（应按域名白名单）
+   
+   **A06 自带缺陷和过时的组件**
+   - 运行 `npm audit` / `pip-audit` / `mvn dependency-check`
+   - 检查高危 CVE（CVSS ≥ 7.0）
+   - 框架和运行时是否在安全维护期内
+   
+   **A07 身份识别和认证失败**
+   - JWT 是否验证签名和过期时间
+   - Session 是否在登出时服务端失效
+   - 多因素认证（MFA）是否支持
+   
+   **A08 软件和数据完整性失败**
+   - 第三方 CDN 资源是否加 SRI（Subresource Integrity）
+   - CI/CD 管道是否允许未授权修改部署配置
+   - 序列化数据是否来自可信来源
+   
+   **A09 安全日志和监控失败**
+   - 登录成功/失败是否记录 IP 和时间戳
+   - 高危操作（删除、权限变更）是否有审计日志
+   - 日志中是否意外记录了密码或 Token
+   
+   **A10 服务端请求伪造（SSRF）**
+   - 接受 URL 参数的接口是否限制可访问的域名/IP
+   - 是否阻断对内网地址（10.x/172.x/192.168.x/127.x）的请求
+
+3. **密钥与凭据扫描**:
+   - 扫描代码中是否硬编码了：API Key、数据库密码、JWT Secret、云账号 AK/SK
+   - 检查 `.env` 文件是否被提交到 Git（查 `.gitignore`）
+   - 历史 commit 是否包含敏感信息（可用 `git log -S "password"` 搜索）
+   - 推荐工具：
+     - `gitleaks` — 扫描 git 历史中的密钥
+     - `trufflehog` — 高熵字符串检测
+     - GitHub Secret Scanning（如在 GitHub 托管）
+
+4. **依赖漏洞扫描**:
+   根据技术栈运行对应命令：
+   
+   ```bash
+   # Node.js
+   npm audit --audit-level=high
+   npx audit-ci --high
+   
+   # Python
+   pip install pip-audit && pip-audit
+   
+   # Java/Maven
+   mvn dependency-check:check
+   
+   # Docker 镜像
+   trivy image your-image:tag
+   ```
+   
+   重点关注：
+   - CVSS Score ≥ 7.0 的高危/严重漏洞
+   - 直接依赖优先修复（间接依赖通过升级父包解决）
+   - 有修复版本的立即升级，无修复的评估缓解措施
+
+5. **按风险级别输出报告**:
+   ```markdown
+   ## 安全审查报告
+   
+   **审查范围**：[模块/文件/PR]
+   **审查日期**：[日期]
+   **整体风险等级**：🔴 Critical / 🟠 High / 🟡 Medium / 🟢 Low
+   
+   ---
+   
+   ### 🔴 Critical（立即修复，阻止上线）
+   
+   - [ ] `auth.ts:45` SQL 注入漏洞：用户 ID 直接拼接查询字符串
+     **修复**：使用 ORM 参数化查询 `db.query('SELECT * FROM users WHERE id = ?', [id])`
+     **CVE**：— **CVSS**：9.8
+   
+   ### 🟠 High（本次迭代修复）
+   
+   - [ ] `upload.ts:23` 文件上传未限制类型，可上传 .php 执行文件
+     **修复**：白名单校验扩展名，并检查 MIME type
+   
+   ### 🟡 Medium（计划修复）
+   
+   - [ ] 缺少登录频率限制（Rate Limiting），存在暴力破解风险
+     **修复**：引入 express-rate-limit，5次失败后锁定15分钟
+   
+   ### 🟢 Low（建议改进）
+   
+   - [ ] Session Cookie 缺少 SameSite=Strict 属性
+   
+   ### ✅ 已做好的安全措施
+   - [值得肯定的安全实践]
+   
+   ### 统计
+   Critical: X | High: Y | Medium: Z | Low: W
+   ```
+
+**Output**: Markdown 安全审查报告，含 OWASP 维度检查结果、风险级别（Critical/High/Medium/Low）、修复建议和优先级
+**Notes**: 
+- Critical 问题必须在上线前修复，不接受任何例外
+- 前端安全校验只是 UX 辅助，所有安全逻辑必须在后端实现
+- 依赖漏洞扫描建议加入 CI 流程自动运行（每次 PR 触发）
+- 安全审查不能替代专业渗透测试，重大系统上线前建议委托专业团队
+
+### 13. 部署上线 (deployment)
+
+**Triggers**: `部署上线`, `上线`, `发布`, `deploy`, `发版`, `部署`, `上线流程`, `发布流程`, `怎么上线`, `准备上线`, `@ethan 上线`, `@ethan deploy`, `/部署上线`
+
+**Goal**: 系统化执行部署上线流程，覆盖预检、发布、验证和回滚，保障变更安全落地
+
+**Steps**:
+
+1. **上线前预检（Pre-flight）**:
+   在发布代码前完成以下检查，任何一项 ❌ 不得上线：
+   
+   **代码质量**
+   - [ ] 所有 CI 检查通过（单测、集成测试、Lint）
+   - [ ] Code Review 已完成，无 Blocker 问题
+   - [ ] 安全扫描无 Critical/High 级别漏洞（`npm audit`）
+   - [ ] 变更已在 Staging/预生产环境验证通过
+   
+   **配置核查**
+   - [ ] 生产环境配置（数据库、Redis、MQ 地址）已更新
+   - [ ] 环境变量已在目标环境注入（不含硬编码的密钥）
+   - [ ] Feature Flag 配置正确（灰度开关状态）
+   
+   **数据库变更**
+   - [ ] 数据库迁移脚本已备份原表结构
+   - [ ] 迁移脚本已在 Staging 执行并验证
+   - [ ] 大表 DDL 变更（加字段/加索引）在低峰期执行，评估锁表时间
+   
+   **依赖与基础设施**
+   - [ ] 第三方服务（支付/短信/CDN）已确认可用
+   - [ ] 新增的 Redis Key / MQ Topic 已提前创建
+   - [ ] 容器镜像已构建并推送到镜像仓库
+   
+   **通知**
+   - [ ] 上线时间已知会相关团队（QA / 前端 / 产品 / 运维）
+   - [ ] 回滚预案已准备（上个版本的镜像 Tag 或 SQL 回滚脚本）
+
+2. **选择发布策略**:
+   根据变更风险等级选择合适的发布策略：
+   
+   **🟢 滚动发布（Rolling Update）**
+   - 场景：低风险常规迭代
+   - 方式：逐个 Pod/实例替换，始终保持一定数量可用
+   - Kubernetes：`kubectl set image deployment/app app=image:v2`
+   - 优点：无停机；缺点：同时存在新旧版本（需兼容）
+   
+   **🟡 蓝绿部署（Blue/Green）**
+   - 场景：中风险版本，需要快速回滚能力
+   - 方式：并行运行两套环境，切换负载均衡流量
+   - 优点：回滚只需切流量（秒级）；缺点：资源成本翻倍
+   
+   **🟠 灰度发布（Canary Release）**
+   - 场景：高风险变更，需验证真实流量
+   - 方式：先放 5%-10% 流量到新版本，观察监控后逐步扩量
+   - 关键指标：错误率、P99 延迟、业务转化率
+   - Nginx 示例：`split_clients "${remote_addr}" $upstream { 10% backend_v2; * backend_v1; }`
+   
+   **🔴 停机发布（Maintenance Window）**
+   - 场景：强破坏性变更（如数据库大规模迁移）
+   - 提前在状态页通知用户，维护窗口选在凌晨低峰期
+
+3. **执行发布**:
+   **自动化流水线（推荐）**
+   ```bash
+   # GitOps 方式：更新镜像 Tag 触发 CD
+   git tag v1.2.3 && git push origin v1.2.3
+   
+   # 手动触发 GitHub Actions
+   gh workflow run deploy.yml --field environment=production --field version=v1.2.3
+   ```
+   
+   **发布过程监控要点**
+   - 实时观察 Pod 滚动状态：`kubectl rollout status deployment/app`
+   - 监控健康检查端点（Liveness/Readiness Probe）
+   - 观察 APM 工具（Datadog/SkyWalking）中错误率和延迟变化
+   - 若部署过程中出现 CrashLoopBackOff，立即暂停并触发回滚
+   
+   **数据库迁移执行顺序**
+   1. 先执行 向后兼容的迁移（如加字段，设默认值）
+   2. 发布新代码
+   3. 确认新代码运行稳定后，再执行清理旧逻辑的迁移
+   （Expand-Contract 模式，避免新旧代码不兼容）
+
+4. **上线后验证**:
+   发布完成后，在 **15 分钟内**完成以下验证：
+   
+   **基础健康检查**
+   - [ ] 所有实例健康检查端点 `/health` 返回 200
+   - [ ] Pod/实例数量与预期一致（未发生缩减）
+   - [ ] 无 OOMKilled 或高 CPU 异常
+   
+   **监控告警**
+   - [ ] 错误率（5xx）在基线水平（< 0.1%）
+   - [ ] P99 响应时间未劣化（对比上线前）
+   - [ ] 关键业务指标（下单量、登录量）趋势正常
+   
+   **核心链路冒烟测试**
+   - [ ] 用最高风险的 1-3 个核心功能人工验证
+     - 示例：登录 → 查看商品 → 加购 → 提交订单
+   - [ ] 检查日志无新增 ERROR 级别错误
+   
+   **灰度扩量（Canary 场景）**
+   ```
+   5% → 稳定 10min → 20% → 稳定 10min → 50% → 100%
+   ```
+
+5. **回滚方案**:
+   **触发回滚的条件（满足任一立即回滚）**
+   - 错误率超过基线 3 倍以上
+   - P99 延迟超过告警阈值 2 倍
+   - 核心业务指标断崖式下跌
+   - 出现 Critical 级别报错
+   
+   **回滚操作**
+   ```bash
+   # Kubernetes 快速回滚
+   kubectl rollout undo deployment/app
+   kubectl rollout undo deployment/app --to-revision=3  # 回滚到指定版本
+   
+   # Docker Compose 回滚
+   docker-compose up -d --no-deps --scale app=2  # 拉起旧版本
+   ```
+   
+   **数据库回滚**
+   - 向后兼容的迁移（加字段）通常不需要回滚
+   - 破坏性迁移回滚需执行预先准备的 SQL 脚本
+   - 数据删除操作必须在回滚脚本中用 INSERT 恢复（从备份）
+   
+   **上线后记录**
+   - 记录上线时间、版本号、发布人
+   - 若出现问题，触发故障排查（`ethan debug`）和事后复盘（`ethan oncall`）
+
+**Output**: Markdown 上线 Checklist + 执行记录，含预检清单、发布策略建议、验证结果和回滚记录
+**Notes**: 
+- 生产环境首次部署必须有专人在线值守，完成后才能离开
+- 数据库变更是最高风险项，大表 DDL 操作务必在低峰期执行
+- 回滚方案必须提前验证可用，不能到了出问题才发现回滚脚本有 bug
+- 蓝绿和灰度部署需要基础设施支持，提前确认 K8s/Nginx 配置
+
+### 14. PRD 编写 (prd)
+
+**Triggers**: `PRD`, `产品需求`, `写 PRD`, `需求文档`, `prd 编写`, `产品文档`, `写需求`, `功能需求`, `生成 PRD`, `@ethan PRD`, `@ethan 需求文档`, `/prd`, `/PRD`
+
+**Goal**: 从用户故事和业务目标出发，结构化生成产品需求文档（PRD），支撑研发高效落地
+
+**Steps**:
+
+1. **背景与目标**:
+   明确以下关键信息（询问或推导）：
+   
+   **业务背景**
+   - 这个功能/产品要解决什么业务问题？
+   - 当前用户的痛点是什么？（现有方案的不足）
+   - 有哪些量化的数据支撑这个问题的存在？
+   
+   **目标用户**
+   - 主要用户角色：[角色名称 + 典型特征描述]
+   - 次要用户角色：[如有]
+   - 用户当前的操作路径是什么（Before）？
+   
+   **成功指标（OKR/KPI）**
+   - 核心业务指标：如 "注册转化率提升 15%"、"客服工单减少 30%"
+   - 次要指标：NPS、页面停留时长等
+   - 不追求的指标（避免过度设计）：明确 out-of-scope
+   
+   **优先级与时间**
+   - P0（必须有，MVP 核心）/ P1（重要但非必须）/ P2（锦上添花）
+   - 目标上线日期：[日期]
+   - 里程碑节点：[设计完成 / 研发完成 / 灰度 / 全量]
+
+2. **用户故事与功能范围**:
+   用标准用户故事格式描述每个功能点：
+   
+   **用户故事格式**
+   > 作为 [用户角色]，
+   > 我需要 [完成某事]，
+   > 以便 [获得某种价值]。
+   
+   **示例**
+   > 作为新注册用户，我需要通过邮箱验证激活账号，以便确保账号安全并接收通知邮件。
+   
+   **功能列表模板**
+   
+   | # | 功能模块 | 用户故事 | 优先级 | 研发工作量估算 |
+   |---|---------|---------|--------|----------------|
+   | 1 | 注册激活 | 新用户通过邮件激活账号 | P0 | M（3-5天）|
+   | 2 | 邮件模板 | 支持品牌化邮件样式 | P1 | S（1-2天）|
+   | 3 | 批量导入 | 管理员批量导入用户 | P2 | L（5-8天）|
+   
+   **明确 Out-of-Scope（本期不做的）**
+   - [功能 A]：原因 / 延后到 v2
+   - [功能 B]：超出本期范围
+
+3. **详细功能描述与验收标准**:
+   为每个 P0/P1 功能编写详细说明和可测试的验收标准：
+   
+   **功能详细描述模板**
+   
+   ---
+   
+   #### 功能：[功能名称]
+   
+   **触发场景**：[用户在什么情况下使用此功能]
+   
+   **操作流程**（主流程 Happy Path）
+   1. 用户进入 [入口页面]
+   2. 操作 [步骤]
+   3. 系统 [处理逻辑]
+   4. 用户看到 [结果/反馈]
+   
+   **异常流程**
+   - [条件] → 系统提示 "[错误信息]"
+   - 网络超时 → 提示重试，不重复提交
+   
+   **验收标准（AC）**
+   > Given [前置条件]
+   > When [用户操作]
+   > Then [系统行为 + 可量化结果]
+   
+   示例：
+   - AC1: Given 用户输入正确邮箱和密码，When 点击登录，Then 3秒内跳转到首页
+   - AC2: Given 用户连续5次密码错误，When 第6次尝试，Then 账号锁定15分钟并发送通知邮件
+   
+   ---
+
+4. **非功能性需求**:
+   明确产品的质量属性约束：
+   
+   **性能**
+   - 核心页面首屏加载时间：< 2秒（P75）
+   - 核心接口响应时间：< 500ms（P99）
+   - 并发支持：峰值 QPS XXX
+   
+   **可用性与可靠性**
+   - SLA：99.9%（每月不超过 44 分钟停机）
+   - 容灾：支持单机房故障切换
+   - 数据备份：每日全量 + 实时增量
+   
+   **安全**
+   - 涉及 PII 数据字段列表：[手机号、身份证号]
+   - 合规要求：[GDPR / 等保二级 / 金融监管要求]
+   - 脱敏规则：手机号显示 138****8888
+   
+   **兼容性**
+   - 浏览器：Chrome 90+, Safari 14+, Firefox 88+（不支持 IE）
+   - 移动端：iOS 13+, Android 8+
+   - 屏幕适配：最小支持 375px 宽度
+   
+   **国际化**
+   - 语言：简体中文（v1）/ 英文（v2规划）
+   - 时区：UTC+8（如有跨时区需求需说明）
+
+5. **UI/UX 与交互说明**:
+   **设计资源**
+   - Figma/Sketch 链接：[填写]
+   - 设计规范：遵循 [设计系统名称] 组件库
+   - 标注版本：[v1.2 / 待定]
+   
+   **关键交互说明**
+   列出容易被研发忽略的交互细节：
+   
+   - 空状态设计：列表无数据时展示 [空态图 + 引导文案]
+   - Loading 状态：核心操作需要骨架屏（Skeleton），不用转圈
+   - 错误状态：区分网络错误（可重试）和业务错误（不可重试）
+   - 表单校验：实时校验（onBlur）还是提交时校验（onSubmit）
+   - 动效要求：页面切换 fade-in 200ms，按钮点击 100ms 响应反馈
+   
+   **无障碍要求（A11y）**
+   - 图片必须有 alt 属性
+   - 颜色对比度不低于 4.5:1（WCAG AA 标准）
+   - 核心操作支持键盘导航
+
+6. **数据埋点与监控**:
+   **埋点方案**
+   
+   | 事件名 | 触发时机 | 属性 | 说明 |
+   |--------|---------|------|------|
+   | page_view | 进入页面 | page_name, user_id | 必填 |
+   | btn_click | 点击按钮 | btn_name, page | 所有 CTA 按钮 |
+   | form_submit | 表单提交 | form_name, is_success | 含失败原因 |
+   | feature_use | 使用核心功能 | feature_name, duration | 用于功能价值评估 |
+   
+   **业务监控告警**
+   
+   | 指标 | 告警阈值 | 负责人 |
+   |------|---------|--------|
+   | 注册成功率 | < 85% 触发告警 | PM + 后端 |
+   | 支付成功率 | < 95% 立即告警 | PM + 后端 + 运维 |
+   | 页面崩溃率 | > 0.1% 告警 | 前端 |
+   
+   **数据分析需求**
+   - 上线后第 3/7/30 天分析用户路径漏斗
+   - 功能使用率（功能激活用户 / 总用户）
+
+**Output**: Markdown PRD 文档，含背景目标、用户故事、功能详情（含验收标准 AC）、非功能性需求、UI/UX 说明和埋点方案
+**Notes**: 
+- PRD 应明确 Out-of-Scope，避免研发范围蔓延
+- 验收标准必须可测试，"用户体验好" 不是有效的 AC
+- 非功能性需求经常被遗漏，但对系统架构选型影响很大
+- 埋点方案尽早与数据团队对齐，避免上线后补埋导致历史数据断层
+
+### 15. Git 工作流 (git_workflow)
+
+**Triggers**: `Git 工作流`, `git workflow`, `git 规范`, `分支策略`, `branching strategy`, `commit 规范`, `commit convention`, `提交规范`, `PR 规范`, `rebase vs merge`, `冲突解决`, `@ethan git`, `@ethan git-workflow`
+
+**Goal**: 规范 Git 分支策略、提交规范、合并流程，建立团队一致的版本控制工作流
+
+**Steps**:
+
+1. **评估项目特征，选择分支策略**:
+   根据团队规模和发布节奏选择合适的分支策略：
+   
+   **GitFlow 适用场景**
+   - 有明确版本号的产品（如 App、SDK、开源库）
+   - 需要维护多个线上版本
+   - 发布周期较长（周/月级别）
+   
+   ```
+   main          ──●────────────────────●──  (生产稳定)
+   hotfix/1.0.1    └──●──┘                  (紧急修复)
+   release/1.1       └──●──┘               (预发布验证)
+   develop       ──●──────●──────●──────●── (集成分支)
+   feature/login    └──●──┘                 (功能开发)
+   ```
+   
+   **Trunk-Based Development 适用场景**
+   - 持续部署（CD）体系成熟
+   - 有完善的 Feature Flag 机制
+   - 团队规模适中（≤50 人），发布频率高（日/周）
+   
+   ```
+   main  ──●──●──●──●──●──  (直接推送或短命分支 <2天)
+   feat   └──●──┘           (短命功能分支，快速合并)
+   ```
+   
+   **决策矩阵**
+   
+   | 维度 | GitFlow | Trunk-Based |
+   |------|---------|-------------|
+   | 发布频率 | 低（周/月） | 高（日/周） |
+   | 团队规模 | 大 | 中小 |
+   | 多版本维护 | 支持 | 不擅长 |
+   | CI/CD 成熟度 | 低要求 | 高要求 |
+
+2. **制定提交信息规范（Conventional Commits）**:
+   采用 Conventional Commits 规范，格式：`<type>(<scope>): <subject>`
+   
+   **类型（type）定义**
+   
+   | type | 用途 | 版本影响 |
+   |------|------|---------|
+   | `feat` | 新功能 | MINOR |
+   | `fix` | Bug 修复 | PATCH |
+   | `perf` | 性能优化 | PATCH |
+   | `refactor` | 重构（无功能变化） | — |
+   | `docs` | 文档变更 | — |
+   | `test` | 测试相关 | — |
+   | `chore` | 构建/依赖/工具 | — |
+   | `ci` | CI 配置变更 | — |
+   | `BREAKING CHANGE` | 破坏性变更（Footer） | MAJOR |
+   
+   **示例**
+   ```bash
+   # 好的提交信息
+   feat(auth): add OAuth2 login with Google provider
+   fix(cart): prevent duplicate item addition on rapid click
+   perf(query): add composite index on (user_id, created_at)
+   refactor(api): extract pagination helper to shared utils
+   docs(readme): update installation steps for Node 20
+   
+   # 破坏性变更写法
+   feat(api)!: rename /users endpoint to /accounts
+   
+   BREAKING CHANGE: /users endpoint removed, use /accounts instead
+   ```
+   
+   **工具链配置**
+   ```bash
+   # 安装 commitlint
+   npm install -D @commitlint/cli @commitlint/config-conventional
+   echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
+   
+   # 配合 husky 在 commit-msg 钩子校验
+   npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'
+   ```
+
+3. **Rebase vs Merge 决策与实践**:
+   **核心原则：黄金法则 — 不要 rebase 已推送的公共分支**
+   
+   **何时用 Merge**
+   - 合并长期分支（feature → develop）
+   - 需要保留完整历史记录（审计场景）
+   - 多人协作的共享分支
+   
+   ```bash
+   # 保留合并记录（推荐用于 PR/MR 合并）
+   git merge --no-ff feature/login
+   
+   # 快进合并（适合独立小修改）
+   git merge --ff-only hotfix/typo
+   ```
+   
+   **何时用 Rebase**
+   - 更新本地功能分支，与主干保持同步
+   - 整理本地提交历史，推送 PR 前清理
+   
+   ```bash
+   # 将功能分支变基到最新 main
+   git checkout feature/login
+   git rebase origin/main
+   
+   # 交互式 rebase：合并/重排/修改最近 3 个提交
+   git rebase -i HEAD~3
+   # 选项: pick / squash(s) / fixup(f) / reword(r) / drop(d)
+   ```
+   
+   **Squash Merge**（GitHub/GitLab PR 推荐）
+   ```bash
+   # 将功能分支所有提交合并为一个干净提交
+   git merge --squash feature/login
+   git commit -m "feat(auth): add login page with form validation"
+   ```
+   
+   **推荐工作流**
+   1. 本地开发：随意提交，保持节奏
+   2. 推送 PR 前：`git rebase -i origin/main` 整理提交
+   3. PR 合并：使用 Squash Merge 保持主干干净
+
+4. **冲突解决流程**:
+   **结构化冲突解决步骤**
+   
+   ```bash
+   # Step 1: 理解冲突来源
+   git log --oneline --graph --all  # 查看分支关系
+   git diff HEAD origin/main        # 对比差异
+   
+   # Step 2: 标记冲突文件分析
+   git status  # 查看所有冲突文件
+   # conflict markers: <<<<<<< HEAD ... ======= ... >>>>>>> branch
+   
+   # Step 3: 使用工具辅助解决
+   git mergetool  # 调用配置的 merge tool（VSCode / IntelliJ）
+   
+   # 配置 VSCode 为默认 merge tool
+   git config --global merge.tool vscode
+   git config --global mergetool.vscode.cmd 'code --wait $MERGED'
+   ```
+   
+   **三路合并理解（Three-way merge）**
+   ```
+   BASE（公共祖先）：const timeout = 5000;
+   OURS（当前分支）：const timeout = 10000;  // 改为10s
+   THEIRS（被合并）：const TIMEOUT = 5000;   // 改为大写常量名
+   RESULT（手动）：  const TIMEOUT = 10000;  // 两个改动都要
+   ```
+   
+   **预防冲突的最佳实践**
+   - 功能分支生命周期控制在 1-3 天内
+   - 每日同步主干：`git pull --rebase origin main`
+   - 大文件/自动生成文件加入 `.gitattributes` 配置合并策略
+   ```gitattributes
+   # 始终使用 ours 策略合并 lock 文件（减少冲突）
+   package-lock.json merge=ours
+   yarn.lock merge=ours
+   ```
+
+5. **Pull Request / Code Review 流程规范**:
+   **PR 模板设计**
+   ```markdown
+   ## 变更说明
+   [简洁描述本次变更做了什么、为什么]
+   
+   ## 变更类型
+   - [ ] 新功能 (feat)
+   - [ ] Bug 修复 (fix)
+   - [ ] 重构 (refactor)
+   - [ ] 性能优化 (perf)
+   
+   ## 测试验证
+   - [ ] 单元测试通过
+   - [ ] 手动测试场景: [描述]
+   - [ ] 截图/录屏（UI 变更必填）
+   
+   ## 影响范围
+   [描述可能影响的模块或依赖方]
+   
+   ## Checklist
+   - [ ] 代码自查完毕
+   - [ ] 无调试代码 (console.log/debugger)
+   - [ ] 文档已更新（如需要）
+   ```
+   
+   **PR 规模控制**
+   - 理想 PR 大小：< 400 行（不含测试）
+   - 超过 800 行：强制拆分为多个 PR
+   - 可用 `git diff --stat origin/main` 提前检查
+   
+   **分支保护规则（GitHub/GitLab 配置）**
+   ```
+   main 分支保护：
+   ✅ Require pull request reviews (min: 1)
+   ✅ Require status checks to pass (CI/lint/test)
+   ✅ Require branches to be up to date
+   ✅ Restrict push access (仅管理员)
+   ✅ Require signed commits（高安全场景）
+   ```
+
+6. **输出工作流规范文档**:
+   整理为团队可直接使用的规范文档，格式如下：
+   
+   ```markdown
+   ## Git 工作流规范
+   
+   ### 分支命名
+   - feature/<ticket-id>-short-description  (如: feature/PROJ-123-user-login)
+   - fix/<ticket-id>-short-description
+   - hotfix/<version>-short-description     (如: hotfix/1.2.1-payment-crash)
+   - release/<version>                      (如: release/1.3.0)
+   
+   ### 提交规范
+   格式: <type>(<scope>): <subject>
+   示例: feat(auth): add JWT refresh token support
+   
+   ### 禁止行为
+   ❌ 直接推送到 main/master
+   ❌ force push 到共享分支
+   ❌ rebase 已推送的公共分支
+   ❌ 超过 1000 行的单次 PR（紧急 hotfix 除外）
+   
+   ### 分支生命周期
+   - feature 分支: ≤ 5 个工作日
+   - release 分支: ≤ 2 周
+   - hotfix 分支: ≤ 24 小时
+   ```
+
+**Output**: Markdown 工作流规范文档，含分支策略选型建议、提交规范示例、rebase/merge 决策指南、冲突解决 SOP 和 PR 规范模板
+**Notes**: 
+- 分支策略没有银弹，根据团队规模和发版频率选择最适合的
+- force push 操作必须在团队内公告，避免其他成员本地分支混乱
+- 建议在 CI 中自动校验 commit message 格式，而非依赖人工审查
+- 冲突解决后务必运行测试，确保合并结果功能正常
+
+### 16. 单元测试 (unit_testing)
+
+**Triggers**: `单元测试`, `unit test`, `写测试`, `write tests`, `TDD`, `测试设计`, `test design`, `mock 策略`, `mocking`, `测试覆盖率`, `coverage`, `@ethan test`, `@ethan unit-testing`
+
+**Goal**: 运用 AAA 模式和 TDD 工作流编写高质量单元测试，建立覆盖率目标和 Mock 策略
+
+**Steps**:
+
+1. **明确测试目标与范围**:
+   在编写测试前，先明确测什么：
+   
+   **测试金字塔**
+   ```
+           ┌───────────┐
+           │  E2E 测试  │  (少量，慢，高置信)
+          ┌┴───────────┴┐
+          │  集成测试    │  (适量，中速)
+         ┌┴─────────────┴┐
+         │  单元测试      │  (大量，快，低成本)
+         └───────────────┘
+   ```
+   
+   **单元测试应该覆盖**
+   - ✅ 纯函数的各种输入输出（含边界）
+   - ✅ 类/模块的公共方法逻辑
+   - ✅ 条件分支（if/switch/三元）
+   - ✅ 错误处理路径（throw/catch）
+   - ✅ 异步操作（Promise/async-await）
+   
+   **不应该单元测试**
+   - ❌ 简单的 getter/setter（无逻辑）
+   - ❌ 第三方库内部实现
+   - ❌ 框架本身（如 React 渲染机制）
+   - ❌ 私有方法（通过公共方法间接测试）
+
+2. **AAA 模式编写测试用例**:
+   每个测试用例遵循 **Arrange → Act → Assert** 三段式结构：
+   
+   **基础示例（JavaScript/TypeScript with Vitest/Jest）**
+   ```typescript
+   describe('calculateDiscount', () => {
+     it('should apply 20% discount for premium users', () => {
+       // Arrange（准备：设置测试数据和依赖）
+       const user = { type: 'premium', cart: [{ price: 100 }, { price: 50 }] };
+       const expectedTotal = 120;  // 150 * 0.8
+   
+       // Act（执行：调用被测函数）
+       const result = calculateDiscount(user);
+   
+       // Assert（断言：验证结果）
+       expect(result.total).toBe(expectedTotal);
+       expect(result.discountRate).toBe(0.2);
+     });
+   });
+   ```
+   
+   **测试命名规范（Given-When-Then）**
+   ```typescript
+   // 格式: should <expected behavior> when <condition>
+   it('should return null when user is not found')
+   it('should throw AuthError when token is expired')
+   it('should apply 20% discount when user has premium status')
+   
+   // 或使用 Given-When-Then 风格
+   it('given empty cart, when checkout, then throws EmptyCartError')
+   ```
+   
+   **边界条件测试清单**
+   ```typescript
+   describe('parseAge', () => {
+     // 正常值
+     it('should parse valid age 25')
+     // 边界值
+     it('should accept minimum age 0')
+     it('should accept maximum age 150')
+     // 非法值
+     it('should throw when age is negative')
+     it('should throw when age exceeds 150')
+     // 类型边界
+     it('should throw when age is not a number')
+     it('should throw when age is null or undefined')
+     it('should handle decimal by flooring to integer')
+   });
+   ```
+
+3. **TDD 工作流（红-绿-重构）**:
+   **TDD 循环步骤**
+   
+   ```
+   🔴 Red   → 写一个失败的测试（先设计接口）
+   🟢 Green → 写最少代码让测试通过（不过度设计）
+   🔵 Refactor → 在测试保护下重构代码
+   ```
+   
+   **实践示例：用 TDD 实现邮箱验证**
+   
+   ```typescript
+   // Step 1 🔴 先写测试（此时 validateEmail 还不存在）
+   describe('validateEmail', () => {
+     it('should return true for valid email', () => {
+       expect(validateEmail('user@example.com')).toBe(true);
+     });
+     it('should return false for missing @', () => {
+       expect(validateEmail('userexample.com')).toBe(false);
+     });
+     it('should return false for empty string', () => {
+       expect(validateEmail('')).toBe(false);
+     });
+   });
+   
+   // Step 2 🟢 写最简实现让测试通过
+   export function validateEmail(email: string): boolean {
+     return /^[^s@]+@[^s@]+.[^s@]+$/.test(email);
+   }
+   
+   // Step 3 🔵 重构：提取正则为常量，添加类型注释
+   const EMAIL_REGEX = /^[^s@]+@[^s@]+.[^s@]+$/;
+   export function validateEmail(email: string): boolean {
+     if (!email) return false;
+     return EMAIL_REGEX.test(email);
+   }
+   ```
+   
+   **TDD 适用场景**
+   - 明确需求的业务逻辑函数
+   - 工具库/SDK 开发
+   - Bug 修复（先写复现测试再修复）
+   
+   **不强制 TDD 的场景**
+   - 探索性开发阶段
+   - UI 组件（先实现再补测试）
+
+4. **Mock / Stub / Spy 策略**:
+   **三种测试替身的区别**
+   
+   | 类型 | 用途 | 验证方式 |
+   |------|------|---------|
+   | **Stub** | 替换外部依赖，控制返回值 | 只验证输出 |
+   | **Mock** | 验证函数是否被正确调用 | 验证调用行为 |
+   | **Spy** | 监听真实函数的调用情况 | 包装真实实现 |
+   
+   **Vitest/Jest 实践**
+   ```typescript
+   import { vi, describe, it, expect, beforeEach } from 'vitest';
+   
+   // Stub: 控制外部 API 返回值
+   vi.mock('../api/user', () => ({
+     fetchUser: vi.fn().mockResolvedValue({ id: 1, name: 'Alice' }),
+   }));
+   
+   // Mock: 验证函数被调用
+   it('should call sendEmail when user registers', async () => {
+     const sendEmail = vi.fn();
+     await registerUser({ email: 'test@test.com' }, { sendEmail });
+     expect(sendEmail).toHaveBeenCalledOnce();
+     expect(sendEmail).toHaveBeenCalledWith('test@test.com', expect.objectContaining({ subject: 'Welcome' }));
+   });
+   
+   // Spy: 包装真实函数监听
+   it('should log error when fetch fails', async () => {
+     const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+     vi.mocked(fetchUser).mockRejectedValue(new Error('Network Error'));
+     await loadUserProfile(1);
+     expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Network Error'));
+     consoleSpy.mockRestore();
+   });
+   ```
+   
+   **Mock 黄金法则**
+   - 只 Mock 跨边界的依赖（网络、数据库、文件系统、时间）
+   - 不要 Mock 被测单元的内部实现
+   - 每次测试后还原 Mock（使用 `beforeEach(() => vi.clearAllMocks())`）
+
+5. **覆盖率目标与质量保障**:
+   **覆盖率类型与目标**
+   
+   | 覆盖率类型 | 说明 | 建议目标 |
+   |----------|------|---------|
+   | 语句覆盖（Statements） | 执行的语句比例 | ≥ 80% |
+   | 分支覆盖（Branches） | if/else 分支比例 | ≥ 75% |
+   | 函数覆盖（Functions） | 调用的函数比例 | ≥ 80% |
+   | 行覆盖（Lines） | 执行的代码行比例 | ≥ 80% |
+   
+   **Vitest 覆盖率配置**
+   ```typescript
+   // vitest.config.ts
+   export default defineConfig({
+     test: {
+       coverage: {
+         provider: 'v8',  // 或 'istanbul'
+         reporter: ['text', 'html', 'lcov'],
+         thresholds: {
+           statements: 80,
+           branches: 75,
+           functions: 80,
+           lines: 80,
+         },
+         exclude: [
+           'node_modules/',
+           'src/types/',
+           '**/*.config.*',
+           '**/*.d.ts',
+         ],
+       },
+     },
+   });
+   ```
+   
+   **覆盖率反模式（要避免）**
+   ```typescript
+   // ❌ 为了覆盖率写无意义断言
+   it('does something', () => {
+     expect(doSomething()).toBeDefined();  // 没有验证具体行为
+   });
+   
+   // ✅ 验证真实业务逻辑
+   it('should return correct discounted price', () => {
+     expect(calculatePrice(100, 0.1)).toBe(90);
+   });
+   ```
+   
+   **CI 集成**
+   ```yaml
+   # .github/workflows/test.yml
+   - name: Run tests with coverage
+     run: npm run test -- --coverage
+   
+   - name: Comment coverage on PR
+     uses: MishaKav/jest-coverage-comment@main
+     with:
+       coverage-summary-path: ./coverage/coverage-summary.json
+   ```
+
+**Output**: Markdown 测试方案文档，含测试用例设计（AAA 格式）、Mock 策略说明、覆盖率目标和 CI 配置示例
+**Notes**: 
+- 测试应该是自文档化的，好的测试名称比注释更有价值
+- 避免测试实现细节，测试行为而非内部结构，有助于重构时测试不频繁失败
+- 不要追求 100% 覆盖率，关注核心业务逻辑的质量覆盖
+- 测试代码同样需要维护，避免过度复杂的测试辅助函数
+
+### 17. 系统设计 (system_design)
+
+**Triggers**: `系统设计`, `system design`, `架构设计`, `architecture design`, `高并发系统`, `分布式系统`, `distributed system`, `容量估算`, `capacity estimation`, `扩展性设计`, `scalability`, `@ethan design`, `@ethan system-design`
+
+**Goal**: 从需求澄清到架构设计全流程，完成高并发分布式系统的方案设计与权衡分析
+
+**Steps**:
+
+1. **需求澄清与范围界定**:
+   在动手设计前，花 5 分钟澄清需求：
+   
+   **功能需求（Functional Requirements）**
+   - 系统的核心用例是什么？（写出 3-5 个最关键的）
+   - 哪些功能在 scope 内，哪些明确 out of scope？
+   - 用户角色有哪些？各自的主要操作是什么？
+   
+   **非功能需求（Non-Functional Requirements）**
+   
+   | 维度 | 问题 | 示例指标 |
+   |------|------|---------|
+   | 规模 | 用户量 / DAU / QPS 是多少？ | 1亿用户，1000万 DAU |
+   | 性能 | 读写延迟要求？P99 是多少？ | P99 < 100ms |
+   | 可用性 | 允许多少停机时间？ | 99.9%（每年 8.7h） |
+   | 一致性 | 强一致 or 最终一致？ | 最终一致（可接受） |
+   | 持久性 | 数据丢失容忍度？ | RPO = 0（不允许丢失） |
+   
+   **明确边界的示例问题**
+   ```
+   Q: 设计一个 Twitter
+   A（先澄清）:
+   - 只需要发推/关注/Feed 功能吗？（排除私信、广告）
+   - 用户规模：3亿用户，1亿 DAU？
+   - 读写比例：推文读多写少，100:1？
+   - 媒体文件：支持图片/视频吗？
+   - 全球分发还是单地区？
+   ```
+
+2. **容量估算（Back-of-Envelope）**:
+   快速估算系统规模，为架构决策提供数据依据：
+   
+   **常用基准数字**
+   ```
+   内存访问：    ~100ns
+   SSD 访问：    ~100μs
+   HDD 访问：    ~10ms
+   网络往返（同数据中心）：~0.5ms
+   网络往返（跨地区）：    ~100ms
+   
+   1 MB = 10^6 bytes
+   1 GB = 10^9 bytes
+   1 TB = 10^12 bytes
+   ```
+   
+   **估算示例：设计微博（Twitter-like）**
+   ```
+   用户数据：
+   - DAU: 1亿
+   - 每用户每天发1条推文 → 写 QPS = 100M / 86400 ≈ 1160 QPS
+   - 每用户每天读100条 → 读 QPS = 100 × 1160 = 116,000 QPS
+   
+   存储估算：
+   - 单条推文: 140字 × 2字节(UTF-16) = 280字节 ≈ 300字节
+   - 元数据(user_id, timestamp等): 100字节
+   - 每条推文总计: ~400字节
+   - 每日新增: 1.16K QPS × 400字节 × 86400 = ~40 GB/天
+   - 5年存储: 40GB × 365 × 5 ≈ 73 TB
+   
+   带宽估算：
+   - 写带宽: 1160 × 400字节 = ~450 KB/s
+   - 读带宽: 116K × 400字节 = ~45 MB/s
+   ```
+   
+   **结论：** 读多写少（100:1），需要读缓存；存储量大需分库分表；单机无法支撑读 QPS 需多副本。
+
+3. **高层架构设计**:
+   从整体入手，画出系统的核心模块和数据流：
+   
+   **通用分层架构**
+   ```
+   客户端 (Web/Mobile/API Consumer)
+            │
+            ▼
+      DNS + CDN (静态资源 / 地理路由)
+            │
+            ▼
+      Load Balancer (L4/L7, 负载均衡 + SSL 终止)
+       ┌────┴────┐
+       ▼         ▼
+    API Srv   API Srv   (无状态，水平扩展)
+       │
+       ├──→ Cache (Redis: 热数据)
+       ├──→ Message Queue (Kafka: 异步解耦)
+       ├──→ Primary DB (写操作)
+       └──→ Read Replica (读操作)
+            │
+            ▼
+      Object Storage (S3: 文件/媒体)
+      Search Engine (Elasticsearch)
+   ```
+   
+   **架构选型决策点**
+   
+   | 场景 | 选型建议 |
+   |------|---------|
+   | 读多写少 | 读写分离 + 缓存层 |
+   | 高写入吞吐 | 异步消息队列削峰 |
+   | 数据量超百亿行 | 分库分表 / NoSQL |
+   | 强一致性 | 单主 / Paxos / Raft |
+   | 最终一致性 | 多主 / CRDT |
+   | 低延迟全球访问 | CDN + 多地域部署 |
+   | 复杂查询 | 专用搜索引擎 |
+   
+   **微服务 vs 单体 决策**
+   - 团队 < 10人，初创期：单体优先（避免过度工程）
+   - 明确的服务边界、独立扩展需求：拆分微服务
+   - 拆分原则：按业务边界（DDD 限界上下文），而非技术层
+
+4. **核心组件深度设计**:
+   针对最关键的 2-3 个组件进行深入设计：
+   
+   **数据库 Schema 设计**
+   ```sql
+   -- 示例：推文表设计
+   CREATE TABLE tweets (
+     id          BIGINT PRIMARY KEY,      -- Snowflake ID（分布式唯一ID）
+     user_id     BIGINT NOT NULL,
+     content     VARCHAR(280) NOT NULL,
+     created_at  TIMESTAMP DEFAULT NOW(),
+     like_count  INT DEFAULT 0,
+     retweet_count INT DEFAULT 0,
+     INDEX idx_user_created (user_id, created_at DESC)  -- 用户时间线查询
+   );
+   
+   -- Fan-out 策略：预写 vs 拉取
+   -- 方案A: Push（写扩散）: 发推时写入所有粉丝的 Feed 表
+   -- 方案B: Pull（读扩散）: 读取时聚合关注者的推文
+   -- 混合方案: 普通用户 Push，大V（粉丝>100万）Pull
+   ```
+   
+   **缓存策略**
+   ```
+   Cache-Aside（旁路缓存）- 最通用
+   读: 查缓存 → miss → 查DB → 写缓存 → 返回
+   写: 更新DB → 删除缓存（避免双写不一致）
+   
+   Write-Through（写穿）- 一致性高
+   写: 同时写DB和缓存
+   
+   Write-Behind（写回）- 高性能
+   写: 先写缓存，异步批量写DB（风险：缓存宕机丢数据）
+   
+   缓存 Key 设计示例:
+   user:{userId}:profile      → 用户资料
+   user:{userId}:feed:page:{n} → 用户 Feed 分页
+   tweet:{tweetId}            → 单条推文
+   ```
+   
+   **API 接口设计**
+   ```
+   POST /tweets              发布推文
+   GET  /users/{id}/feed     获取 Feed (cursor分页)
+   POST /tweets/{id}/like    点赞
+   GET  /tweets/{id}         获取单条推文
+   
+   分页策略: cursor-based > offset-based（大数据量场景）
+   cursor: base64(created_at + tweet_id)
+   ```
+
+5. **可扩展性与可用性权衡**:
+   **CAP 定理实践**
+   ```
+   C（一致性）+ A（可用性）+ P（分区容错）三选二
+   网络分区不可避免 → 通常是 CP 或 AP 的选择
+   
+   CP 系统: ZooKeeper, HBase（金融交易、库存扣减）
+   AP 系统: Cassandra, DynamoDB（社交Feed、购物车）
+   ```
+   
+   **水平扩展策略**
+   
+   | 层次 | 策略 |
+   |------|------|
+   | 无状态应用层 | 直接水平扩展 + 负载均衡 |
+   | 有状态缓存 | 一致性哈希分片（Redis Cluster） |
+   | 数据库水平 | 分库分表（按 user_id % N） |
+   | 数据库垂直 | 主从复制，读写分离 |
+   
+   **单点故障（SPOF）消除清单**
+   - [ ] Load Balancer 双活/主备
+   - [ ] 数据库主从 + 自动故障转移（MHA/Orchestrator）
+   - [ ] 缓存集群（Redis Sentinel / Cluster）
+   - [ ] 消息队列多副本（Kafka Replication Factor ≥ 3）
+   - [ ] 跨可用区部署（Multi-AZ）
+   
+   **限流与熔断**
+   ```
+   限流: Token Bucket（突发流量友好）
+        Sliding Window（精准限流）
+        分级限流: 用户级 → 接口级 → 全局
+   
+   熔断: Closed → Open（失败率>50%）→ Half-Open（探测恢复）
+   工具: Resilience4j（Java）/ hystrix-go / Polly(.NET)
+   ```
+
+6. **输出系统设计文档**:
+   整理为结构化设计文档：
+   
+   ```markdown
+   ## 系统设计方案：[系统名称]
+   
+   ### 1. 需求概述
+   **功能需求**（核心功能列表）
+   **非功能需求**（QPS / 延迟 / 可用性 / 存储）
+   
+   ### 2. 容量估算
+   | 指标 | 估算值 |
+   |------|-------|
+   | DAU | X 万 |
+   | 写 QPS | X |
+   | 读 QPS | X |
+   | 存储（5年） | X TB |
+   
+   ### 3. 系统架构图
+   [ASCII 图或 Mermaid 图]
+   
+   ### 4. 核心组件设计
+   - **数据库 Schema**：[关键表设计]
+   - **缓存策略**：[策略选择与理由]
+   - **API 设计**：[关键接口]
+   
+   ### 5. 扩展性方案
+   - **瓶颈点**：[识别的瓶颈]
+   - **解决方案**：[具体方案]
+   
+   ### 6. 权衡与风险
+   [已知权衡和设计风险]
+   ```
+
+**Output**: Markdown 系统设计文档，含需求澄清结果、容量估算数据、架构图、核心组件设计方案和扩展性权衡分析
+**Notes**: 
+- 系统设计没有标准答案，重点展示思考过程和权衡意识
+- 先画出高层架构，再逐步深入细节，避免一开始陷入细节
+- 主动提出设计中的权衡和不足，展示对复杂度的认知
+- 数量级估算误差在 10x 以内即可，重要的是数量级概念
+
+### 18. 数据库优化 (database_optimize)
+
+**Triggers**: `数据库优化`, `database optimize`, `慢查询`, `slow query`, `SQL 优化`, `SQL optimization`, `索引优化`, `index optimization`, `N+1 问题`, `N+1 query`, `查询性能`, `query performance`, `@ethan db`, `@ethan database-optimize`
+
+**Goal**: 系统诊断数据库性能问题，涵盖 Schema 审查、索引设计、慢查询分析和 N+1 修复
+
+**Steps**:
+
+1. **Schema 设计审查**:
+   检查数据库表结构是否存在设计问题：
+   
+   **规范化检查（防止冗余）**
+   ```sql
+   -- ❌ 反模式：在用户表存储地址字符串
+   CREATE TABLE users (
+     id INT PRIMARY KEY,
+     name VARCHAR(100),
+     address VARCHAR(500)  -- 难以精准查询城市/省份
+   );
+   
+   -- ✅ 正确：拆分为 addresses 表
+   CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(100));
+   CREATE TABLE addresses (
+     id INT PRIMARY KEY,
+     user_id INT REFERENCES users(id),
+     province VARCHAR(50),
+     city VARCHAR(50),
+     detail VARCHAR(200)
+   );
+   ```
+   
+   **数据类型选择**
+   
+   | 场景 | 推荐类型 | 避免 |
+   |------|---------|------|
+   | 主键 | BIGINT / UUID | INT（可能溢出） |
+   | 状态枚举 | TINYINT / ENUM | VARCHAR |
+   | 金额 | DECIMAL(10,2) | FLOAT（精度丢失）|
+   | 时间 | TIMESTAMP / DATETIME | VARCHAR |
+   | 短字符串(≤255) | VARCHAR(N) | TEXT |
+   | 布尔值 | TINYINT(1) | VARCHAR('true') |
+   
+   **常见 Schema 问题清单**
+   - [ ] 是否有未使用的列？
+   - [ ] VARCHAR 长度是否合理（不要都 VARCHAR(255)）？
+   - [ ] 外键是否有索引？
+   - [ ] 是否有重复的字段（非规范化导致）？
+   - [ ] 是否用了 TEXT/BLOB 存储应该单独存储的大文件？
+
+2. **索引设计策略**:
+   **索引类型选择**
+   
+   ```sql
+   -- 单列索引：高选择性字段（如 email、手机号）
+   CREATE INDEX idx_users_email ON users(email);
+   
+   -- 联合索引：遵循最左前缀原则
+   -- 适合查询: WHERE status = ? AND created_at > ?
+   -- 适合查询: WHERE status = ?
+   -- 不适合:   WHERE created_at > ?  （无法命中）
+   CREATE INDEX idx_orders_status_created ON orders(status, created_at);
+   
+   -- 覆盖索引：索引包含查询所有字段，避免回表
+   -- 查询: SELECT user_id, status FROM orders WHERE order_no = ?
+   CREATE INDEX idx_orders_covering ON orders(order_no, user_id, status);
+   
+   -- 前缀索引：长字符串节省空间
+   CREATE INDEX idx_url_prefix ON pages(url(50));
+   
+   -- 函数索引（MySQL 8.0+）：对表达式建索引
+   CREATE INDEX idx_lower_email ON users((LOWER(email)));
+   ```
+   
+   **EXPLAIN 分析索引使用**
+   ```sql
+   EXPLAIN SELECT * FROM orders
+   WHERE user_id = 1001 AND status = 'PAID'
+   ORDER BY created_at DESC LIMIT 10;
+   
+   -- 关注字段:
+   -- type:  ref > range > index > ALL（ALL 最差）
+   -- key:   使用的索引名（NULL 表示未使用索引）
+   -- rows:  预估扫描行数（越小越好）
+   -- Extra: Using filesort / Using temporary（需优化的信号）
+   ```
+   
+   **索引原则**
+   - 高频查询的 WHERE / JOIN / ORDER BY 字段建索引
+   - 选择性低的字段慎建索引（如 status 只有3个值）
+   - 避免在频繁更新的列上建过多索引（写性能代价）
+   - 复合索引字段顺序：等值条件在前，范围条件在后
+
+3. **慢查询分析与优化**:
+   **开启慢查询日志**
+   ```sql
+   -- MySQL 配置
+   SET GLOBAL slow_query_log = 'ON';
+   SET GLOBAL long_query_time = 1;  -- 超过1秒记录
+   SET GLOBAL log_queries_not_using_indexes = 'ON';
+   
+   -- 查看慢查询日志文件位置
+   SHOW VARIABLES LIKE 'slow_query_log_file';
+   
+   -- 使用 pt-query-digest 分析日志
+   pt-query-digest /var/log/mysql/slow.log | head -100
+   ```
+   
+   **常见慢查询模式与修复**
+   ```sql
+   -- ❌ 问题1: SELECT * 全列查询
+   SELECT * FROM orders WHERE user_id = 1001;
+   -- ✅ 修复: 只查需要的列
+   SELECT id, order_no, status, total FROM orders WHERE user_id = 1001;
+   
+   -- ❌ 问题2: 对索引列使用函数，导致索引失效
+   SELECT * FROM orders WHERE DATE(created_at) = '2024-01-01';
+   -- ✅ 修复: 使用范围查询
+   SELECT * FROM orders
+   WHERE created_at >= '2024-01-01' AND created_at < '2024-01-02';
+   
+   -- ❌ 问题3: OR 导致索引失效（某些情况）
+   SELECT * FROM users WHERE email = ? OR phone = ?;
+   -- ✅ 修复: UNION ALL
+   SELECT * FROM users WHERE email = ?
+   UNION ALL
+   SELECT * FROM users WHERE phone = ?;
+   
+   -- ❌ 问题4: LIKE 前缀通配符
+   SELECT * FROM products WHERE name LIKE '%iPhone%';
+   -- ✅ 修复: 使用全文索引或 Elasticsearch
+   SELECT * FROM products WHERE MATCH(name) AGAINST('iPhone' IN BOOLEAN MODE);
+   
+   -- ❌ 问题5: 隐式类型转换
+   SELECT * FROM users WHERE user_id = '1001';  -- user_id 是 INT
+   -- ✅ 修复: 类型匹配
+   SELECT * FROM users WHERE user_id = 1001;
+   ```
+
+4. **N+1 查询识别与修复**:
+   **N+1 问题定义**：查询1次获取N条记录，再针对每条记录查询1次，共 N+1 次数据库访问。
+   
+   **ORM 场景中的 N+1**
+   ```typescript
+   // ❌ TypeORM N+1 示例：查100个用户 → 执行101次SQL
+   const users = await userRepository.find();  // Query 1: SELECT * FROM users
+   for (const user of users) {
+     const orders = await user.orders;         // Query 2-101: 每个用户各查一次
+     console.log(orders.length);
+   }
+   
+   // ✅ 修复：使用 eager loading（JOIN）
+   const users = await userRepository.find({
+     relations: ['orders'],  // 一次 JOIN 查询搞定
+   });
+   
+   // ✅ 或使用 QueryBuilder（更精确控制）
+   const users = await userRepository
+     .createQueryBuilder('user')
+     .leftJoinAndSelect('user.orders', 'order')
+     .where('order.status = :status', { status: 'PAID' })
+     .getMany();
+   ```
+   
+   **原生 SQL 批量查询模式**
+   ```sql
+   -- ❌ N+1: 循环查询
+   -- for user_id in user_ids: SELECT * FROM orders WHERE user_id = ?
+   
+   -- ✅ 批量查询 + 应用层 Map 聚合
+   SELECT user_id, COUNT(*) as order_count, SUM(total) as total_amount
+   FROM orders
+   WHERE user_id IN (1,2,3,...,100)  -- 一次查询
+   GROUP BY user_id;
+   -- 在应用层用 Map 按 user_id 聚合
+   ```
+   
+   **检测 N+1 工具**
+   ```
+   - Laravel Debugbar（PHP）
+   - Django Debug Toolbar（Python）
+   - Bullet gem（Rails）
+   - TypeORM logging: { logging: true } 观察 SQL 数量
+   - DataLoader（GraphQL 场景批量加载）
+   ```
+
+5. **分区与分表策略**:
+   **表分区（Partitioning）— 单机方案**
+   ```sql
+   -- 按时间范围分区（适合日志、订单历史）
+   CREATE TABLE orders (
+     id BIGINT,
+     user_id INT,
+     created_at DATETIME,
+     total DECIMAL(10,2)
+   ) PARTITION BY RANGE (YEAR(created_at)) (
+     PARTITION p2022 VALUES LESS THAN (2023),
+     PARTITION p2023 VALUES LESS THAN (2024),
+     PARTITION p2024 VALUES LESS THAN (2025),
+     PARTITION pmax  VALUES LESS THAN MAXVALUE
+   );
+   
+   -- 分区裁剪：查询自动只扫描相关分区
+   SELECT * FROM orders WHERE created_at >= '2024-01-01';
+   -- 只扫描 p2024 分区，跳过历史分区
+   ```
+   
+   **分库分表策略（超千万行后考虑）**
+   
+   | 方案 | 分片键选择 | 适用场景 |
+   |------|----------|---------|
+   | 水平分表（同库） | user_id % N | 单库容量瓶颈 |
+   | 水平分库 | user_id % N | 读写 QPS 瓶颈 |
+   | 按地区分库 | region | 合规/延迟要求 |
+   
+   ```
+   分片键选择原则:
+   - 选择查询中高频使用的字段（避免跨分片查询）
+   - 选择数据分布均匀的字段（避免热点）
+   - 一旦确定不能轻易更改
+   
+   常见工具:
+   - ShardingSphere（Java）
+   - Vitess（MySQL 集群，YouTube 方案）
+   - Citus（PostgreSQL 分布式扩展）
+   ```
+   
+   **读写分离配置**
+   ```
+   主库（Primary）: 处理写操作 + 强一致读
+   从库（Replica）: 处理读操作（注意主从延迟，通常 <1s）
+   
+   适用于读写比 > 4:1 的场景
+   注意: 写后立即读可能读到旧数据（主从同步延迟）
+   解决: 重要读操作路由到主库；或用 Redis 缓存最新写入
+   ```
+
+**Output**: Markdown 优化报告，含 Schema 问题列表、索引设计方案、慢查询 EXPLAIN 分析、N+1 修复代码示例和分区建议
+**Notes**: 
+- 优化前先用 EXPLAIN 分析，避免盲目加索引
+- 索引不是越多越好，每个索引都会降低写入性能，控制在 5-8 个以内
+- 分库分表是最后手段，优先考虑索引优化、缓存、读写分离
+- 生产环境加索引使用 gh-ost 或 pt-online-schema-change，避免锁表
+
+### 19. Docker 容器化 (docker)
+
+**Triggers**: `Docker`, `docker`, `容器化`, `containerization`, `Dockerfile`, `dockerfile`, `docker-compose`, `镜像优化`, `image optimization`, `多阶段构建`, `multi-stage build`, `容器安全`, `@ethan docker`
+
+**Goal**: 编写生产级 Dockerfile，实现多阶段构建、镜像优化和 docker-compose 编排
+
+**Steps**:
+
+1. **Dockerfile 基础最佳实践**:
+   **基础规则清单**
+   
+   ```dockerfile
+   # ✅ 使用具体版本标签，避免 latest（不可复现）
+   FROM node:20.11-alpine3.19
+   
+   # ✅ 设置工作目录（避免在根目录操作）
+   WORKDIR /app
+   
+   # ✅ 先复制依赖文件，利用层缓存
+   # 依赖文件不变时，npm install 层直接复用缓存
+   COPY package*.json ./
+   RUN npm ci --only=production
+   
+   # ✅ 再复制源码（源码改变不影响依赖缓存）
+   COPY . .
+   
+   # ✅ 使用非 root 用户运行（安全最佳实践）
+   RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+   USER appuser
+   
+   # ✅ 仅暴露必要端口
+   EXPOSE 3000
+   
+   # ✅ 使用 ENTRYPOINT + CMD 组合（更灵活）
+   ENTRYPOINT ["node"]
+   CMD ["dist/index.js"]
+   ```
+   
+   **层缓存优化原则**
+   ```
+   构建缓存命中规则：指令 + 参数 + 上下文文件 都相同才命中缓存
+   
+   优化策略:
+   1. 变化频率低的指令放前面（基础镜像、系统依赖）
+   2. 变化频率高的指令放后面（应用代码）
+   3. 合并 RUN 指令减少层数
+   
+   # ❌ 多个 RUN 产生多个层
+   RUN apt-get update
+   RUN apt-get install -y curl
+   RUN apt-get clean
+   
+   # ✅ 合并为一个 RUN，减少层数 + 及时清理缓存
+   RUN apt-get update && apt-get install -y curl     && rm -rf /var/lib/apt/lists/*
+   ```
+
+2. **多阶段构建（Multi-Stage Build）**:
+   多阶段构建将构建环境与运行环境分离，显著减小生产镜像体积：
+   
+   **Node.js 应用示例**
+   ```dockerfile
+   # ===== Stage 1: Build =====
+   FROM node:20.11-alpine3.19 AS builder
+   WORKDIR /app
+   
+   # 安装所有依赖（含 devDependencies）
+   COPY package*.json ./
+   RUN npm ci
+   
+   # 编译 TypeScript
+   COPY . .
+   RUN npm run build
+   
+   # ===== Stage 2: Dependencies =====
+   FROM node:20.11-alpine3.19 AS deps
+   WORKDIR /app
+   COPY package*.json ./
+   # 只安装生产依赖
+   RUN npm ci --only=production
+   
+   # ===== Stage 3: Production =====
+   FROM node:20.11-alpine3.19 AS production
+   WORKDIR /app
+   
+   # 只从前两个阶段复制必要文件
+   COPY --from=deps /app/node_modules ./node_modules
+   COPY --from=builder /app/dist ./dist
+   
+   # 非 root 用户
+   RUN addgroup -S app && adduser -S app -G app
+   USER app
+   
+   EXPOSE 3000
+   HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
+   CMD ["node", "dist/index.js"]
+   ```
+   
+   **效果对比**
+   ```
+   单阶段构建（含 devDeps + 源码）:  ~800 MB
+   多阶段构建（只含运行时）:          ~120 MB
+   体积减少约 85%
+   ```
+   
+   **Go 应用（静态二进制最小镜像）**
+   ```dockerfile
+   FROM golang:1.22-alpine AS builder
+   WORKDIR /app
+   COPY go.mod go.sum ./
+   RUN go mod download
+   COPY . .
+   RUN CGO_ENABLED=0 GOOS=linux go build -o server .
+   
+   # 使用 scratch（空镜像）或 distroless
+   FROM gcr.io/distroless/static-debian12
+   COPY --from=builder /app/server /server
+   EXPOSE 8080
+   ENTRYPOINT ["/server"]
+   # 最终镜像仅 ~10MB
+   ```
+
+3. **.dockerignore 与镜像安全**:
+   **配置 .dockerignore**
+   ```dockerignore
+   # 排除不需要的文件，减小构建上下文
+   node_modules
+   npm-debug.log
+   .git
+   .gitignore
+   .env
+   .env.*
+   *.md
+   .DS_Store
+   coverage/
+   dist/
+   .nyc_output
+   __tests__
+   *.test.ts
+   Dockerfile*
+   docker-compose*
+   ```
+   
+   **镜像安全扫描**
+   ```bash
+   # Trivy（推荐，免费开源）
+   docker pull aquasec/trivy
+   trivy image --severity HIGH,CRITICAL myapp:latest
+   
+   # 输出示例:
+   # CRITICAL: CVE-2024-xxxx in openssl 3.0.0 → 升级到 3.0.13
+   
+   # 集成到 CI（GitHub Actions）
+   - name: Scan Docker image
+     uses: aquasecurity/trivy-action@master
+     with:
+       image-ref: 'myapp:${{ github.sha }}'
+       severity: 'CRITICAL,HIGH'
+       exit-code: '1'  # 发现高危漏洞时 CI 失败
+   ```
+   
+   **容器运行时安全配置**
+   ```bash
+   # 禁止 root 运行（Dockerfile 中已设置 USER，运行时再确认）
+   docker run --user 1001:1001 myapp:latest
+   
+   # 只读文件系统（防止容器内写文件）
+   docker run --read-only --tmpfs /tmp myapp:latest
+   
+   # 限制资源
+   docker run --memory="256m" --cpus="0.5" myapp:latest
+   
+   # 丢弃不需要的 Linux Capabilities
+   docker run --cap-drop ALL --cap-add NET_BIND_SERVICE myapp:latest
+   
+   # 禁止权限提升
+   docker run --security-opt no-new-privileges myapp:latest
+   ```
+
+4. **Docker Compose 服务编排**:
+   **生产级 docker-compose.yml 示例**
+   ```yaml
+   version: '3.9'
+   
+   services:
+     app:
+       build:
+         context: .
+         dockerfile: Dockerfile
+         target: production        # 指定多阶段构建的目标阶段
+       image: myapp:${APP_VERSION:-latest}
+       restart: unless-stopped
+       ports:
+         - "3000:3000"
+       environment:
+         NODE_ENV: production
+         DATABASE_URL: ${DATABASE_URL}    # 从 .env 文件读取，不硬编码
+       env_file:
+         - .env.production
+       depends_on:
+         db:
+           condition: service_healthy     # 等待健康检查通过
+         redis:
+           condition: service_healthy
+       healthcheck:
+         test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
+         interval: 30s
+         timeout: 5s
+         retries: 3
+         start_period: 40s
+       deploy:
+         resources:
+           limits:
+             cpus: '1.0'
+             memory: 512M
+       networks:
+         - app-network
+   
+     db:
+       image: postgres:16-alpine
+       restart: unless-stopped
+       environment:
+         POSTGRES_DB: ${DB_NAME}
+         POSTGRES_USER: ${DB_USER}
+         POSTGRES_PASSWORD: ${DB_PASSWORD}
+       volumes:
+         - postgres-data:/var/lib/postgresql/data
+         - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
+       healthcheck:
+         test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
+         interval: 10s
+         timeout: 5s
+         retries: 5
+       networks:
+         - app-network
+   
+     redis:
+       image: redis:7-alpine
+       restart: unless-stopped
+       command: redis-server --requirepass ${REDIS_PASSWORD}
+       volumes:
+         - redis-data:/data
+       healthcheck:
+         test: ["CMD", "redis-cli", "ping"]
+         interval: 10s
+       networks:
+         - app-network
+   
+   networks:
+     app-network:
+       driver: bridge
+   
+   volumes:
+     postgres-data:
+     redis-data:
+   ```
+   
+   **常用 Compose 命令**
+   ```bash
+   docker compose up -d               # 后台启动
+   docker compose up -d --build       # 重新构建并启动
+   docker compose logs -f app         # 实时查看日志
+   docker compose exec app sh         # 进入容器 shell
+   docker compose ps                  # 查看服务状态
+   docker compose down -v             # 停止并删除 volume
+   ```
+
+5. **镜像优化与发布**:
+   **镜像大小优化总结**
+   
+   | 优化手段 | 效果 |
+   |---------|------|
+   | 使用 Alpine 基础镜像 | node:20 → node:20-alpine，1.1GB → 150MB |
+   | 多阶段构建 | 去除构建工具 & devDependencies |
+   | .dockerignore | 减小构建上下文 |
+   | 合并 RUN 清理缓存 | 减少层数和大小 |
+   | distroless/scratch | Go/Rust 应用极小镜像 |
+   
+   **镜像打标签规范**
+   ```bash
+   # 语义化版本 + git commit hash
+   docker build -t myapp:1.2.3 -t myapp:1.2.3-abc1234 .
+   
+   # CI 中自动打标签
+   docker build   -t myregistry/myapp:${VERSION}   -t myregistry/myapp:latest   --label "git.commit=${GIT_SHA}"   --label "build.date=$(date -u +%Y-%m-%dT%H:%M:%SZ)"   .
+   ```
+   
+   **镜像推送到 Registry**
+   ```bash
+   # 登录到 GitHub Container Registry
+   echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin
+   
+   # 推送
+   docker push ghcr.io/org/myapp:1.2.3
+   
+   # 使用 Docker BuildKit（并行构建，更快）
+   DOCKER_BUILDKIT=1 docker build .
+   
+   # 多平台构建（兼容 ARM Mac 和 x86 服务器）
+   docker buildx build --platform linux/amd64,linux/arm64   -t myapp:latest --push .
+   ```
+
+**Output**: Markdown 容器化方案，含优化后的 Dockerfile、.dockerignore、docker-compose.yml 配置和安全加固建议
+**Notes**: 
+- 生产镜像绝不使用 :latest 标签，始终用具体版本号确保可复现
+- 绝不在 Dockerfile 中写入密钥或密码，使用环境变量或 Docker Secrets
+- 每次发版前用 Trivy 扫描镜像漏洞，CRITICAL 漏洞不上线
+- docker-compose 仅用于本地开发和小规模部署，生产大规模编排推荐 Kubernetes
+
+### 20. CI/CD 流水线 (cicd)
+
+**Triggers**: `CI/CD`, `cicd`, `流水线`, `pipeline`, `持续集成`, `continuous integration`, `持续部署`, `continuous deployment`, `自动化部署`, `automated deployment`, `GitHub Actions`, `构建优化`, `@ethan cicd`, `@ethan ci`
+
+**Goal**: 设计完整 CI/CD 流水线，涵盖流水线阶段设计、测试自动化、部署门控和回滚策略
+
+**Steps**:
+
+1. **流水线阶段设计**:
+   **标准 CI/CD 流水线结构**
+   
+   ```
+   Push/PR → [CI 阶段] → [镜像构建] → [部署到 Staging] → [部署到 Production]
+   
+   CI 阶段（每次 Push/PR 触发）:
+     ├── 代码检查: Lint + Type Check
+     ├── 单元测试: Unit Tests + Coverage
+     ├── 安全扫描: SAST + Dependency Audit
+     └── 构建验证: Build Success Check
+   
+   镜像构建（CI 通过后）:
+     ├── Docker Build（多平台）
+     ├── 镜像安全扫描（Trivy）
+     └── 推送到 Registry（打 tag）
+   
+   部署流程:
+     ├── Staging（自动，合并到 main 后）
+     │   ├── 集成测试
+     │   └── E2E 测试（冒烟）
+     └── Production（需审批 or 手动触发）
+         ├── 部署策略（蓝绿/金丝雀）
+         └── 部署后验证（健康检查）
+   ```
+   
+   **快速反馈原则**
+   - CI 总时长目标：< 10 分钟（开发者等待阈值）
+   - 测试并行化：单元测试 → 集成测试 → E2E（分层执行）
+   - Fail Fast：代码格式错误最先检查，最快发现
+
+2. **GitHub Actions 流水线配置**:
+   **完整 CI 工作流示例**
+   ```yaml
+   # .github/workflows/ci.yml
+   name: CI
+   
+   on:
+     push:
+       branches: [main, develop]
+     pull_request:
+       branches: [main]
+   
+   env:
+     NODE_VERSION: '20'
+     REGISTRY: ghcr.io
+     IMAGE_NAME: ${{ github.repository }}
+   
+   jobs:
+     # ─── 代码质量检查 ───────────────────────────────
+     lint:
+       name: Lint & Type Check
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v4
+         - uses: actions/setup-node@v4
+           with:
+             node-version: ${{ env.NODE_VERSION }}
+             cache: 'npm'
+         - run: npm ci
+         - run: npm run lint
+         - run: npm run typecheck
+   
+     # ─── 测试 ────────────────────────────────────────
+     test:
+       name: Unit Tests
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v4
+         - uses: actions/setup-node@v4
+           with:
+             node-version: ${{ env.NODE_VERSION }}
+             cache: 'npm'
+         - run: npm ci
+         - run: npm run test -- --coverage
+         - name: Upload coverage to Codecov
+           uses: codecov/codecov-action@v4
+           with:
+             token: ${{ secrets.CODECOV_TOKEN }}
+   
+     # ─── 安全扫描 ───────────────────────────────────
+     security:
+       name: Security Audit
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v4
+         - run: npm audit --audit-level=high
+         - uses: github/codeql-action/init@v3
+           with:
+             languages: javascript
+         - uses: github/codeql-action/analyze@v3
+   
+     # ─── 构建镜像 ───────────────────────────────────
+     build:
+       name: Build & Push Image
+       needs: [lint, test, security]
+       runs-on: ubuntu-latest
+       if: github.ref == 'refs/heads/main'
+       permissions:
+         contents: read
+         packages: write
+       outputs:
+         image-tag: ${{ steps.meta.outputs.tags }}
+       steps:
+         - uses: actions/checkout@v4
+         - uses: docker/setup-buildx-action@v3
+         - uses: docker/login-action@v3
+           with:
+             registry: ${{ env.REGISTRY }}
+             username: ${{ github.actor }}
+             password: ${{ secrets.GITHUB_TOKEN }}
+         - uses: docker/metadata-action@v5
+           id: meta
+           with:
+             images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+             tags: |
+               type=sha,prefix={{branch}}-
+               type=semver,pattern={{version}}
+         - uses: docker/build-push-action@v5
+           with:
+             push: true
+             tags: ${{ steps.meta.outputs.tags }}
+             cache-from: type=gha
+             cache-to: type=gha,mode=max
+   ```
+
+3. **构建速度优化**:
+   **缓存策略**
+   ```yaml
+   # npm/yarn 依赖缓存
+   - uses: actions/cache@v4
+     with:
+       path: ~/.npm
+       key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+       restore-keys: |
+         ${{ runner.os }}-node-
+   
+   # Docker layer 缓存（使用 GitHub Actions Cache）
+   - uses: docker/build-push-action@v5
+     with:
+       cache-from: type=gha
+       cache-to: type=gha,mode=max
+   ```
+   
+   **并行执行策略**
+   ```yaml
+   # 使用 matrix 并行运行测试
+   jobs:
+     test:
+       strategy:
+         matrix:
+           shard: [1, 2, 3, 4]     # 4个并行 runner
+       steps:
+         - run: npm test -- --shard=${{ matrix.shard }}/4
+   ```
+   
+   **跳过不必要的 CI**
+   ```yaml
+   # 路径过滤：文档变更不触发完整 CI
+   on:
+     push:
+       paths-ignore:
+         - 'docs/**'
+         - '*.md'
+         - '.github/ISSUE_TEMPLATE/**'
+   
+   # 或者使用 paths 只触发相关路径
+   on:
+     push:
+       paths:
+         - 'src/**'
+         - 'tests/**'
+         - 'package*.json'
+   ```
+   
+   **Self-hosted Runner（节省 CI 费用）**
+   ```
+   适用场景: 大型项目、私有依赖、特殊硬件需求
+   注意事项:
+   - 安全隔离（不要在 public repo 使用 self-hosted runner）
+   - 定期更新 runner 软件
+   - 隔离不同项目的 runner（避免环境污染）
+   ```
+
+4. **部署策略与门控**:
+   **三种主要部署策略**
+   
+   **蓝绿部署（Blue-Green）**
+   ```
+   适用: 需要零停机、可快速回滚的场景
+   成本: 双倍资源（同时运行两套环境）
+   
+   Blue（当前生产）: v1.0 → 接收所有流量
+   Green（新版本）:  v1.1 → 部署验证中
+   切换: 负载均衡器流量从 Blue → Green（瞬间完成）
+   回滚: 流量切回 Blue（秒级）
+   ```
+   
+   **金丝雀部署（Canary Release）**
+   ```
+   适用: 高风险变更、需要渐进式验证
+   流程:
+     1%流量 → 新版本（观察5min）
+     → 10%（观察15min）
+     → 50%（观察30min）
+     → 100%（全量）
+   
+   Kubernetes 实现:
+   kubectl scale deployment app-v2 --replicas=1   # 1/10 = 10%
+   kubectl scale deployment app-v1 --replicas=9
+   ```
+   
+   **部署门控（Deployment Gates）配置**
+   ```yaml
+   # GitHub Environments 配置审批
+   deploy-production:
+     environment:
+       name: production
+       url: https://app.example.com
+     # 需要人工审批
+     steps:
+       - name: Request approval
+         uses: trstringer/manual-approval@v1
+         with:
+           approvers: team-lead,cto
+           minimum-approvals: 1
+   
+   # 自动门控：基于健康检查
+   deploy-production:
+     steps:
+       - name: Deploy
+         run: kubectl apply -f k8s/
+       - name: Wait for rollout
+         run: kubectl rollout status deployment/app --timeout=5m
+       - name: Smoke test
+         run: |
+           sleep 10
+           curl -f https://api.example.com/health || exit 1
+   ```
+
+5. **回滚策略与监控告警**:
+   **自动回滚触发条件**
+   ```yaml
+   # 部署后自动验证，失败则回滚
+   steps:
+     - name: Deploy to production
+       id: deploy
+       run: kubectl set image deployment/app app=${{ env.NEW_IMAGE }}
+   
+     - name: Monitor deployment health
+       run: |
+         # 等待10分钟，监控错误率
+         for i in {1..20}; do
+           ERROR_RATE=$(curl -s https://metrics.example.com/api/error-rate)
+           if (( $(echo "$ERROR_RATE > 5" | bc -l) )); then
+             echo "Error rate $ERROR_RATE% exceeds threshold, rolling back!"
+             kubectl rollout undo deployment/app
+             exit 1
+           fi
+           sleep 30
+         done
+   
+     - name: Rollback on failure
+       if: failure() && steps.deploy.outcome == 'success'
+       run: kubectl rollout undo deployment/app
+   ```
+   
+   **Kubernetes 滚动更新配置**
+   ```yaml
+   # deployment.yaml
+   spec:
+     strategy:
+       type: RollingUpdate
+       rollingUpdate:
+         maxSurge: 1          # 最多多启动1个 Pod
+         maxUnavailable: 0    # 始终保持满负载（零停机）
+     minReadySeconds: 30      # Pod 就绪后等待30s再继续
+   ```
+   
+   **部署通知**
+   ```yaml
+   # 部署成功/失败通知到 Slack
+   - name: Notify deployment status
+     uses: slackapi/slack-github-action@v1
+     with:
+       channel-id: 'deployments'
+       slack-message: |
+         ${{ job.status == 'success' && '✅' || '❌' }} Deployment to Production
+         Version: ${{ github.sha }}
+         Actor: ${{ github.actor }}
+         Status: ${{ job.status }}
+     env:
+       SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+   ```
+   
+   **关键 CI/CD 指标**
+   
+   | 指标 | 目标 | 说明 |
+   |------|------|------|
+   | Lead Time | < 1天 | 代码到生产的时间 |
+   | Deploy Frequency | 每日1次+ | 部署频率 |
+   | MTTR | < 1小时 | 故障恢复时间 |
+   | Change Failure Rate | < 15% | 部署导致故障比例 |
+
+**Output**: Markdown CI/CD 方案文档，含流水线阶段图、GitHub Actions YAML 配置、部署策略对比和回滚方案
+**Notes**: 
+- 流水线应该是可靠的，不稳定的 CI 比没有 CI 更糟糕（影响信任度）
+- 保护 main 分支，禁止直接推送，所有变更必须经过 PR + CI 验证
+- 密钥统一用 GitHub Secrets / Vault 管理，严禁硬编码在配置文件中
+- 定期检查并更新 CI Actions 版本，避免使用废弃的 Action 版本
+
+### 21. 性能优化 (performance)
+
+**Triggers**: `性能优化`, `performance`, `页面慢`, `接口慢`, `性能分析`, `profiling`, `Core Web Vitals`, `@ethan 性能`, `/性能优化`
+
+**Goal**: 系统化分析和优化前后端性能瓶颈，涵盖分析工具使用、优化策略和量化指标
+
+**Steps**:
+
+1. **建立性能基线与目标**:
+   优化前先量化，避免盲目优化。
+   
+   **前端核心指标（Core Web Vitals）**
+   | 指标 | 含义 | 优秀 | 需改进 | 差 |
+   |------|------|------|--------|-----|
+   | LCP | 最大内容绘制 | ≤ 2.5s | ≤ 4s | > 4s |
+   | INP | 交互响应延迟 | ≤ 200ms | ≤ 500ms | > 500ms |
+   | CLS | 累积布局偏移 | ≤ 0.1 | ≤ 0.25 | > 0.25 |
+   | TTFB | 首字节时间 | ≤ 800ms | ≤ 1.8s | > 1.8s |
+   
+   **采集工具**
+   ```bash
+   npm install -g @lhci/cli
+   lhci autorun --collect.url=https://yoursite.com
+   
+   npx autocannon -c 100 -d 30 http://localhost:3000/api/users
+   ```
+
+2. **前端性能优化**:
+   **资源加载优化**
+   ```html
+   <link rel="preload" href="/fonts/main.woff2" as="font" crossorigin>
+   <link rel="preconnect" href="https://api.example.com">
+   <img src="hero.jpg" loading="eager" fetchpriority="high" />
+   <img src="below-fold.jpg" loading="lazy" />
+   ```
+   
+   **代码拆分（React）**
+   ```typescript
+   const UserProfile = lazy(() => import('./pages/UserProfile'));
+   
+   // 虚拟列表（大数据量）
+   import { FixedSizeList } from 'react-window';
+   <FixedSizeList height={600} itemCount={10000} itemSize={50}>
+     {({ index, style }) => <div style={style}>Row {index}</div>}
+   </FixedSizeList>
+   ```
+   
+   **打包体积优化**
+   ```bash
+   npx vite-bundle-visualizer
+   # Tree-shaking: 按需引入
+   import { debounce } from 'lodash-es';  // ✅ 非 import _ from 'lodash'
+   ```
+
+3. **后端与数据库性能优化**:
+   **数据库查询优化**
+   ```sql
+   EXPLAIN ANALYZE SELECT u.*, COUNT(o.id)
+   FROM users u LEFT JOIN orders o ON u.id = o.user_id
+   WHERE u.status = 'active' GROUP BY u.id;
+   
+   -- 复合索引
+   CREATE INDEX idx_user_status_created ON users(status, created_at);
+   ```
+   
+   **缓存策略（Redis）**
+   ```typescript
+   async function getUserProfile(userId: string) {
+     const cacheKey = `user:profile:${userId}`;
+     const cached = await redis.get(cacheKey);
+     if (cached) return JSON.parse(cached);
+     const user = await db.users.findUnique({ where: { id: userId } });
+     const ttl = 300 + Math.floor(Math.random() * 60); // 随机TTL防雪崩
+     await redis.setex(cacheKey, ttl, JSON.stringify(user));
+     return user;
+   }
+   ```
+   
+   **并行化异步操作**
+   ```typescript
+   // ✅ 并行（快）
+   const [user, orders] = await Promise.all([getUser(id), getOrders(id)]);
+   ```
+
+4. **性能优化 Checklist 与持续监控**:
+   **优化优先级矩阵**
+   | 优化项 | 影响 | 成本 | 优先级 |
+   |--------|------|------|--------|
+   | 图片压缩/WebP | 高 | 低 | 🔴 立即 |
+   | 关键资源预加载 | 高 | 低 | 🔴 立即 |
+   | 数据库慢查询修复 | 高 | 中 | 🔴 立即 |
+   | 代码拆分/懒加载 | 高 | 中 | 🟡 近期 |
+   | Redis 缓存层 | 高 | 高 | 🟡 规划 |
+   
+   **Lighthouse CI 集成**
+   ```yaml
+   - name: Lighthouse CI
+     uses: treosh/lighthouse-ci-action@v10
+     with:
+       urls: https://yoursite.com
+       uploadArtifacts: true
+   ```
+   
+   **性能优化报告模板**
+   ```
+   优化前：LCP 4.8s | FCP 3.2s | P99 API 1200ms
+   已实施：图片WebP → LCP -1.8s；加索引 → P99 -600ms
+   优化后：LCP 2.3s ✅ | FCP 1.4s ✅ | P99 380ms ✅
+   ```
+
+**Output**: Markdown 性能分析报告，含当前指标基线、瓶颈列表、优化方案和预期收益
+**Notes**: 
+- 先测量再优化，不要猜测瓶颈，用数据说话
+- Core Web Vitals 直接影响 Google SEO 排名
+- 缓存是最有效的优化，但要仔细设计失效策略
+
+### 22. 代码重构 (refactoring)
+
+**Triggers**: `代码重构`, `refactoring`, `refactor`, `重构`, `坏味道`, `bad smell`, `技术债`, `technical debt`, `代码质量改善`, `@ethan refactor`, `@ethan 重构`
+
+**Goal**: 系统化识别代码坏味道，运用重构手法安全改善代码结构，不改变外部行为
+
+**Steps**:
+
+1. **识别代码坏味道（Bad Smells）**:
+   重构前先诊断，明确改善目标：
+   
+   **最常见的 12 种坏味道**
+   
+   | 坏味道 | 症状 | 危害 |
+   |--------|------|------|
+   | **重复代码** | 相同逻辑出现 ≥2 处 | 修改需同步多处，极易遗漏 |
+   | **过长函数** | 函数 > 20 行 | 难以理解、测试、复用 |
+   | **过大的类** | 类承担过多职责 | 违反 SRP，耦合严重 |
+   | **过长参数列表** | 参数 > 4 个 | 调用复杂，难以记忆 |
+   | **发散式变化** | 一个类因不同原因被修改 | 违反 SRP |
+   | **散弹式修改** | 一个变化需改多处 | 高耦合，遗漏风险高 |
+   | **依恋情结** | 方法频繁访问其他类数据 | 逻辑放错了地方 |
+   | **数据泥团** | 多处总是成组出现的数据 | 缺少封装 |
+   | **基本类型偏执** | 用原始类型代替小对象 | 缺少领域建模 |
+   | **注释过多** | 用注释弥补代码的不清晰 | 注释是坏味道的遮羞布 |
+   | **过深嵌套** | 条件/循环嵌套 > 3 层 | 圈复杂度高，难以追踪 |
+   | **僵尸代码** | 死代码、被注释的代码块 | 干扰阅读，增加维护负担 |
+   
+   ```bash
+   # 快速扫描工具
+   npx eslint src --rule '{"complexity": ["warn", 10]}'  # 圈复杂度
+   npx jscpd src --threshold 5                           # 重复代码检测
+   ethan scan --todo                                      # TODO/FIXME 清单
+   ```
+
+2. **核心重构手法**:
+   **提炼函数（Extract Function）** — 最常用
+   
+   ```typescript
+   // Before: 过长函数，注释掩盖意图
+   function processOrder(order: Order) {
+     // 计算折扣
+     let discount = 0;
+     if (order.user.isPremium) discount = 0.1;
+     if (order.total > 1000) discount += 0.05;
+     const finalPrice = order.total * (1 - discount);
+   
+     // 发送确认邮件
+     const subject = `订单 ${order.id} 确认`;
+     sendEmail(order.user.email, subject, finalPrice);
+   }
+   
+   // After: 每个函数做一件事
+   function calculateDiscount(order: Order): number {
+     let discount = 0;
+     if (order.user.isPremium) discount = 0.1;
+     if (order.total > 1000) discount += 0.05;
+     return discount;
+   }
+   
+   function sendOrderConfirmation(order: Order, finalPrice: number): void {
+     const subject = `订单 ${order.id} 确认`;
+     sendEmail(order.user.email, subject, finalPrice);
+   }
+   
+   function processOrder(order: Order) {
+     const discount = calculateDiscount(order);
+     const finalPrice = order.total * (1 - discount);
+     sendOrderConfirmation(order, finalPrice);
+   }
+   ```
+   
+   **以多态取代条件（Replace Conditional with Polymorphism）**
+   
+   ```typescript
+   // Before: switch 散弹式修改
+   function getShippingCost(order: Order): number {
+     switch (order.type) {
+       case 'standard': return order.weight * 10;
+       case 'express': return order.weight * 20 + 50;
+       case 'overnight': return order.weight * 30 + 100;
+     }
+   }
+   
+   // After: 策略模式/多态
+   abstract class ShippingStrategy {
+     abstract calculate(order: Order): number;
+   }
+   class StandardShipping extends ShippingStrategy {
+     calculate(order: Order) { return order.weight * 10; }
+   }
+   class ExpressShipping extends ShippingStrategy {
+     calculate(order: Order) { return order.weight * 20 + 50; }
+   }
+   ```
+   
+   **引入参数对象（Introduce Parameter Object）**
+   
+   ```typescript
+   // Before: 过长参数列表
+   function createReport(startDate: Date, endDate: Date, userId: string, format: string) {}
+   
+   // After: 封装为值对象
+   interface ReportParams { dateRange: DateRange; userId: string; format: string; }
+   function createReport(params: ReportParams) {}
+   ```
+   
+   **其他常用手法速查**
+   
+   | 手法 | 适用场景 |
+   |------|---------|
+   | 提炼类（Extract Class） | 一个类承担过多职责 |
+   | 移动函数（Move Function） | 方法与数据不在一处 |
+   | 内联函数（Inline Function） | 函数体比名字更清晰 |
+   | 分解条件（Decompose Conditional） | 复杂 if-else 逻辑 |
+   | 卫语句（Guard Clauses） | 深层嵌套 → 提前返回 |
+   | 以查询取代临时变量 | 中间临时变量过多 |
+
+3. **重构安全网：测试先行**:
+   **重构铁律：没有测试，不要重构**
+   
+   ```bash
+   # Step 1: 确保现有测试覆盖率充足
+   npm run test:coverage
+   # 目标：被重构的模块覆盖率 > 80%
+   
+   # Step 2: 若无测试，先补特征测试（Characterization Test）
+   # 不是测试"应该如何"，而是记录"当前如何"
+   it('characterization: processOrder returns expected price', () => {
+     const result = processOrder(mockOrder);
+     expect(result).toMatchSnapshot(); // 先快照，重构后验证不变
+   });
+   
+   # Step 3: 小步前进 — 每次重构后立即运行测试
+   npm test -- --watch
+   ```
+   
+   **重构工作流**
+   
+   ```
+   识别目标 → 写/补测试 → 最小重构 → 运行测试 → 提交
+        ↑____________________________|
+              循环，每次改动 < 30min
+   ```
+   
+   **IDE 辅助重构（减少手工失误）**
+   
+   | 操作 | VS Code / WebStorm |
+   |------|-------------------|
+   | 提炼函数 | Ctrl+Shift+R → Extract Method |
+   | 重命名 | F2 → 自动更新所有引用 |
+   | 移动文件 | 拖拽 → 自动更新 import |
+   | 提炼变量 | Ctrl+Shift+R → Extract Variable |
+
+4. **重构策略与输出**:
+   **Boy Scout Rule（童子军规则）**
+   > 让代码比你来时更干净一点，每次 PR 顺手重构接触到的代码。
+   
+   **大规模重构策略：Strangler Fig Pattern（绞杀榕模式）**
+   
+   ```
+   旧系统 ──[façade]──→ 新模块（逐步替换）
+            |
+            └──→ 旧模块（逐步废弃）
+   ```
+   
+   1. 在旧代码外包一层 Façade/Adapter
+   2. 新功能全部写在新结构中
+   3. 旧调用方逐步迁移到新结构
+   4. 旧代码最终归零删除
+   
+   **何时停止重构**
+   
+   | 信号 | 建议 |
+   |------|------|
+   | 测试全绿，代码可读性提升 | 提交，结束本轮 |
+   | 发现需要改外部接口 | 创建新 Issue，本次不做 |
+   | 重构范围不断扩大 | 停止，重新评估范围 |
+   
+   **重构输出清单**
+   - [ ] 坏味道清单（标注优先级 P1/P2/P3）
+   - [ ] 本次重构的 Diff 说明（what changed & why）
+   - [ ] 测试覆盖率前后对比
+   - [ ] 技术债记录到 Issue/Backlog
+
+**Output**: Markdown 重构报告：坏味道清单 + 重构手法说明 + 测试覆盖率变化 + 技术债 Backlog
+**Notes**: 
+- 重构前必须有测试覆盖，否则是在盲目改动——叫重写不叫重构
+- 每次重构只做一件事，不要同时修改功能
+- 利用 IDE 的自动重构功能，减少手工失误
+- 技术债需要持续还，但不要以重构为名无限延期需求
+
+### 23. 可观测性 (observability)
+
+**Triggers**: `可观测性`, `observability`, `监控`, `monitoring`, `日志`, `logging`, `链路追踪`, `tracing`, `指标`, `metrics`, `SLO`, `SLA`, `告警`, `alerting`, `@ethan 监控`, `@ethan observability`
+
+**Goal**: 建立日志、指标、链路追踪三支柱体系，实现系统状态完全可观测，快速定位生产问题
+
+**Steps**:
+
+1. **三支柱体系设计**:
+   **可观测性三支柱（Three Pillars of Observability）**
+   
+   | 支柱 | 回答的问题 | 工具栈 |
+   |------|-----------|--------|
+   | **Logs（日志）** | 发生了什么？ | Winston/Pino + ELK/Loki |
+   | **Metrics（指标）** | 系统状况如何？ | Prometheus + Grafana |
+   | **Traces（链路）** | 请求经过了哪里？ | OpenTelemetry + Jaeger/Tempo |
+   
+   **选型建议**
+   
+   ```
+   轻量级单体:  Pino + Prometheus + Grafana
+   微服务标准:  OpenTelemetry SDK → Collector → Jaeger + Prometheus + Loki
+   云原生托管:  Datadog / New Relic / AWS CloudWatch (开箱即用)
+   ```
+   
+   **黄金信号（Golden Signals）— 4个必监控指标**
+   
+   | 信号 | 说明 | 告警阈值示例 |
+   |------|------|-------------|
+   | **Latency（延迟）** | P50/P99/P999 响应时间 | P99 > 500ms |
+   | **Traffic（流量）** | RPS / 并发连接数 | 环比突增 50% |
+   | **Errors（错误率）** | 5xx / 业务错误比例 | > 0.1% |
+   | **Saturation（饱和度）** | CPU/内存/队列深度 | CPU > 80% |
+
+2. **结构化日志规范**:
+   **日志必须是结构化 JSON，不要用 console.log**
+   
+   ```typescript
+   // ❌ Bad: 非结构化，无法机器解析
+   console.log(`用户 ${userId} 下单失败: ${error.message}`);
+   
+   // ✅ Good: 结构化 JSON 日志（使用 Pino）
+   import pino from 'pino';
+   const logger = pino({ level: 'info' });
+   
+   logger.error({
+     event: 'order.create.failed',
+     userId,
+     orderId,
+     errorCode: error.code,
+     msg: error.message,
+     durationMs: Date.now() - startTime,
+   });
+   ```
+   
+   **日志级别规范**
+   
+   | 级别 | 使用场景 | 生产建议 |
+   |------|---------|---------|
+   | ERROR | 需要立即处理的错误 | 触发告警 |
+   | WARN | 不影响功能但需关注 | 记录 + 汇总 |
+   | INFO | 关键业务事件（下单/登录） | 默认级别 |
+   | DEBUG | 调试信息，技术细节 | 生产关闭 |
+   
+   **必带字段（Mandatory Fields）**
+   
+   ```typescript
+   interface LogContext {
+     traceId: string;    // 链路追踪 ID
+     spanId: string;     // 当前 Span ID
+     userId?: string;    // 用户 ID（有则带）
+     requestId: string;  // 请求唯一 ID
+     service: string;    // 服务名
+     version: string;    // 服务版本
+     env: string;        // prod / staging
+   }
+   ```
+   
+   **日志采样策略**
+   
+   ```typescript
+   // 高流量场景：ERROR 全量，INFO 10% 采样
+   const shouldLog = (level: string) =>
+     level === 'error' || Math.random() < 0.1;
+   ```
+
+3. **指标采集与告警（Prometheus + Grafana）**:
+   **RED 方法论（微服务推荐）**
+   - **R**ate — 每秒请求数
+   - **E**rrors — 错误率
+   - **D**uration — 请求时延分布
+   
+   ```typescript
+   // Node.js 指标暴露（prom-client）
+   import { Counter, Histogram, register } from 'prom-client';
+   
+   const httpRequests = new Counter({
+     name: 'http_requests_total',
+     help: 'Total HTTP requests',
+     labelNames: ['method', 'route', 'status'],
+   });
+   
+   const httpDuration = new Histogram({
+     name: 'http_request_duration_seconds',
+     help: 'HTTP request duration in seconds',
+     labelNames: ['method', 'route'],
+     buckets: [0.005, 0.01, 0.05, 0.1, 0.5, 1, 5],
+   });
+   
+   // Express 中间件
+   app.use((req, res, next) => {
+     const end = httpDuration.startTimer({ method: req.method, route: req.path });
+     res.on('finish', () => {
+       httpRequests.inc({ method: req.method, route: req.path, status: res.statusCode });
+       end();
+     });
+     next();
+   });
+   
+   // 暴露 /metrics 端点
+   app.get('/metrics', async (_, res) => {
+     res.set('Content-Type', register.contentType);
+     res.end(await register.metrics());
+   });
+   ```
+   
+   **Grafana 告警规则示例（Alertmanager）**
+   
+   ```yaml
+   groups:
+     - name: api-alerts
+       rules:
+         - alert: HighErrorRate
+           expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.01
+           for: 2m
+           labels:
+             severity: critical
+           annotations:
+             summary: "错误率超过 1%，当前: {{ $value | humanizePercentage }}"
+   
+         - alert: SlowP99
+           expr: histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) > 1
+           for: 5m
+           labels:
+             severity: warning
+           annotations:
+             summary: "P99 延迟超过 1s"
+   ```
+
+4. **分布式链路追踪（OpenTelemetry）**:
+   **OpenTelemetry 是行业标准 —— 一次接入，多后端支持**
+   
+   ```typescript
+   // 初始化 OTel（Node.js）
+   import { NodeSDK } from '@opentelemetry/sdk-node';
+   import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+   import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+   
+   const sdk = new NodeSDK({
+     traceExporter: new OTLPTraceExporter({
+       url: 'http://otel-collector:4318/v1/traces',
+     }),
+     instrumentations: [
+       getNodeAutoInstrumentations(), // 自动追踪 HTTP/Express/DB
+     ],
+     serviceName: 'order-service',
+   });
+   sdk.start();
+   ```
+   
+   **手动创建 Span（业务关键路径）**
+   
+   ```typescript
+   import { trace } from '@opentelemetry/api';
+   const tracer = trace.getTracer('order-service');
+   
+   async function createOrder(data: OrderData) {
+     return tracer.startActiveSpan('order.create', async (span) => {
+       try {
+         span.setAttributes({
+           'order.user_id': data.userId,
+           'order.item_count': data.items.length,
+           'order.total': data.total,
+         });
+   
+         const order = await db.orders.create(data);
+         span.setStatus({ code: SpanStatusCode.OK });
+         return order;
+       } catch (err) {
+         span.recordException(err as Error);
+         span.setStatus({ code: SpanStatusCode.ERROR });
+         throw err;
+       } finally {
+         span.end();
+       }
+     });
+   }
+   ```
+   
+   **SLO 定义模板**
+   
+   ```yaml
+   SLO: API 可用性
+   SLI: (成功请求数 / 总请求数) * 100%
+   目标: ≥ 99.9% (月度 = 允许 43.8 min 故障)
+   告警: 1h 内错误预算消耗 > 5% 时 PagerDuty 通知
+   ```
+
+**Output**: Markdown 可观测性方案：技术栈选型 + 日志/指标/链路配置代码 + 告警规则 + SLO 定义
+**Notes**: 
+- 可观测性要从项目初期建立，生产出了问题再加往往太晚
+- 日志一定要带 traceId，否则微服务间无法串联请求链路
+- SLO 要与产品/业务方共同制定，不能只是技术侧自说自话
+- 告警要有"降噪"机制（for: 2m），避免毛刺误报打扰团队
+
+### 24. 设计模式 (design_patterns)
+
+**Triggers**: `设计模式`, `design pattern`, `design patterns`, `模式`, `GoF`, `工厂模式`, `单例模式`, `观察者模式`, `策略模式`, `装饰器模式`, `依赖注入`, `代理模式`, `@ethan 设计模式`, `@ethan design-patterns`
+
+**Goal**: 识别适用场景，选择合适的 GoF 设计模式，提升代码可扩展性与可维护性
+
+**Steps**:
+
+1. **三大类模式全景**:
+   **23 种 GoF 模式分类速查**
+   
+   | 类型 | 模式 | 解决的核心问题 |
+   |------|------|--------------|
+   | **创建型** | Factory Method | 子类决定创建哪种对象 |
+   | | Abstract Factory | 创建一族相关对象 |
+   | | Builder | 分步骤构建复杂对象 |
+   | | Singleton | 全局唯一实例 |
+   | | Prototype | 克隆已有对象 |
+   | **结构型** | Adapter | 接口转换，兼容不兼容的接口 |
+   | | Decorator | 动态添加行为（不继承） |
+   | | Facade | 简化复杂子系统的接口 |
+   | | Proxy | 控制对象访问（缓存/权限/懒加载）|
+   | | Composite | 树形结构，统一处理单个和组合 |
+   | **行为型** | Observer | 一对多事件通知 |
+   | | Strategy | 运行时切换算法 |
+   | | Command | 将请求封装为对象（支持撤销）|
+   | | Iterator | 统一遍历集合的方式 |
+   | | State | 状态机，行为随状态变化 |
+   | | Chain of Responsibility | 请求沿链传递，直到被处理 |
+   | | Template Method | 算法骨架固定，子类填充步骤 |
+   
+   **最常用的 5 个（优先掌握）**：Strategy, Observer, Factory, Decorator, Proxy
+
+2. **高频模式 TypeScript 实现**:
+   **策略模式（Strategy）— 取代 if/switch 的最佳武器**
+   
+   ```typescript
+   // 场景：支付方式可扩展
+   interface PaymentStrategy {
+     pay(amount: number): Promise<void>;
+   }
+   
+   class WechatPay implements PaymentStrategy {
+     async pay(amount: number) { /* 微信支付逻辑 */ }
+   }
+   class AlipayStrategy implements PaymentStrategy {
+     async pay(amount: number) { /* 支付宝逻辑 */ }
+   }
+   
+   class PaymentService {
+     constructor(private strategy: PaymentStrategy) {}
+     async checkout(amount: number) {
+       await this.strategy.pay(amount);
+     }
+   }
+   
+   // 运行时切换，新增支付方式不改原有代码
+   const service = new PaymentService(new WechatPay());
+   ```
+   
+   **观察者模式（Observer / EventEmitter）**
+   
+   ```typescript
+   // 场景：订单状态变更通知多个系统
+   class OrderEventEmitter extends EventEmitter {
+     emitOrderCreated(order: Order) {
+       this.emit('order:created', order);
+     }
+   }
+   
+   const emitter = new OrderEventEmitter();
+   emitter.on('order:created', sendConfirmationEmail);
+   emitter.on('order:created', updateInventory);
+   emitter.on('order:created', triggerRecommendation);
+   ```
+   
+   **装饰器模式（Decorator）— 不改原类，添加横切关注点**
+   
+   ```typescript
+   // 场景：为任意服务添加缓存
+   function withCache<T extends object>(service: T, ttlMs = 60_000): T {
+     return new Proxy(service, {
+       get(target, prop) {
+         const original = (target as Record<string, unknown>)[prop as string];
+         if (typeof original !== 'function') return original;
+         const cache = new Map<string, { value: unknown; expiry: number }>();
+         return async (...args: unknown[]) => {
+           const key = JSON.stringify(args);
+           const cached = cache.get(key);
+           if (cached && Date.now() < cached.expiry) return cached.value;
+           const value = await (original as Function).apply(target, args);
+           cache.set(key, { value, expiry: Date.now() + ttlMs });
+           return value;
+         };
+       },
+     });
+   }
+   
+   const cachedUserService = withCache(userService, 30_000);
+   ```
+
+3. **创建型模式实践**:
+   **工厂模式（Factory）— 解耦对象创建与使用**
+   
+   ```typescript
+   // 场景：根据配置创建不同日志处理器
+   interface Logger {
+     log(message: string): void;
+   }
+   
+   class ConsoleLogger implements Logger {
+     log(message: string) { console.log(message); }
+   }
+   class FileLogger implements Logger {
+     log(message: string) { fs.appendFile('app.log', message); }
+   }
+   
+   // 工厂函数（简单场景推荐函数而非类）
+   function createLogger(type: 'console' | 'file'): Logger {
+     if (type === 'file') return new FileLogger();
+     return new ConsoleLogger();
+   }
+   ```
+   
+   **建造者模式（Builder）— 处理复杂对象构造**
+   
+   ```typescript
+   // 场景：SQL 查询构建，参数组合多变
+   class QueryBuilder {
+     private query = { table: '', conditions: [] as string[], limit: 100 };
+   
+     from(table: string) { this.query.table = table; return this; }
+     where(condition: string) { this.query.conditions.push(condition); return this; }
+     limit(n: number) { this.query.limit = n; return this; }
+     build() {
+       const where = this.query.conditions.length
+         ? `WHERE ${this.query.conditions.join(' AND ')}`
+         : '';
+       return `SELECT * FROM ${this.query.table} ${where} LIMIT ${this.query.limit}`;
+     }
+   }
+   
+   // 链式调用，可读性极强
+   const sql = new QueryBuilder()
+     .from('orders')
+     .where('status = "pending"')
+     .where('created_at > NOW() - INTERVAL 7 DAY')
+     .limit(50)
+     .build();
+   ```
+   
+   **单例注意事项**
+   
+   ```typescript
+   // ⚠️ 单例慎用：全局状态 = 隐式耦合
+   // 适用：DB连接池、全局配置、Logger
+   // 不适用：有状态的业务逻辑
+   
+   // Node.js 模块缓存天然单例
+   export const db = createDbPool(); // 模块级单例，足够用
+   ```
+
+4. **模式选型指南与反模式**:
+   **场景 → 模式 速查表**
+   
+   | 遇到这种问题 | 考虑使用 |
+   |------------|---------|
+   | if/switch 随需求不断增长 | Strategy / Command |
+   | 一个变化需要修改多处 | Observer / Mediator |
+   | 需要在运行时给对象加功能 | Decorator / Proxy |
+   | 创建逻辑复杂，参数多 | Factory / Builder |
+   | 需要统一处理树形结构 | Composite |
+   | 需要兼容旧接口/第三方库 | Adapter / Facade |
+   | 请求需要多步验证/处理 | Chain of Responsibility |
+   | 对象行为随状态显著变化 | State |
+   
+   **反模式：过度设计的信号**
+   
+   ```
+   ❌ 为了用设计模式而用设计模式
+   ❌ 一个功能引入 3 层抽象（不超过 2 个接口）
+   ❌ 到处都是 Manager / Handler / Processor 命名
+   ❌ 接口只有一个实现类（YAGNI 原则）
+   
+   ✅ 正确姿势：先写简单代码，当变化来临时再重构引入模式
+   ```
+   
+   **SOLID 原则与模式的关系**
+   
+   | 原则 | 对应常用模式 |
+   |------|------------|
+   | S 单一职责 | Facade, Extract Class |
+   | O 开闭原则 | Strategy, Decorator |
+   | L 里氏替换 | Template Method |
+   | I 接口隔离 | Adapter |
+   | D 依赖倒置 | Factory, DI Container |
+   
+   **输出清单**
+   - [ ] 识别到的模式应用场景（带代码位置）
+   - [ ] 选型理由（为什么选这个模式而不是另一个）
+   - [ ] 实现示例（TypeScript，保持 < 50 行）
+   - [ ] 过度设计风险说明
+
+**Output**: Markdown 设计模式方案：场景分析 + 模式选型理由 + TypeScript 实现示例 + 反模式警示
+**Notes**: 
+- 设计模式是工具，不是目标——代码能跑、能改才是目标
+- TypeScript 的类型系统让很多模式更安全，善用 interface + generic
+- 函数式替代方案通常比类更简洁：Strategy → 高阶函数，Observer → EventEmitter
+- 重构引入模式时，必须有测试覆盖，见 refactoring Skill