القائمة
技术方案：围绕业务目标与约束，输出架构设计、关键模块、技术选型、风险与实施计划的完整技术方案。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
文档创作年度报告：主要借助 `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 模块必须包含：职责边界、接口设计（入参/出参/错误码）、数据模型（表结构/索引）、关键逻辑（状态机/并发控制/幂等设计） |