@umacloud/knowledge 1.0.1

package/architecture/03-checklists/architecture-decision-checklist.md

@@ -0,0 +1,297 @@
+---
+id: architecture-decision-checklist
+title: 架构决策检查清单
+domain: architecture
+category: 03-checklists
+difficulty: intermediate
+tags: [architecture, checklist, decision, 可扩展性, 可用性, 可观测性, 安全, 成本]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 架构决策检查清单
+
+> 适用场景：新系统设计、重大技术选型、架构评审会议、ADR 编写前的全面评估。
+> 使用方式：逐项核查，标记完成状态，未通过项必须附带理由或待办。
+
+---
+
+## 1. 需求分析
+
+### 1.1 功能需求
+
+- [ ] 核心业务场景已梳理并按优先级排序（P0/P1/P2）
+- [ ] 用户角色与权限模型已定义
+- [ ] 关键业务流程已绘制流程图或时序图
+- [ ] 数据实体与关系已建模（ER 图或领域模型）
+- [ ] 接口边界已明确（对外 API、对内服务间调用）
+- [ ] 离线/批处理需求已识别
+- [ ] 多租户需求已评估（是否需要、隔离级别）
+- [ ] 国际化/本地化需求已确认（语言、时区、货币）
+
+### 1.2 非功能需求
+
+- [ ] 性能目标已量化（QPS、响应时间 P50/P95/P99）
+- [ ] 可用性目标已量化（SLA 百分比，如 99.9%、99.99%）
+- [ ] 数据一致性要求已明确（强一致/最终一致）
+- [ ] 数据量预估已完成（初始量、增长率、峰值）
+- [ ] 并发用户数预估已完成（日常/峰值）
+- [ ] 数据保留策略已定义（热/温/冷数据周期）
+- [ ] 合规要求已识别（GDPR、等保、行业法规）
+- [ ] 灾备等级已确定（RPO/RTO 目标值）
+
+### 1.3 约束条件
+
+- [ ] 现有技术栈约束已列出
+- [ ] 团队技术能力已评估（熟悉的语言/框架/工具）
+- [ ] 预算约束已明确（基础设施、许可证、第三方服务）
+- [ ] 上线时间约束已确认
+- [ ] 合规与审计约束已确认
+- [ ] 组织架构约束已考虑（团队规模、协作模式）
+- [ ] 遗留系统集成约束已识别
+- [ ] 供应商锁定风险已评估
+
+---
+
+## 2. 技术选型
+
+### 2.1 编程语言与运行时
+
+- [ ] 候选语言已列出并对比（性能/生态/招聘难度）
+- [ ] 语言版本与 LTS 策略已确认
+- [ ] 运行时环境已确定（JVM/Node/Python/Go 等）
+- [ ] 跨语言通信方案已确定（gRPC/REST/消息队列）
+- [ ] 构建工具链已选定
+
+### 2.2 框架与库
+
+- [ ] Web 框架已选定并评估（成熟度/社区/性能）
+- [ ] ORM / 数据访问层方案已确定
+- [ ] 依赖管理策略已制定（版本锁定/安全扫描）
+- [ ] 框架升级路径已评估（大版本兼容性）
+- [ ] 开源许可证合规已检查
+
+### 2.3 数据库
+
+- [ ] 主数据库类型已选定（关系型/文档/键值/图/时序）
+- [ ] 读写分离方案已评估
+- [ ] 分库分表策略已评估（是否需要、分片键选择）
+- [ ] 数据库版本与部署模式已确定（自建/托管/Serverless）
+- [ ] 数据迁移方案已规划
+- [ ] 备份与恢复策略已制定
+- [ ] 索引设计原则已确定
+
+### 2.4 消息队列
+
+- [ ] 是否需要消息队列已评估
+- [ ] 消息队列产品已选定（Kafka/RabbitMQ/RocketMQ/Pulsar/NATS）
+- [ ] 消息投递语义已确定（at-least-once/at-most-once/exactly-once）
+- [ ] 消息顺序性要求已评估
+- [ ] 死信队列/重试策略已设计
+- [ ] 消息积压监控方案已规划
+- [ ] 消息 schema 管理方案已确定
+
+### 2.5 缓存
+
+- [ ] 缓存层级已设计（本地缓存/分布式缓存/CDN）
+- [ ] 缓存产品已选定（Redis/Memcached/本地 LRU）
+- [ ] 缓存策略已确定（Cache-Aside/Read-Through/Write-Behind）
+- [ ] 缓存失效策略已设计（TTL/事件驱动/版本号）
+- [ ] 缓存穿透/击穿/雪崩防护已设计
+- [ ] 缓存一致性方案已确定
+- [ ] 缓存容量预估已完成
+
+---
+
+## 3. 可扩展性
+
+### 3.1 水平扩展
+
+- [ ] 无状态服务设计已确认（Session 外置）
+- [ ] 服务发现机制已确定
+- [ ] 负载均衡策略已选定（轮询/权重/一致性哈希）
+- [ ] 自动扩缩容规则已设计（CPU/内存/QPS 阈值）
+- [ ] 数据库连接池在扩展时的行为已验证
+- [ ] 有状态组件的水平扩展方案已明确
+
+### 3.2 垂直扩展
+
+- [ ] 单节点性能瓶颈已预估
+- [ ] 资源规格上限已了解（云厂商实例上限）
+- [ ] 垂直扩展成本曲线已评估
+- [ ] 垂直扩展时的停机影响已评估
+
+### 3.3 数据分片
+
+- [ ] 分片策略已确定（范围/哈希/混合）
+- [ ] 分片键选择已论证（数据分布均匀性、查询模式）
+- [ ] 跨分片查询方案已设计
+- [ ] 分片扩容方案已规划（在线扩容/停机迁移）
+- [ ] 全局唯一 ID 生成方案已确定
+- [ ] 跨分片事务处理方案已设计
+
+---
+
+## 4. 可用性
+
+### 4.1 SLA 定义
+
+- [ ] 整体 SLA 目标已定义（如 99.95%）
+- [ ] 各子系统 SLA 已分解
+- [ ] SLA 计算方式已明确（时间窗口/排除维护窗口）
+- [ ] SLA 违约的响应流程已建立
+- [ ] 依赖方 SLA 已确认并纳入计算
+
+### 4.2 冗余设计
+
+- [ ] 服务实例冗余数量已确定（最少 2 副本）
+- [ ] 数据库主从/多副本已配置
+- [ ] 缓存集群冗余已设计
+- [ ] 消息队列集群冗余已设计
+- [ ] 跨可用区部署已评估
+- [ ] 跨区域部署已评估（多活/灾备）
+
+### 4.3 故障转移
+
+- [ ] 健康检查机制已设计（存活/就绪探针）
+- [ ] 自动故障转移策略已配置
+- [ ] 手动切换流程已文档化
+- [ ] 数据库 Failover 方案已验证
+- [ ] DNS 切换方案已规划（TTL 设置）
+- [ ] 故障演练计划已制定
+
+---
+
+## 5. 安全
+
+### 5.1 认证与授权
+
+- [ ] 认证方案已确定（OAuth2/OIDC/SAML/JWT/Session）
+- [ ] Token 生命周期管理已设计（签发/刷新/撤销）
+- [ ] 权限模型已设计（RBAC/ABAC/ACL）
+- [ ] API 鉴权方案已确定
+- [ ] 服务间认证已设计（mTLS/Service Token）
+- [ ] 多因素认证需求已评估
+
+### 5.2 数据加密
+
+- [ ] 传输加密已确认（TLS 1.2+）
+- [ ] 静态数据加密方案已确定（磁盘加密/字段加密）
+- [ ] 敏感数据识别与分类已完成
+- [ ] 密钥管理方案已确定（KMS/Vault）
+- [ ] 密钥轮换策略已设计
+- [ ] 证书管理与自动续期已规划
+
+### 5.3 审计与合规
+
+- [ ] 审计日志范围已定义（操作类型/数据变更）
+- [ ] 审计日志存储与保留策略已确定
+- [ ] 审计日志防篡改方案已设计
+- [ ] 合规扫描已纳入 CI/CD
+- [ ] 渗透测试计划已制定
+- [ ] 安全事件响应流程已建立
+- [ ] 数据脱敏规则已定义（日志/测试环境）
+
+---
+
+## 6. 可观测性
+
+### 6.1 指标（Metrics）
+
+- [ ] 业务指标已定义（订单量/转化率/活跃用户）
+- [ ] 系统指标已定义（CPU/内存/磁盘/网络）
+- [ ] 应用指标已定义（请求量/延迟/错误率 — RED 方法）
+- [ ] 指标采集方案已选定（Prometheus/Datadog/CloudWatch）
+- [ ] 仪表盘已规划（总览/服务级/基础设施级）
+- [ ] 告警规则已定义（阈值/持续时间/通知渠道）
+- [ ] SLI/SLO 指标已与 SLA 对齐
+
+### 6.2 日志（Logging）
+
+- [ ] 日志格式已统一（结构化 JSON）
+- [ ] 日志级别使用规范已制定
+- [ ] 日志采集方案已选定（ELK/Loki/CloudWatch Logs）
+- [ ] 日志存储与保留策略已确定
+- [ ] 敏感信息脱敏已在日志层实现
+- [ ] 请求 ID / 关联 ID 已贯穿全链路
+
+### 6.3 追踪（Tracing）
+
+- [ ] 分布式追踪方案已选定（Jaeger/Zipkin/OpenTelemetry）
+- [ ] Trace ID 传播机制已确认（HTTP Header/消息 Header）
+- [ ] 采样策略已确定（全量/概率/自适应）
+- [ ] 追踪数据保留周期已定义
+- [ ] 关键路径已标注 Span 名称和属性
+- [ ] 追踪与日志/指标的关联已打通
+
+---
+
+## 7. 成本
+
+### 7.1 基础设施成本
+
+- [ ] 计算资源预估已完成（实例类型/数量/预留/按需）
+- [ ] 存储成本预估已完成（块存储/对象存储/数据库存储）
+- [ ] 网络成本预估已完成（跨区域流量/CDN/API 网关调用）
+- [ ] 托管服务费用已列出（数据库/缓存/消息队列/搜索）
+- [ ] 许可证费用已列出（商业软件/SaaS）
+- [ ] 成本优化策略已制定（预留实例/Spot/Savings Plan）
+
+### 7.2 运维成本
+
+- [ ] 监控/告警平台费用已评估
+- [ ] 日志存储费用已评估
+- [ ] CI/CD 平台费用已评估
+- [ ] 安全工具费用已评估（WAF/SAST/DAST）
+- [ ] 运维自动化程度已评估
+
+### 7.3 人力成本
+
+- [ ] 开发团队规模已评估
+- [ ] 运维团队规模已评估
+- [ ] 技术栈学习成本已评估
+- [ ] 招聘难度已评估（稀缺技术/市场供给）
+- [ ] 外部顾问/培训费用已评估
+
+---
+
+## 8. 文档
+
+### 8.1 架构决策记录（ADR）
+
+- [ ] ADR 模板已选定（标题/状态/上下文/决策/后果）
+- [ ] 每项重大技术选型已编写 ADR
+- [ ] ADR 存储位置已确定（代码仓库/Wiki）
+- [ ] ADR 审批流程已建立
+- [ ] 历史 ADR 已归档且可检索
+
+### 8.2 架构图
+
+- [ ] 系统上下文图已绘制（C4 Level 1）
+- [ ] 容器图已绘制（C4 Level 2）
+- [ ] 组件图已绘制（C4 Level 3，关键模块）
+- [ ] 部署图已绘制（基础设施拓扑）
+- [ ] 数据流图已绘制（关键业务流程）
+- [ ] 架构图使用代码化工具（Mermaid/PlantUML/Structurizr）
+- [ ] 架构图版本与代码同步更新
+
+### 8.3 接口文档
+
+- [ ] API 文档格式已统一（OpenAPI 3.0 / AsyncAPI）
+- [ ] API 文档自动生成已集成到 CI
+- [ ] 服务间接口契约已定义
+- [ ] 接口变更流程已建立（版本控制/向后兼容）
+- [ ] 接口示例与错误码已完善
+- [ ] SDK / 客户端库生成方案已评估
+
+---
+
+## Agent Checklist
+
+- [ ] 架构决策前已完成本清单中所有 P0 项的评估
+- [ ] 未通过的检查项已附带原因说明或待办计划
+- [ ] 清单结果已同步至 ADR 或架构评审纪要
+- [ ] 涉及的非功能需求已转化为可量化的 SLI/SLO
+- [ ] 技术选型对比矩阵已存档
+- [ ] 成本预估已获得相关方确认
+- [ ] 安全与合规项已通过安全团队评审
+- [ ] 所有架构图已更新至最新版本