commands/gudaspec/deepresearch-reviw.md

---
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]
---

<!-- GUDASPEC:DEEP-RESEARCH-REVIEW:START -->

## 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/<requirement-id>/internal.md
cat gudaspec/research/<requirement-id>/external.md
```

Prepare synthesis by:
- Mapping external options to internal constraints
- Identifying potential conflicts
- Preparing comparison matrices

### Step 1: Welcome and Context Recap

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 外部调研审查: <Requirement Description>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

需求ID: <requirement-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 (最终决策总结)

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 决策总结
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

经过完整的研究和审查，以下是您的所有决策：

┌─────────────────────────────────────────────────────────────┐
│ 📋 需求: <Requirement Description>                          │
│ 🆔 ID: <requirement-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: <requirement-id>

📁 生成的文档:
├─ gudaspec/research/<requirement-id>/
│  ├─ internal.md     (内部研究 - 已确认)
│  ├─ external.md     (外部研究 - 已确认)
│  └─ requirement.md  (最终需求文档) ⭐

📊 研究摘要:
┌─────────────────────────────────────────┐
│ 您做出了 8 项关键决策                   │
│ 确认了 12 条约束                        │
│ 采纳了 2 项最佳实践                     │
│ 了解并接受了 2 项风险                   │
└─────────────────────────────────────────┘

📋 下一步操作:

1. 输入 /clear 清空当前上下文
   (释放空间，为规划阶段准备)

2. 输入以下命令开始规划:
   /gudaspec:plan gudaspec/research/<requirement-id>/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

<!-- GUDASPEC:DEEP-RESEARCH-REVIEW:END -->