--- name: GudaSpec: Deep Research Review description: Interactive review of external research - guided technology decisions and synthesis. category: GudaSpec tags: [gudaspec, research, review, external, synthesis, interactive] argument-hint: [requirement-id] --- ## Purpose 以用户友好的方式审查外部研究发现，引导技术决策，综合内外部约束生成最终需求文档。 ## Core Principles 1. **决策导向**：聚焦于帮助用户做决定，而非展示信息 2. **对比清晰**：用表格和可视化展示选项差异 3. **风险透明**：明确说明每个选择的潜在风险 4. **关联内部**：始终与内部约束对照验证 5. **渐进收敛**：从大方向到具体细节 ## Guardrails - **MUST** use `AskUserQuestions` for all decisions - **MUST** relate external findings to internal constraints - **MUST** explain trade-offs in business terms - **NEVER** make technology decisions without user confirmation - **NEVER** present options without recommendation and rationale --- ## Steps ### Step 0: Load Both Documents ```bash cat gudaspec/research//internal.md cat gudaspec/research//external.md ``` Prepare synthesis by: - Mapping external options to internal constraints - Identifying potential conflicts - Preparing comparison matrices ### Step 1: Welcome and Context Recap ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 外部调研审查: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 需求ID: 【回顾：您之前的关键决策】 • 登录安全: 复用现有机制 • 同步频率: 每5分钟 • 实施边界: <范围描述> 【本次调研解答了】 • Microsoft Graph API vs EWS 选型 • OAuth 2.0 集成方案 • 邮件数据存储策略 接下来我会引导您完成技术选型决策。 📊 决策概览: ┌─────────────────────────────────────┐ │ 核心技术选型 ████████░░ 2 个 │ │ 实施策略确认 ██████░░░░ 2 个 │ │ 风险确认 ████░░░░░░ 1 个 │ └─────────────────────────────────────┘ 预计用时: 5-10 分钟 ``` --- ### Step 2: Core Technology Decision (核心技术决策) **Strategy**: Present as a product comparison, highlight what matters most for this specific use case. ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🎯 技术选型 1/2: 邮件API选择 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 经过调研，有两个主要方案可以实现 Outlook 邮件集成： ┌─────────────────────────────────────────────────────────────┐ │ Microsoft Graph API │ ├─────────────────────────────────────────────────────────────┤ │ 🌟 推荐理由: 微软官方推荐的现代API │ │ │ │ ✅ 优势 │ ⚠️ 注意事项 │ │ • 统一的API，可扩展到日历等 │ • 需要Azure AD应用注册 │ │ • 活跃维护，文档完善 │ • 学习曲线略高 │ │ • 支持增量同步（省流量） │ • 某些高级功能需付费许可 │ │ • 与现代OAuth 2.0完全兼容 │ │ │ │ │ │ 📊 与您项目的兼容性: 95% │ │ │ • ✅ 可复用现有OAuth基础设施 │ │ │ • ✅ 符合项目REST风格 │ │ │ • ⚠️ 需要新增 msgraph-sdk │ │ └─────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────┐ │ Exchange Web Services (EWS) │ ├─────────────────────────────────────────────────────────────┤ │ ℹ️ 备选方案: 传统但稳定 │ │ │ │ ✅ 优势 │ ⚠️ 注意事项 │ │ • 成熟稳定，案例多 │ • 微软已停止新功能开发 │ │ • 本地Exchange服务器支持好 │ • 未来可能被废弃 │ │ │ • 文档逐渐过时 │ │ │ • 某些新邮箱功能不支持 │ │ │ │ │ 📊 与您项目的兼容性: 70% │ │ │ • ⚠️ 认证方式与现有不兼容 │ │ │ • ⚠️ XML格式与项目JSON风格冲突│ │ └─────────────────────────────────────────────────────────────┘ 【我的建议】 选择 **Microsoft Graph API** 原因：与您项目的现有技术栈（OAuth、REST、JSON）高度兼容， 且是微软未来重点发展方向，长期维护成本更低。 ``` Use `AskUserQuestions`: ``` question: "邮件API您选择哪个方案？" options: [ "Microsoft Graph API（推荐）", "Exchange Web Services", "需要更多对比信息", "我有其他考虑，想讨论一下" ] ``` **If user wants more info or discussion**, provide: ``` 我来补充一些细节： 【成本对比】 • Graph API: 免费额度较大，超出后按调用计费 • EWS: 通常包含在Microsoft 365订阅中 【开发时间对比】 • Graph API: 预计 3-4 天（有官方SDK） • EWS: 预计 5-7 天（需要更多手动处理） 【您的顾虑是什么？】 ``` --- ### Step 3: Implementation Strategy Decision (实施策略决策) ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🎯 技术选型 2/2: OAuth认证流程 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 基于您选择的 Graph API，需要确定 OAuth 认证流程： 【您的场景】 用户在您的应用中点击"连接Outlook" → 跳转微软登录 → 授权后返回您的应用 → 开始同步邮件 【推荐方案: Authorization Code Flow】 ``` 用户 您的应用 微软 │ │ │ │──点击连接────▶│ │ │ │──重定向──────▶│ │ │ │ │◀──────────────────登录页面────│ │ │ │ │───────────输入账号密码───────▶│ │ │ │ │ │◀──授权码──────│ │ │ │ │ │──换取Token───▶│ │ │ │ │ │◀──Access Token│ │◀──连接成功───│ │ ``` 【此方案的优点】 • 最安全的OAuth流程（PKCE增强） • 与您现有的Google OAuth流程一致 • 可复用现有的Token刷新机制 【需要您确认】 Token存储位置： ┌────────────────────────────────────────────┐ │ A. 数据库存储（推荐） │ │ • 服务器可定时刷新 │ │ • 用户关闭浏览器后仍可后台同步 │ │ • 需要加密存储 │ ├────────────────────────────────────────────┤ │ B. 仅Session存储 │ │ • 更简单，无需额外存储 │ │ • 用户关闭浏览器后需重新授权 │ │ • 不支持后台同步 │ └────────────────────────────────────────────┘ ``` Use `AskUserQuestions`: ``` question: "Token存储方案选择？" options: [ "A. 数据库存储（推荐：支持后台同步）", "B. Session存储（简单但功能受限）", "这个决定需要更多技术背景，请解释" ] ``` --- ### Step 4: Best Practices Adoption (最佳实践采纳) **Strategy**: Present best practices as "lessons learned from others", let user decide what to adopt. ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📚 最佳实践: 他人踩过的坑 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 调研中发现了一些值得借鉴的经验： 【实践1: 增量同步】 ┌────────────────────────────────────────────┐ │ 💡 经验: 不要每次全量拉取邮件 │ │ │ │ 问题: 全量拉取会很慢且浪费API配额 │ │ 解决: 使用 deltaLink 只获取变化的邮件 │ │ 效果: API调用减少 80%，同步速度提升 5x │ │ │ │ 采纳成本: 低（Graph API原生支持） │ └────────────────────────────────────────────┘ 建议: ✅ 强烈推荐采纳 【实践2: 错误重试策略】 ┌────────────────────────────────────────────┐ │ 💡 经验: API调用失败时要智能重试 │ │ │ │ 问题: 网络波动导致同步中断 │ │ 解决: 指数退避重试 (1s, 2s, 4s, 8s...) │ │ 效果: 同步成功率从 95% 提升到 99.9% │ │ │ │ 采纳成本: 低（约2小时开发） │ └────────────────────────────────────────────┘ 建议: ✅ 推荐采纳 【实践3: 邮件内容缓存】 ┌────────────────────────────────────────────┐ │ 💡 经验: 缓存邮件正文减少重复请求 │ │ │ │ 问题: 用户反复查看同一邮件消耗API │ │ 解决: 本地缓存已读邮件内容 │ │ 效果: 响应速度提升，API成本降低 │ │ │ │ 采纳成本: 中（需要设计缓存策略） │ └────────────────────────────────────────────┘ 建议: ⚠️ 可选（根据使用频率决定） ``` Use `AskUserQuestions`: ``` question: "以上最佳实践，您希望采纳哪些？" options: [ "全部采纳（推荐）", "仅采纳强烈推荐的（实践1和2）", "最小实现，后续再优化", "我想逐个讨论" ] ``` --- ### Step 5: Risk Acknowledgment (风险确认) **Strategy**: Be transparent about potential issues, get user's acknowledgment. ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⚠️ 风险提示: 实施前须知 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 基于调研，以下风险需要您了解： 【风险1: API速率限制】 ┌────────────────────────────────────────────┐ │ 🚨 严重程度: 中 │ │ │ │ 情况: Graph API 有调用频率限制 │ │ • 每应用: 2000次/秒 │ │ • 每用户: 10000次/10分钟 │ │ │ │ 触发场景: 大量用户同时首次同步 │ │ │ │ 缓解措施: │ │ ✅ 已计划: 增量同步减少调用 │ │ ✅ 已计划: 错误重试策略 │ │ 📋 建议: 首次同步限制为最近30天邮件 │ └────────────────────────────────────────────┘ 【风险2: Token过期处理】 ┌────────────────────────────────────────────┐ │ 🚨 严重程度: 低 │ │ │ │ 情况: Access Token 1小时过期 │ │ Refresh Token 90天过期 │ │ │ │ 触发场景: 用户90天未使用需重新授权 │ │ │ │ 缓解措施: │ │ ✅ 已计划: 自动刷新机制 │ │ 📋 建议: 过期前邮件提醒用户重新授权 │ └────────────────────────────────────────────┘ 【总体风险评估】 以上风险在正确实施后均可控。 无阻塞性风险，可以继续推进。 ``` Use `AskUserQuestions`: ``` question: "您是否了解并接受以上风险？" options: [ "了解，可以接受", "风险1我有顾虑，想讨论一下", "风险2我有顾虑，想讨论一下", "需要更详细的风险分析" ] ``` --- ### Step 6: Constraint Conflict Resolution (约束冲突解决) **Strategy**: If there are conflicts between internal and external constraints, present clearly and get resolution. ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⚡ 约束冲突: 需要您做决定 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 在综合内外部研究时，发现一个需要协调的点： 【冲突描述】 ┌────────────────────────────────────────────┐ │ 内部约束: │ │ 现有认证模块使用 HS256 算法签名 JWT │ │ │ │ 外部推荐: │ │ Microsoft 最佳实践建议使用 RS256 算法 │ │ │ │ 冲突点: │ │ 算法不同，无法直接复用现有 Token 验证逻辑 │ └────────────────────────────────────────────┘ 【解决方案】 方案A: 统一升级到 RS256 ┌────────────────────────────────────────────┐ │ 做法: 整体迁移现有认证到 RS256 │ │ 优点: 安全性更高，架构统一 │ │ 代价: 需要修改现有代码，所有用户重新登录 │ │ 工作量: +2天 │ └────────────────────────────────────────────┘ 方案B: 双算法共存 ┌────────────────────────────────────────────┐ │ 做法: 现有保持 HS256，Outlook 用 RS256 │ │ 优点: 不影响现有功能 │ │ 代价: 代码复杂度增加，维护两套逻辑 │ │ 工作量: +0.5天 │ └────────────────────────────────────────────┘ 方案C: Outlook也用 HS256 ┌────────────────────────────────────────────┐ │ 做法: 忽略微软建议，统一用 HS256 │ │ 优点: 最简单，完全复用现有逻辑 │ │ 代价: 安全性略低于推荐标准 │ │ 工作量: +0天 │ └────────────────────────────────────────────┘ 【我的建议】 选择 **方案B: 双算法共存** 原因：平衡了安全性和改动范围，Outlook模块使用推荐算法， 不影响现有用户，未来可渐进式迁移。 ``` Use `AskUserQuestions`: ``` question: "对于JWT算法冲突，您选择哪个方案？" options: [ "方案A: 统一升级（更安全，改动大）", "方案B: 双算法共存（推荐：平衡）", "方案C: 统一HS256（最简单）", "需要更多信息来决定" ] ``` --- ### Step 7: Final Decision Summary (最终决策总结) ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ 决策总结 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 经过完整的研究和审查，以下是您的所有决策： ┌─────────────────────────────────────────────────────────────┐ │ 📋 需求: │ │ 🆔 ID: │ ├─────────────────────────────────────────────────────────────┤ │ │ │ 【内部研究决策】 │ │ ├─ 登录安全: 复用现有机制 │ │ ├─ 项目规范: 完全遵循 │ │ ├─ 集成方案: 3个对接点 │ │ └─ 同步频率: 每5分钟 │ │ │ │ 【外部研究决策】 │ │ ├─ 邮件API: Microsoft Graph API │ │ ├─ 认证流程: Authorization Code Flow + PKCE │ │ ├─ Token存储: 数据库加密存储 │ │ ├─ 最佳实践: 采纳增量同步 + 错误重试 │ │ └─ JWT算法: 双算法共存 │ │ │ │ 【风险确认】 │ │ ├─ API限速: 已了解，通过增量同步缓解 │ │ └─ Token过期: 已了解，通过自动刷新处理 │ │ │ ├─────────────────────────────────────────────────────────────┤ │ 📊 实施预估 │ │ ├─ 涉及文件: 12-15 个 │ │ ├─ 新增依赖: msgraph-sdk, msal │ │ ├─ 预计工时: 5-7 天 │ │ └─ 风险等级: 中低 │ └─────────────────────────────────────────────────────────────┘ ``` Use `AskUserQuestions`: ``` question: "以上决策总结是否准确完整？" options: [ "准确，生成最终需求文档", "基本准确，有小的补充", "需要修改某项决策" ] ``` --- ### Step 8: Generate Final Requirement Document Create comprehensive `requirement.md` incorporating all confirmed decisions. **Key sections to include**: - 所有内部约束（已确认） - 所有外部约束（已确认） - 技术决策及理由 - 采纳的最佳实践 - 风险及缓解措施 - 用户所有决策的完整记录 --- ### Step 9: Completion Output ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🎉 Research 全部完成！ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 需求ID: 📁 生成的文档: ├─ gudaspec/research// │ ├─ internal.md (内部研究 - 已确认) │ ├─ external.md (外部研究 - 已确认) │ └─ requirement.md (最终需求文档) ⭐ 📊 研究摘要: ┌─────────────────────────────────────────┐ │ 您做出了 8 项关键决策 │ │ 确认了 12 条约束 │ │ 采纳了 2 项最佳实践 │ │ 了解并接受了 2 项风险 │ └─────────────────────────────────────────┘ 📋 下一步操作: 1. 输入 /clear 清空当前上下文 (释放空间，为规划阶段准备) 2. 输入以下命令开始规划: /gudaspec:plan gudaspec/research//requirement.md 规划阶段将基于您确认的约束，生成详细的实施计划。 ``` --- ## Question Design Patterns for External Review ### Pattern 1: Product Comparison (产品对比) ``` 【方案A】 vs 【方案B】 ┌──────────────┐ ┌──────────────┐ │ 特点 │ │ 特点 │ │ 优势 │ │ 优势 │ │ 劣势 │ │ 劣势 │ │ 适用场景 │ │ 适用场景 │ └──────────────┘ └──────────────┘ 我的建议: [方案X]，因为 [与您需求的匹配点] ``` ### Pattern 2: Trade-off Matrix (权衡矩阵) ``` ┌─────────┬──────┬──────┬──────┐ │ 维度 │ A │ B │ C │ ├─────────┼──────┼──────┼──────┤ │ 成本 │ ⭐⭐⭐ │ ⭐⭐ │ ⭐ │ │ 复杂度 │ ⭐ │ ⭐⭐ │ ⭐⭐⭐ │ │ 安全性 │ ⭐⭐⭐ │ ⭐⭐ │ ⭐ │ └─────────┴──────┴──────┴──────┘ 您更看重哪个维度？ ``` ### Pattern 3: Impact Visualization (影响可视化) ``` 如果选择 [方案X]: 现在 3个月后 ──── ──────── [现状] ──────────────▶ [预期结果] 收益: [具体数字/效果] 代价: [具体工作量/风险] ``` ### Pattern 4: Lesson Learned (经验借鉴) ``` 【他人经验】 问题: 遇到了什么问题 原因: 为什么会这样 解决: 怎么解决的 效果: 解决后怎样 【对您的启示】 建议: 您应该/不应该... ``` --- ## Exit Criteria - [ ] All technology decisions confirmed with user rationale - [ ] All best practices reviewed (adopted/skipped with reason) - [ ] All risks acknowledged by user - [ ] All constraint conflicts resolved - [ ] Final decision summary confirmed by user - [ ] requirement.md generated with complete documentation - [ ] User directed to /gudaspec:plan