Menu
技术方案：围绕业务目标与约束，输出架构设计、关键模块、技术选型、风险与实施计划的完整技术方案。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
文档创作年度报告：主要借助 `aily-doc` 获取用户年度文档信息（数量、点赞、评论、PV、UV 等），并基于这些指标与代表性文档产出年度总结型飞书云文档。
商业计划书：强调市场机会、产品与商业模式、竞争、团队、财务与风险，形成可评审BP。
季度/年度业务汇报：围绕指标达成、业务进展、问题与对策输出结构化业务汇报。
公司调研：基于官方与公开信息输出公司概况、业务结构、竞争位置、经营与风险的结构化研究。
竞品分析：通过统一维度对比产品与市场信息，形成结构化对比结论与机会点。
概念解释：由浅入深讲清概念的定义、原理与本质，面向不同知识背景的读者。
| name | aily-doc-technical-solution |
| label | 技术方案 |
| description | 技术方案：围绕业务目标与约束，输出架构设计、关键模块、技术选型、风险与实施计划的完整技术方案。 |
技术方案：围绕业务目标与约束，输出架构设计、关键模块、技术选型、风险与实施计划的完整技术方案。
task（subagent_type: writer）委托 Writer Agent 创建飞书云文档。feishu-use-skills-map 并按其指引调用对应技能get_skills 获取对应飞书技能说明aily-doc 检索，再以外部搜索补充feishu-use-skills-map 并调用对应技能| 工具 | 用途 | 适用场景 |
|---|---|---|
aily-doc | 检索飞书云文档 | PRD、已有技术文档、架构图、评审记录 |
knowledge_answer | 检索内部知识库 | 业务上下文、技术栈信息、历史决策 |
web_search | 广泛检索公开信息 | 技术选型对比、最佳实践、性能基准 |
fetch | 获取特定网页/文档全文 | 官方文档、技术博客、白皮书 |
aily-diagram | 生成流程图/架构图 | 系统架构图、数据流图、时序图 |
file | 将素材写入 draft.md（append 模式） | 每个数据步骤完成后 |
aily-diagram）主 Agent 收到技术方案请求后，使用 todo_write 分解任务：
{
"todos": [
{"content": "需求理解：梳理业务目标、功能需求、非功能需求与约束条件", "status": "in_progress"},
{"content": "现有系统调研：检索内部技术文档、架构图、已有组件能力", "status": "pending"},
{"content": "技术调研：检索架构设计最佳实践、技术选型对比、行业方案", "status": "pending"},
{"content": "性能与规模基准：获取技术组件性能数据、容量规划参考", "status": "pending"},
{"content": "安全与合规调研：检索安全最佳实践、合规要求", "status": "pending"},
{"content": "结构化分析：需求拆解、选型评估、架构设计、风险评估", "status": "pending"},
{"content": "调用 writer agent 生成技术方案文档", "status": "pending"}
]
}
核心原则：飞书工具优先获取内部资料，外部检索补充技术选型与最佳实践。每个步骤产出的关键信息必须写入
draft.md，作为 Writer Agent 的输入素材。
目标：完整理解业务目标、功能边界、非功能要求与约束条件。
aily-doc 检索（通过 get_skills 获取 aily-doc 技能后调用）：
搜索飞书云文档："{项目名称} PRD 需求文档"
搜索飞书云文档："{项目名称} 产品设计 功能规格"
过滤条件：doc_type = "docx"
knowledge_answer 查询：
knowledge_answer(
query_list: [
"{项目名称} 业务背景 目标",
"{项目名称} 功能需求 用户场景",
"{项目名称} 非功能需求 性能 可用性 安全"
],
explanation: "理解业务上下文和需求全貌"
)
写入 draft.md（使用 file(path: "/home/workspace/draft.md", mode: "append")）：
## 需求理解
### 业务背景
- 业务痛点：...
- 项目目标：...
- 关键干系人：...
### 功能需求
| 需求编号 | 需求描述 | 优先级 | 来源 |
|---------|---------|--------|------|
| F-001 | ... | P0 | PRD v2.1 |
| F-002 | ... | P1 | 用户反馈 |
### 非功能需求
- 性能：接口响应 P99 < 200ms，QPS >= 5000
- 可用性：SLA >= 99.95%
- 安全：用户数据加密存储，接口鉴权
- 扩展性：支持未来 3 年 10 倍流量增长
### 约束条件
- 技术栈约束：必须使用公司统一的微服务框架
- 时间约束：需在 Q2 上线
- 人力约束：后端 3 人，前端 2 人
- 预算约束：云资源月预算 XX 万
目标：了解当前系统架构、技术债、可复用组件，避免重复建设。
aily-doc 检索：
搜索飞书云文档："{项目名称} 技术架构 系统设计"
搜索飞书云文档："{项目名称} 架构图 部署图"
搜索飞书云文档："{相关系统} 接口文档 API"
knowledge_answer 查询：
knowledge_answer(
query_list: [
"{项目名称} 当前技术架构 技术栈",
"{项目名称} 已有组件 中间件 基础设施",
"{项目名称} 技术债 已知问题 瓶颈"
],
explanation: "了解现有系统现状和可复用资产"
)
写入 draft.md（使用 file(path: "/home/workspace/draft.md", mode: "append")）：
## 现有系统调研
### 当前架构概述
- 架构模式：单体/微服务/...
- 核心技术栈：语言、框架、数据库、中间件
- 部署方式：容器化/物理机/...
### 可复用组件
| 组件 | 能力 | 负责团队 | 是否可直接复用 |
|------|------|---------|--------------|
| 用户中心 | 登录/鉴权/权限 | 平台团队 | 是 |
| 消息服务 | 推送/站内信/邮件 | 基础架构 | 是，需对接 |
| 数据平台 | 埋点/分析/报表 | 数据团队 | 部分复用 |
### 已知问题与技术债
- 数据库单点：MySQL 主库无读写分离，高峰期慢查询多
- 缓存穿透：部分接口未做缓存降级
- 监控缺失：核心链路缺少全链路追踪
### 现有接口依赖
- 上游：订单服务（gRPC）、用户服务（HTTP）
- 下游：推荐服务（Kafka）、搜索服务（HTTP）
目标：调研行业最佳实践、架构模式和候选技术方案，为选型决策提供依据。
web_search 查询（多角度）：
- "{技术场景} 架构设计 最佳实践 2024 2025"
- "{技术A} vs {技术B} 对比 选型"
- "{业务场景} 技术方案 大厂实践"
- "{技术场景} system design architecture"
- "{中间件} 生产环境 踩坑 经验"
fetch 深度阅读：
fetch(
url: "https://tech-blog.example.com/architecture-xxx",
prompt: "提取该技术方案的架构设计、技术选型理由、性能数据、踩坑经验"
)
典型调研方向：
写入 draft.md（使用 file(path: "/home/workspace/draft.md", mode: "append")）：
## 技术调研
### 架构模式调研
- 方案一（微服务 + 事件驱动）：适用于高并发场景，参考 {公司A} 实践...
- 方案二（模块化单体）：初期快速迭代，参考 {公司B} 实践...
- 方案三（Serverless + BaaS）：适用于流量波动大的场景...
### 关键技术对比
| 维度 | 技术A | 技术B | 技术C |
|------|-------|-------|-------|
| 性能 | ... | ... | ... |
| 生态 | ... | ... | ... |
| 运维成本 | ... | ... | ... |
| 团队熟悉度 | ... | ... | ... |
| 社区活跃度 | ... | ... | ... |
### 行业参考案例
- {公司A}：采用 XX 架构解决 YY 问题，QPS 达到 ZZ（来源：技术博客，2024）
- {公司B}：从 XX 迁移到 YY，延迟降低 40%（来源：InfoQ，2024）
目标：获取候选技术组件的性能基准数据，为容量规划和性能目标设定提供依据。
web_search 查询：
- "{技术组件} benchmark 性能测试 QPS 延迟"
- "{技术组件} 大规模 生产环境 性能优化"
- "{业务场景} 容量规划 capacity planning"
- "{数据库} 单表 亿级 性能 分库分表"
- "{缓存} 集群 内存优化 淘汰策略"
fetch 深度阅读（官方性能报告、第三方评测）：
fetch(
url: "https://xxx.io/benchmark-report",
prompt: "提取性能测试结果：QPS、延迟分布（P50/P99/P999）、资源消耗、测试条件"
)
写入 draft.md（使用 file(path: "/home/workspace/draft.md", mode: "append")）：
## 性能与规模基准
### 基准测试数据
| 组件 | 场景 | QPS | P99 延迟 | 资源配置 | 来源 |
|------|------|-----|---------|---------|------|
| MySQL 8.0 | OLTP 读写混合 | 15,000 | 8ms | 8C16G SSD | Sysbench, 官方文档 |
| Redis 7.0 | GET/SET | 100,000+ | 1ms | 8C16G | redis-benchmark |
| Kafka 3.x | 消息生产 | 200,000 msg/s | 5ms | 3 Broker 8C16G | 官方 benchmark |
### 容量估算参考
- 日活用户：XX 万 -> 峰值 QPS 估算：XX（按 20% 集中在 2 小时算）
- 数据增长：日增 XX 万条 -> 年增 XX GB -> 3 年 XX TB
- 存储选型：单表超过 5000 万行需分表，超过 500GB 需分库
### 性能风险点
- 写放大：消息 Fanout 场景，1 条消息扩散为 N 条推送
- 热点数据：Top 1% 的 Key 占 80% 的读请求
- 慢查询：复杂聚合查询可能导致锁表
目标：确认安全要求和合规约束，确保技术方案满足安全基线。
web_search 查询：
- "{业务场景} 安全 最佳实践 OWASP"
- "{技术栈} 安全加固 配置"
- "{行业} 合规要求 等保 数据安全"
- "API 安全 鉴权 限流 防护"
- "{数据类型} 加密 脱敏 隐私保护"
knowledge_answer 查询：
knowledge_answer(
query_list: [
"公司安全规范 安全基线要求",
"数据分类分级 敏感数据处理规范",
"服务上线安全审核 checklist"
],
explanation: "确认内部安全合规要求"
)
写入 draft.md（使用 file(path: "/home/workspace/draft.md", mode: "append")）：
## 安全与合规
### 安全要求
- 认证鉴权：OAuth 2.0 + JWT，Token 有效期 2 小时
- 数据加密：传输层 TLS 1.3，存储层 AES-256 加密敏感字段
- 接口防护：限流（令牌桶算法）、防重放（Nonce + Timestamp）、SQL 注入防护
- 审计日志：所有写操作记录操作人、时间、IP、变更内容
### 合规要求
- 等保要求：三级等保（如适用）
- 数据合规：个人信息收集需用户授权，数据存储不出境
- 行业规范：{行业相关的特殊要求}
### 安全架构参考
- 网关层：WAF + API Gateway 统一鉴权
- 服务层：服务间 mTLS，最小权限原则
- 数据层：敏感数据加密存储，日志脱敏
核心原则：基于 Module A 收集的素材，进行系统性分析，形成可落地的技术决策。分析结果写入
draft.md，作为方案正文的核心内容。
将收集到的需求按功能域拆解，明确优先级和依赖关系：
## 需求拆解
### 功能域划分
| 功能域 | 核心需求 | 优先级 | 依赖关系 | 预估工作量 |
|--------|---------|--------|---------|-----------|
| 用户管理 | 注册/登录/权限 | P0 | 无 | 5 人日 |
| 核心业务 | {核心功能描述} | P0 | 用户管理 | 15 人日 |
| 数据分析 | 报表/Dashboard | P1 | 核心业务 | 8 人日 |
| 消息通知 | 站内信/推送 | P2 | 用户管理 | 3 人日 |
### 需求优先级矩阵
- **P0（必须）**：影响核心业务流程，上线前必须完成
- **P1（重要）**：提升用户体验或运营效率，可分期交付
- **P2（期望）**：锦上添花，资源充足时实现
对每个关键技术决策点，建立多维度评估矩阵：
## 技术选型评估
### 数据库选型
| 评估维度 | MySQL 8.0 | PostgreSQL 15 | TiDB 7.x | 权重 |
|---------|-----------|---------------|-----------|------|
| 性能（OLTP） | 优 | 优 | 良 | 25% |
| 水平扩展 | 差（需分库分表） | 差（需 Citus） | 优（原生分布式） | 20% |
| 运维成本 | 低（团队熟悉） | 中 | 高（需专人） | 20% |
| 生态兼容性 | 优（ORM 全兼容） | 优 | 良（MySQL 协议兼容） | 15% |
| 团队经验 | 丰富 | 少量 | 无 | 15% |
| 许可与成本 | 开源免费 | 开源免费 | 开源/商业版 | 5% |
| **综合得分** | **85** | **72** | **68** | — |
**结论**：选择 MySQL 8.0，理由：团队熟悉度高，运维成本低，当前数据规模无需分布式数据库。预留 TiDB 迁移方案，当单表超过 1 亿行时启动评估。
### 消息队列选型
| 评估维度 | Kafka 3.x | RocketMQ 5.x | Pulsar 3.x | 权重 |
|---------|-----------|--------------|------------|------|
| 吞吐量 | 优（百万级/s） | 良（十万级/s） | 优（百万级/s） | 25% |
| 延迟 | 中（毫秒级） | 优（毫秒级） | 良（毫秒级） | 20% |
| 消息可靠性 | 优 | 优 | 优 | 20% |
| 运维复杂度 | 中 | 低 | 高 | 15% |
| 团队经验 | 丰富 | 少量 | 无 | 15% |
| 功能丰富度 | 良 | 优（延迟消息/事务消息） | 优 | 5% |
| **综合得分** | **82** | **78** | **65** | — |
**结论**：选择 Kafka，理由：吞吐量满足要求，团队运维经验丰富，与现有数据平台生态一致。
明确本方案遵循的设计原则，作为后续模块设计的指导：
## 架构设计原则
1. **高内聚低耦合**：服务按业务域拆分，服务间通过明确接口通信，避免数据库直连
2. **渐进式演进**：初期采用模块化单体，业务验证后按需拆分微服务，避免过度设计
3. **故障隔离**：核心链路与非核心链路隔离，非核心服务故障不影响主流程
4. **数据驱动**：关键路径全链路埋点，通过数据验证设计假设
5. **安全内建**：安全不是事后补丁，在架构层面内建认证、鉴权、加密、审计能力
6. **可观测性**：日志、指标、链路追踪三位一体，问题可定位、性能可度量
对核心模块进行详细设计，包括职责、接口、数据模型和关键逻辑：
## 关键模块设计
### 模块划分
- 根据功能域划分和依赖关系，确定模块边界
- 每个模块明确：职责范围、对外接口、数据模型、关键算法/逻辑
### 设计要素（每个模块）
1. **职责**：该模块负责什么，不负责什么（明确边界）
2. **接口设计**：入参、出参、错误码、幂等性
3. **数据模型**：核心表结构、索引设计、数据生命周期
4. **关键逻辑**：核心算法、状态机、并发控制策略
5. **依赖关系**：上下游依赖、降级策略
基于需求和基准数据，进行系统性的容量估算：
## 性能与容量估算
### 流量模型
- 日活用户（DAU）：XX 万
- 人均请求数：XX 次/天
- 日请求总量：XX 万次
- 峰值系数：3-5 倍（根据业务特征）
- 峰值 QPS：XX
### 资源估算
| 服务 | 实例数 | 单实例配置 | 峰值 CPU | 峰值内存 | 月成本 |
|------|--------|-----------|---------|---------|--------|
| API 网关 | 3 | 4C8G | 60% | 50% | XX 元 |
| 业务服务 | 6 | 4C8G | 70% | 60% | XX 元 |
| MySQL | 1主2从 | 8C32G 500G SSD | 40% | 60% | XX 元 |
| Redis | 3节点集群 | 4C16G | 30% | 70% | XX 元 |
| Kafka | 3 Broker | 4C8G 1T | 50% | 40% | XX 元 |
### 扩展预案
- 短期（3个月）：当前配置可支撑 2 倍流量
- 中期（1年）：水平扩容业务服务至 12 实例，MySQL 读写分离
- 长期（3年）：评估分库分表或迁移分布式数据库
系统性识别技术风险，制定降级预案：
## 风险评估
### 风险清单
| 风险 | 概率 | 影响 | 降级方案 | 负责人 |
|------|------|------|---------|--------|
| 数据库主库宕机 | 低 | 严重 | 自动主从切换，30s 内恢复 | DBA |
| 缓存雪崩 | 中 | 严重 | 多级缓存 + 限流 + 本地缓存兜底 | 后端 |
| 第三方接口超时 | 高 | 中 | 熔断降级，返回缓存数据或默认值 | 后端 |
| 消息积压 | 中 | 中 | 动态扩容消费者 + 监控告警 | SRE |
| 数据不一致 | 中 | 严重 | 对账任务 + 补偿机制 | 后端 |
### 降级层级
- **L1（自动降级）**：熔断器自动触发，无需人工介入
- **L2（预案降级）**：通过配置中心一键切换降级开关
- **L3（人工介入）**：需要运维/开发人员手动处理
主 Agent 完成数据收集和结构化分析后，调用 task 工具分发给 Writer Agent：
{
"description": "生成技术方案飞书云文档",
"prompt": "基于 /home/workspace/draft.md 中的技术方案素材，生成一份结构完整的飞书云文档技术方案。\n\n要求：\n1. 严格按照技术方案文档模板结构\n2. 方案摘要（TL;DR）放在最前面，3-5 条核心设计决策\n3. 技术选型必须有评估矩阵和明确结论\n4. 性能数据标注测试条件和来源\n5. 风险清单完整，每条风险有降级方案\n6. 架构图使用 aily-diagram 生成\n7. 接口定义使用代码块\n\n文档模板见下方。",
"subagent_type": "writer"
}
Writer Agent 接收任务
↓
1. file_read: 读取 /home/workspace/draft.md
↓
2. outline_generator: 基于素材和模板生成结构化大纲
- 输入：draft.md 内容 + 技术方案模板
- 输出：带层级的大纲结构
↓
3. feishu_doc_create: 按大纲生成飞书云文档
- 逐章节填充内容
- 插入表格（选型矩阵、风险清单、排期表等）
- 调用 aily-diagram 生成架构图并嵌入
- 代码块格式化接口定义和数据模型
↓
4. end: 返回飞书文档链接
# {方案名称} 技术方案
> 版本: v1.0 | 作者: @XX | 日期: YYYY-MM-DD
> 状态: 待评审
---
## 方案摘要（TL;DR）
> 用 3-5 条核心设计决策概括整个方案，便于评审人快速了解全貌。
1. **架构选择**：采用 XX 架构，原因是...
2. **核心技术栈**：XX + YY + ZZ，选择依据是...
3. **性能目标**：QPS XX，P99 延迟 < XX ms
4. **关键风险**：XX 风险最高，降级方案为...
5. **预计排期**：共 XX 周，分 N 期交付
---
## 一、背景与目标
### 1.1 业务背景
描述业务场景、痛点和发起技术方案的原因。
### 1.2 技术目标
明确本方案要实现的技术目标，与业务目标对齐。
### 1.3 成功标准
| 维度 | 指标 | 目标值 | 度量方式 |
|------|------|--------|---------|
| 性能 | 接口 P99 延迟 | < 200ms | APM 监控 |
| 可用性 | 服务可用率 | >= 99.95% | SLA 报表 |
| 吞吐 | 峰值 QPS | >= 5000 | 压测报告 |
| 质量 | 线上 Bug 率 | < 0.1% | 缺陷追踪 |
---
## 二、需求与约束
### 2.1 功能需求
| 需求编号 | 需求描述 | 优先级 | 说明 |
|---------|---------|--------|------|
| F-001 | 用户注册与登录 | P0 | 支持手机号/邮箱/第三方登录 |
| F-002 | 核心业务流程 | P0 | {具体描述} |
| F-003 | 数据导出 | P1 | 支持 CSV/Excel 格式 |
### 2.2 非功能需求
- **性能**：核心接口 P99 < 200ms，QPS >= 5000
- **可用性**：SLA >= 99.95%，单机故障自动恢复
- **安全**：数据加密传输与存储，接口鉴权，操作审计
- **扩展性**：支持水平扩容，3 年内无需大规模重构
- **可维护性**：核心模块单元测试覆盖率 >= 80%
### 2.3 约束条件
- 技术栈：必须使用公司 XX 微服务框架
- 时间：Q2 结束前上线 MVP
- 人力：后端 3 人，前端 2 人，测试 1 人
- 预算：月度云资源预算 XX 万元
- 兼容性：需兼容现有 XX 系统的 API 协议
---
## 三、总体架构
### 3.1 架构图
> 使用 aily-diagram 生成系统架构图，或用文字描述架构全貌。
架构概述：
- 接入层：API Gateway（统一鉴权、限流、路由）
- 业务层：按功能域拆分的业务服务集群
- 数据层：MySQL（主数据）+ Redis（缓存）+ Kafka（异步消息）+ ES（搜索）
- 基础设施层：Kubernetes + 服务注册发现 + 配置中心 + 监控告警
### 3.2 核心组件说明
| 组件 | 职责 | 技术选型 | 部署方式 |
|------|------|---------|---------|
| API Gateway | 统一入口、鉴权、限流 | Kong/Nginx | K8s Deployment |
| 业务服务A | {核心业务逻辑} | Go + gRPC | K8s Deployment |
| 业务服务B | {辅助业务逻辑} | Go + gRPC | K8s Deployment |
| MySQL | 持久化存储 | MySQL 8.0 | 主从集群 |
| Redis | 缓存 + 分布式锁 | Redis 7.0 Cluster | 3 主 3 从 |
| Kafka | 异步消息 | Kafka 3.x | 3 Broker 集群 |
### 3.3 数据流
描述核心业务场景下的数据流转路径：
1. 用户请求 -> API Gateway -> 鉴权通过 -> 路由到业务服务
2. 业务服务 -> 查 Redis 缓存 -> 未命中 -> 查 MySQL -> 写回缓存 -> 返回
3. 写操作 -> 业务服务 -> 写 MySQL -> 发 Kafka 消息 -> 消费者更新缓存/搜索索引
---
## 四、关键模块设计
### 4.1 模块A: {名称}
#### 职责
- 负责 XX 功能的核心逻辑
- 不负责 YY（由模块B处理）
#### 接口设计
POST /api/v1/resource Request: { "field_a": "string, 必填, 描述", "field_b": 123, // 可选, 默认值 }
Response: { "code": 0, "message": "success", "data": { "id": "string", "created_at": "2024-01-01T00:00:00Z" } }
错误码:
#### 数据模型
表名: t_resource +------------+--------------+------+-----+-------------------+ | 字段 | 类型 | 必填 | 索引 | 说明 | +------------+--------------+------+-----+-------------------+ | id | BIGINT | 是 | PK | 自增主键 | | biz_id | VARCHAR(64) | 是 | UNI | 业务唯一标识 | | user_id | BIGINT | 是 | IDX | 用户ID | | status | TINYINT | 是 | IDX | 状态: 0-草稿 1-生效 | | content | TEXT | 否 | | 内容 | | created_at | DATETIME | 是 | IDX | 创建时间 | | updated_at | DATETIME | 是 | | 更新时间 | +------------+--------------+------+-----+-------------------+
#### 关键逻辑
- 并发控制：使用 Redis 分布式锁，锁粒度为 user_id
- 状态机：草稿 -> 审核中 -> 已生效 -> 已过期
- 幂等设计：基于 biz_id 做幂等校验
### 4.2 模块B: {名称}
（同上格式，按需展开）
---
## 五、技术选型
### 5.1 选型决策
| 决策点 | 方案A | 方案B | 方案C | 结论 |
|--------|-------|-------|-------|------|
| 数据库 | MySQL 8.0 | PostgreSQL 15 | TiDB | MySQL 8.0 |
| 缓存 | Redis Cluster | Codis | Memcached | Redis Cluster |
| 消息队列 | Kafka | RocketMQ | Pulsar | Kafka |
| 服务框架 | Go-Micro | gRPC + 自研 | Kitex | Kitex |
| 搜索引擎 | Elasticsearch | Meilisearch | — | Elasticsearch |
### 5.2 选型理由
#### 数据库: MySQL 8.0
- **选择原因**：团队深度使用 3 年以上，运维体系成熟，DBA 团队有丰富经验
- **放弃 PostgreSQL 的原因**：团队无生产环境使用经验，迁移学习成本高
- **放弃 TiDB 的原因**：当前数据规模不需要分布式数据库，运维复杂度高
- **迁移预案**：当单表数据量超过 1 亿行时，评估分库分表或迁移 TiDB
#### 缓存: Redis Cluster
- **选择原因**：原生集群模式，支持自动分片和故障转移，数据结构丰富
- **放弃 Memcached 的原因**：不支持持久化，数据结构单一
#### 消息队列: Kafka
- **选择原因**：高吞吐量满足需求，与公司数据平台生态一致，团队经验丰富
- **放弃 RocketMQ 的原因**：虽然延迟更低，但团队无运维经验
---
## 六、性能与容量
### 6.1 性能估算
| 场景 | 预估 QPS | P99 目标 | 资源预估 |
|------|---------|---------|---------|
| 核心查询 | 3,000 | < 100ms | 4 实例 4C8G |
| 核心写入 | 500 | < 200ms | 4 实例 4C8G |
| 搜索查询 | 1,000 | < 300ms | 3 节点 ES |
| 消息消费 | 2,000 msg/s | < 500ms | 6 Consumer |
### 6.2 容量规划
| 资源 | 当前需求 | 6 个月 | 1 年 | 3 年 |
|------|---------|--------|------|------|
| 计算节点 | 8 实例 | 12 实例 | 16 实例 | 32 实例 |
| MySQL 存储 | 100GB | 300GB | 500GB | 2TB |
| Redis 内存 | 16GB | 32GB | 48GB | 96GB |
| Kafka 存储 | 200GB | 500GB | 1TB | 3TB |
| 月度成本 | XX 万 | XX 万 | XX 万 | XX 万 |
### 6.3 压测方案
- **压测工具**：wrk / k6 / JMeter
- **压测环境**：独立压测集群，配置与生产等比缩放
- **压测场景**：
1. 单接口性能基线测试
2. 混合场景（读写比 8:2）压测
3. 峰值流量（3 倍日常）持续 30 分钟
4. 故障注入（杀节点、网络延迟）下的性能表现
- **通过标准**：P99 达标 + 错误率 < 0.1% + 无 OOM / 无长时间 GC
---
## 七、安全与合规
- **认证鉴权**：API Gateway 统一鉴权，OAuth 2.0 + JWT
- **数据安全**：敏感数据（手机号、身份证号等）加密存储，日志自动脱敏
- **传输安全**：全链路 TLS 1.3，服务间 mTLS
- **接口防护**：限流（令牌桶）、防重放、CSRF 防护、XSS 过滤
- **审计日志**：所有写操作记录审计日志，保留 90 天
- **合规**：满足公司安全基线要求，上线前通过安全审核
---
## 八、风险与降级
### 8.1 风险清单
| 风险 | 概率 | 影响 | 降级方案 | 监控指标 |
|------|------|------|---------|---------|
| 数据库主库故障 | 低 | 严重 | 自动主从切换，RTO < 30s | 主从延迟、连接数 |
| 缓存雪崩 | 中 | 严重 | 多级缓存 + 限流 + 本地缓存 | 缓存命中率、QPS |
| 第三方服务不可用 | 高 | 中 | 熔断降级，返回缓存数据 | 调用成功率、延迟 |
| Kafka 消息积压 | 中 | 中 | 动态扩消费者 + 告警 | 消费 Lag |
| 数据不一致 | 中 | 严重 | 对账任务 + 补偿机制 | 对账差异数 |
| 流量突增超预期 | 低 | 严重 | 自动扩容 + 限流降级 | QPS、CPU |
### 8.2 灰度策略
- **灰度维度**：按用户 ID 尾号/地域/渠道分组
- **灰度阶段**：
1. 内部测试（全员）-> 1%用户 -> 10%用户 -> 50%用户 -> 全量
2. 每个阶段至少观察 24 小时
3. 核心指标无异常后推进下一阶段
- **回滚条件**：错误率 > 1% 或 P99 > 500ms 自动回滚
---
## 九、实施计划
### 9.1 开发排期
| 阶段 | 时间 | 交付物 | 里程碑 |
|------|------|--------|--------|
| 技术方案评审 | 第 1 周 | 方案文档终稿 | 评审通过 |
| 基础框架搭建 | 第 2-3 周 | 项目骨架 + CI/CD | 可运行空服务 |
| 核心模块开发 | 第 4-7 周 | 核心业务功能 | 功能可联调 |
| 联调与集成测试 | 第 8-9 周 | 集成测试报告 | 主流程跑通 |
| 性能测试与优化 | 第 10 周 | 压测报告 | 性能达标 |
| 安全审核与灰度 | 第 11-12 周 | 安全审核报告 | 全量上线 |
### 9.2 测试策略
- **单元测试**：核心模块覆盖率 >= 80%，提交时自动运行
- **集成测试**：核心链路端到端覆盖，每日自动回归
- **性能测试**：上线前压测，达到 2 倍预期峰值流量
- **安全测试**：上线前安全扫描，修复所有高危漏洞
- **灰度验证**：按灰度策略逐步放量，观察核心指标
### 9.3 上线 Checklist
- [ ] 技术方案评审通过
- [ ] 核心模块代码 Review 完成
- [ ] 单元测试覆盖率达标
- [ ] 集成测试全部通过
- [ ] 压测报告：性能达标
- [ ] 安全审核通过
- [ ] 监控告警配置完成
- [ ] 灰度方案准备就绪
- [ ] 回滚方案验证通过
- [ ] 运维文档/Runbook 编写完成
---
## 十、监控与运维
- **指标监控**：QPS、延迟（P50/P99/P999）、错误率、CPU/内存/磁盘
- **日志监控**：ERROR 日志实时告警，核心链路日志全量采集
- **链路追踪**：OpenTelemetry 全链路追踪，支持请求级别排查
- **告警规则**：
- 错误率 > 0.5%：P1 告警，自动通知值班人
- P99 > 500ms：P2 告警，通知负责人
- 服务不可用：P0 告警，电话通知 + 自动拉群
- **Runbook**：常见故障处理手册，降低 MTTR
---
## 附录
### A. 接口定义
完整接口列表及详细定义（OpenAPI/Swagger 格式）
### B. 数据模型
完整数据库 ER 图及表结构定义
### C. 术语表
| 术语 | 说明 |
|------|------|
| QPS | 每秒查询数 |
| P99 | 99% 请求的响应时间上界 |
| SLA | 服务级别协议 |
| MTTR | 平均故障恢复时间 |
| RTO | 恢复时间目标 |
| RPO | 恢复点目标 |
用户: "帮我写一份 XX 技术方案"
↓
┌─────────────────────────────────────────────────────────────┐
│ 主 Agent 执行 │
├─────────────────────────────────────────────────────────────┤
│ 1. todo_write: 分解任务（7 个子任务） │
│ │
│ 【A1. 需求理解】 │
│ 2. aily-doc: 搜索 PRD / 需求文档 │
│ 3. knowledge_answer: 查业务上下文、历史决策 │
│ → 写入 draft.md: 需求理解章节 │
│ │
│ 【A2. 现有系统调研】 │
│ 4. aily-doc: 搜索现有技术文档 / 架构图 │
│ 5. knowledge_answer: 查技术栈、可复用组件 │
│ → 写入 draft.md: 现有系统章节 │
│ │
│ 【A3. 技术调研】 │
│ 6. web_search: "{技术} 架构设计 最佳实践" │
│ 7. web_search: "{技术A} vs {技术B} 对比" │
│ 8. fetch: 技术博客 / 官方文档深度阅读 │
│ → 写入 draft.md: 技术调研章节 │
│ │
│ 【A4. 性能与规模基准】 │
│ 9. web_search: "{技术} benchmark 性能测试 QPS" │
│ 10. web_search: "{场景} 容量规划" │
│ 11. fetch: 性能报告 / 评测文章 │
│ → 写入 draft.md: 性能基准章节 │
│ │
│ 【A5. 安全与合规】 │
│ 12. web_search: "{技术} 安全 合规 最佳实践" │
│ 13. knowledge_answer: 内部安全规范 │
│ → 写入 draft.md: 安全合规章节 │
│ │
│ 【B. 结构化分析】 │
│ 14. 需求拆解与优先级 → draft.md │
│ 15. 技术选型评估矩阵 → draft.md │
│ 16. 架构设计 + 模块设计 → draft.md │
│ 17. 性能估算 + 容量规划 → draft.md │
│ 18. 风险评估 + 降级方案 → draft.md │
│ │
│ 19. task(writer): 分发写作任务 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Writer Agent 执行 │
├─────────────────────────────────────────────────────────────┤
│ 1. file_read: 读取 /home/workspace/draft.md │
│ 2. outline_generator: 基于素材 + 模板生成大纲 │
│ - 按"摘要-背景-需求-架构-模块-选型-性能-安全-风险-计划" │
│ 3. feishu_doc_create: 逐章节生成飞书云文档 │
│ - 插入表格（选型矩阵、风险清单、排期表） │
│ - 调用 aily-diagram 生成架构图 │
│ - 代码块格式化接口定义和数据模型 │
│ 4. end: 返回飞书文档链接 │
└─────────────────────────────────────────────────────────────┘
↓
飞书云文档技术方案（可直接用于技术评审）
| 失败模式 | 典型表现 | 根本原因 | 修复方法 |
|---|---|---|---|
| 需求理解偏差 | 方案设计的功能与实际需求不匹配，评审时被挑战"为什么做这个" | 未充分检索 PRD 和需求文档，仅凭用户口头描述就开始设计 | 强制执行 A1 步骤：先用 aily-doc 搜索 PRD，用 knowledge_answer 查业务上下文，需求清单必须与 PRD 逐条对齐 |
| 技术选型无依据 | 选型结论只有"选 XX"，没有对比过程，评审人问"为什么不用 YY"时无法回答 | 跳过了选型评估矩阵，直接凭经验或偏好选择 | 强制执行 B2 步骤：每个关键选型必须有至少 2 个候选方案的多维度对比矩阵，明确写出放弃其他方案的理由 |
| 缺少性能估算 | 方案中没有 QPS 目标、容量规划和资源预估，上线后才发现扛不住流量 | 未做流量建模，未查性能基准数据 | 强制执行 A4 和 B5 步骤：必须有流量模型（DAU -> QPS）、基准测试数据（标注来源）、资源估算表和扩展预案 |
| 风险遗漏 | 上线后出现数据库宕机、缓存雪崩等问题，方案中完全没有提及 | 只关注"正常流程"设计，未系统性思考异常场景 | 强制执行 B6 步骤：风险清单至少 5 项，每项必须有概率评估、影响评估和降级方案；评审前逐条过降级预案 |
| 方案过于理想化 | 架构设计追求"完美"，引入大量高级组件（Service Mesh、分布式事务、多级缓存），但团队只有 3 个人 | 脱离团队能力和资源约束，过度设计 | 在 B3 架构原则中加入"渐进式演进"原则；选型矩阵中"团队经验"和"运维成本"权重不低于 15%；排期是否与人力匹配需交叉验证 |
| 模块设计粗糙 | 模块只有名称和一句话描述，没有接口定义、数据模型和关键逻辑，开发人员无法据此编码 | Module B4 执行不充分，模块设计只停留在架构图层面 | 强制每个 P0 模块必须包含：职责边界、接口设计（入参/出参/错误码）、数据模型（表结构/索引）、关键逻辑（状态机/并发控制/幂等设计） |