15 KiB
15 KiB
架构师解决方案验证清单
本清单为架构师在开发执行前验证技术设计和架构提供了一个全面的框架。架构师应系统地审阅每个项目，确保架构的健壮性、可扩展性、安全性，并与产品需求保持一致。
[[LLM: 初始化说明 - 必要构件
在开始使用此清单之前，请确保您能访问以下内容：
- architecture.md - 主要架构文档 (检查 docs/architecture.md)
- prd.md - 产品需求文档，用于需求对齐 (检查 docs/prd.md)
- frontend-architecture.md 或 fe-architecture.md - 如果是UI项目 (检查 docs/frontend-architecture.md)
- 架构中引用的任何系统图
- 可用的API文档
- 技术栈详情和版本规范
重要提示：如果任何所需文件缺失或无法访问，请在继续之前立即向用户询问其位置或内容。
项目类型检测： 首先，通过检查以下内容来确定项目类型：
- 架构是否包含前端/UI组件？
- 是否有 frontend-architecture.md 文档？
- PRD是否提及用户界面或前端需求？
如果这是一个仅后端或仅服务的项目：
- 跳过标有 仅前端 的部分
- 特别关注API设计、服务架构和集成模式
- 在最终报告中注明由于项目类型而跳过了前端部分
验证方法： 对于每个部分，您必须：
- 深入分析 - 不要只是勾选复选框，要根据提供的文档彻底分析每个项目
- 基于证据 - 验证时引用文档中的具体部分或引述
- 批判性思维 - 质疑假设并识别差距，而不仅仅是确认已有的内容
- 风险评估 - 考虑每个架构决策可能出错的地方
执行模式： 询问用户是否希望通过以下方式审阅清单：
- 逐节进行（互动模式） - 审阅每个部分，提出发现，在继续前获得确认
- 一次性完成（全面模式） - 完成全部分析并在最后提交综合报告]]
1. 需求对齐
1.1 功能性需求覆盖
- 架构支持PRD中的所有功能性需求
- 所有史诗和故事的技术方法都已解决
- 已考虑边缘情况和性能场景
- 所有必需的集成都已考虑在内
- 技术架构支持用户旅程
1.2 非功能性需求对齐
- 性能需求通过具体解决方案得到满足
- 可扩展性考虑已记录并有相应方法
- 安全需求有相应的技术控制
- 可靠性和弹性方法已定义
- 合规性需求有技术实现
1.3 技术约束遵守
- 满足PRD中的所有技术约束
- 遵循平台/语言要求
- 已适应基础设施约束
- 已解决第三方服务约束
- 遵循组织技术标准
2. 架构基础
2.1 架构清晰度
- 架构以清晰的图表记录
- 定义了主要组件及其职责
- 映射了组件交互和依赖关系
- 清晰地说明了数据流
- 指定了每个组件的技术选择
2.2 关注点分离
- UI、业务逻辑和数据层之间有清晰的界限
- 组件之间的职责划分清晰
- 组件之间的接口定义良好
- 组件遵守单一职责原则
- 横切关注点（日志、认证等）得到妥善处理
2.3 设计模式与最佳实践
- 采用了适当的设计模式
- 遵循了行业最佳实践
- 避免了反模式
- 整个架构风格一致
- 模式的使用已记录和解释
2.4 模块化与可维护性
- 系统被划分为内聚、松耦合的模块
- 组件可以独立开发和测试
- 变更可以本地化到特定组件
- 代码组织促进可发现性
- 专为AI代理实现而设计的架构
3. 技术栈与决策
3.1 技术选型
- 所选技术满足所有要求
- 技术版本已明确定义（非范围）
- 技术选择有明确的理由
- 记录了考虑的备选方案及其优缺点
- 所选堆栈组件协同工作良好
3.2 前端架构 仅前端
LLM: 如果这是仅后端或仅服务的项目，请跳过整个部分。仅当项目包含用户界面时才进行评估。
- UI框架和库已明确选择
- 状态管理方法已定义
- 组件结构和组织已指定
- 响应式/自适应设计方法已概述
- 构建和打包策略已确定
3.3 后端架构
- API设计和标准已定义
- 服务组织和边界清晰
- 认证和授权方法已指定
- 错误处理策略已概述
- 后端扩展方法已定义
3.4 数据架构
- 数据模型已完全定义
- 数据库技术已选择并有理由
- 数据访问模式已记录
- 数据迁移/种子方法已指定
- 数据备份和恢复策略已概述
4. 前端设计与实现 仅前端
LLM: 对于仅后端的项目，应跳过整个部分。仅当项目包含用户界面时才进行评估。评估时，请确保主架构文档和特定于前端的架构文档之间的一致性。
4.1 前端理念与模式
- 框架和核心库与主架构文档一致
- 组件架构（例如，原子设计）有清晰描述
- 状态管理策略适合应用程序复杂性
- 数据流模式一致且清晰
- 样式方法已定义并指定了工具
4.2 前端结构与组织
- 目录结构以ASCII图清晰记录
- 组件组织遵循所述模式
- 文件命名约定明确
- 结构支持所选框架的最佳实践
- 关于新组件应放置位置的明确指导
4.3 组件设计
- 定义了组件模板/规范格式
- 组件的props、state和events有详细文档
- 已识别共享/基础组件
- 已建立组件可重用性模式
- 可访问性要求已内置于组件设计中
4.4 前后端集成
- API交互层定义清晰
- HTTP客户端设置和配置已记录
- API调用的错误处理全面
- 服务定义遵循一致模式
- 与后端的认证集成清晰
4.5 路由与导航
- 路由策略和库已指定
- 路由定义表全面
- 路由保护机制已定义
- 已解决深层链接问题
- 导航模式一致
4.6 前端性能
- 定义了图像优化策略
- 记录了代码拆分方法
- 建立了延迟加载模式
- 指定了重新渲染优化技术
- 定义了性能监控方法
5. 弹性和运营准备
5.1 错误处理与弹性
- 错误处理策略全面
- 在适当情况下定义了重试策略
- 为关键服务指定了断路器或回退机制
- 定义了优雅降级方法
- 系统可以从部分故障中恢复
5.2 监控与可观察性
- 定义了日志记录策略
- 指定了监控方法
- 确定了系统健康的关键指标
- 概述了警报阈值和策略
- 内置了调试和故障排除功能
5.3 性能与扩展
- 已识别并解决了性能瓶颈
- 在适当情况下定义了缓存策略
- 指定了负载均衡方法
- 概述了水平和垂直扩展策略
- 提供了资源规模建议
5.4 部署与DevOps
- 定义了部署策略
- 概述了CI/CD管道方法
- 指定了环境策略（开发、预发、生产）
- 定义了基础设施即代码（IaC）方法
- 概述了回滚和恢复程序
6. 安全与合规
6.1 认证与授权
- 认证机制定义清晰
- 授权模型已指定
- 如果需要，概述了基于角色的访问控制
- 定义了会话管理方法
- 已解决凭证管理问题
6.2 数据安全
- 指定了数据加密方法（静态和传输中）
- 定义了敏感数据处理程序
- 概述了数据保留和清除策略
- 如果需要，已解决备份加密问题
- 如果需要，指定了数据访问审计跟踪
6.3 API与服务安全
- 定义了API安全控制
- 指定了速率限制和节流方法
- 概述了输入验证策略
- 已解决CSRF/XSS预防措施
- 指定了安全通信协议
6.4 基础设施安全
- 概述了网络安全设计
- 指定了防火墙和安全组配置
- 定义了服务隔离方法
- 应用了最小权限原则
- 概述了安全监控策略
7. 实施指南
LLM: 清晰的实施指南可防止代价高昂的错误。在审阅本节时，请想象您是第一天开始工作的开发人员。他们是否拥有高效工作所需的一切？编码标准是否足够清晰以保持团队的一致性？寻找具体的示例和模式。
7.1 编码标准与实践
- 定义了编码标准
- 指定了文档要求
- 概述了测试期望
- 定义了代码组织原则
- 指定了命名约定
7.2 测试策略
- 定义了单元测试方法
- 概述了集成测试策略
- 指定了端到端（E2E）测试方法
- 概述了性能测试要求
- 定义了安全测试方法
7.3 前端测试 仅前端
- 定义了组件测试范围和工具
- 指定了UI集成测试方法
- 考虑了可视化回归测试
- 确定了可访问性测试工具
- 已解决特定于前端的测试数据管理
7.4 开发环境
- 记录了本地开发环境设置
- 指定了所需工具和配置
- 概述了开发工作流程
- 定义了源代码控制实践
- 指定了依赖管理方法
7.5 技术文档
- 定义了API文档标准
- 指定了架构文档要求
- 概述了代码文档期望
- 包括了系统图和可视化
- 包括了关键选择的决策记录
8. 依赖与集成管理
LLM: 依赖项通常是生产问题的根源。对于每个依赖项，请考虑：如果它不可用会怎样？是否有带安全补丁的新版本？我们是否被供应商锁定？我们的应急计划是什么？验证特定版本和回退策略。
8.1 外部依赖
- 已识别所有外部依赖项
- 定义了依赖项的版本控制策略
- 指定了关键依赖项的回退方法
- 已解决许可影响
- 概述了更新和修补策略
8.2 内部依赖
- 清晰映射了组件依赖关系
- 已解决构建顺序依赖关系
- 已识别共享服务和实用程序
- 消除了循环依赖
- 定义了内部组件的版本控制策略
8.3 第三方集成
- 已识别所有第三方集成
- 定义了集成方法
- 已解决与第三方的认证问题
- [- ] 指定了集成失败的错误处理
- 考虑了速率限制和配额
9. AI代理实施适用性
LLM: 此架构可能由AI代理实施。审阅时要特别注意清晰度。模式是否一致？复杂性是否最小化？AI代理会做出错误的假设吗？记住：显式优于隐式。寻找清晰的文件结构、命名约定和实施模式。
9.1 AI代理的模块化
- 组件大小适合AI代理实施
- 组件之间的依赖关系最小化
- 定义了组件之间的清晰接口
- 组件具有单一、明确定义的职责
- 为AI代理理解优化了文件和代码组织
9.2 清晰性与可预测性
- 模式一致且可预测
- 复杂逻辑被分解为更简单的步骤
- 架构避免了过于聪明或晦涩的方法
- 为不熟悉的模式提供了示例
- 组件职责明确清晰
9.3 实施指南
- 提供了详细的实施指南
- 定义了代码结构模板
- 记录了具体的实施模式
- 识别了常见陷阱并提供了解决方案
- 在有帮助时提供了类似实现的参考
9.4 错误预防与处理
- 设计减少了实施错误的机会
- 定义了验证和错误检查方法
- 在可能的情况下加入了自愈机制
- 清晰定义了测试模式
- 提供了调试指南
10. 可访问性实施 仅前端
LLM: 对于仅后端的项目，跳过此部分。可访问性是任何用户界面的核心要求。
10.1 可访问性标准
- 强调了语义化HTML的使用
- 提供了ARIA实施指南
- 定义了键盘导航要求
- 指定了焦点管理方法
- 已解决屏幕阅读器兼容性问题
10.2 可访问性测试
- 确定了可访问性测试工具
- 测试过程已集成到工作流程中
- 指定了合规性目标（WCAG级别）
- 定义了手动测试程序
- 概述了自动化测试方法
[[LLM: 最终验证报告生成
既然您已经完成了清单，请生成一份全面的验证报告，其中包括：
-
执行摘要
- 整体架构准备情况（高/中/低）
- 识别出的关键风险
- 架构的主要优势
- 项目类型（全栈/前端/后端）和评估的部分
-
部分分析
- 每个主要部分的通过率（通过项目百分比）
- 最令人担忧的失败或差距
- 需要立即关注的部分
- 注明因项目类型而跳过的任何部分
-
风险评估
- 按严重性排名的前5大风险
- 每个风险的缓解建议
- 解决问题对时间线的影响
-
建议
- 开发前必须修复的项目
- 为提高质量应修复的项目
- 可有可无的改进
-
AI实施准备情况
- 对AI代理实施的具体担忧
- 需要额外说明的领域
- 需要解决的复杂性热点
-
前端特定评估（如果适用）
- 前端架构完整性
- 主架构和前端架构文档之间的一致性
- UI/UX规范覆盖范围
- 组件设计清晰度
提交报告后，询问用户是否希望对任何特定部分进行详细分析，尤其是那些有警告或失败的部分。]]