GitHub Issue 分析方法论

为什么需要 Issue 分析？

一个模糊的 Issue 直接开始编码，往往会导致返工。通过系统化的分析，可以在动手前就明确所有细节。

Template Sections

将 Issue 分析为以下 10 个部分：

1. Issue Summary

对 Issue 的简要概述：

## Issue Summary

Add OAuth2 login support for Google accounts to allow users
to sign in without creating a new password.

2. Problem Statement

清晰定义需要解决的问题：

## Problem Statement

Currently, users must create an account with email/password
to access the platform. This creates friction in the onboarding
process and reduces conversion rates.

3. Technical Approach

高层次的解决方案和架构决策：

## Technical Approach

-   Use Passport.js with Google OAuth2 strategy
-   Store OAuth tokens in existing User model
-   Create new AuthProvider enum for multi-provider support
-   Implement JWT token refresh for session management

4. Implementation Plan

分步骤的实现任务：

## Implementation Plan

1. Add Google OAuth credentials to environment config
2. Create OAuth callback route and controller
3. Extend User model with provider fields
4. Implement token storage and refresh logic
5. Add "Sign in with Google" button to login page
6. Handle account linking for existing users

5. Test Plan

测试策略和测试用例：

## Test Plan

-   Unit tests for OAuth token validation
-   Integration tests for callback handling
-   E2E tests for complete login flow
-   Edge case: existing email, new OAuth provider
-   Error handling: expired tokens, revoked access

6. Files to Modify

需要修改的现有文件列表：

## Files to Modify

-   src/auth/auth.module.ts - Add OAuth strategy
-   src/auth/auth.controller.ts - Add OAuth routes
-   src/user/user.schema.ts - Add provider fields
-   src/config/auth.config.ts - Add OAuth config
-   frontend/pages/login.tsx - Add OAuth button

7. Files to Create

需要创建的新文件：

## Files to Create

-   src/auth/strategies/google.strategy.ts
-   src/auth/dto/oauth-callback.dto.ts
-   src/auth/guards/oauth.guard.ts
-   tests/auth/oauth.e2e-spec.ts

8. Existing Utilities to Leverage

可以复用的项目工具/帮助函数：

## Existing Utilities to Leverage

-   src/common/guards/jwt.guard.ts - Base guard pattern
-   src/common/decorators/user.decorator.ts - User extraction
-   src/config/config.service.ts - Environment config access

9. Success Criteria

可衡量的完成标准：

## Success Criteria

-   [ ] User can click "Sign in with Google" button
-   [ ] OAuth flow redirects and returns correctly
-   [ ] User profile is created/updated from Google data
-   [ ] JWT token is issued after successful OAuth
-   [ ] Existing users can link Google account
-   [ ] All tests pass
-   [ ] No security vulnerabilities introduced

10. Out of Scope

明确不在此次实现范围内的内容：

## Out of Scope

-   Apple Sign In (future issue)
-   Facebook Login (future issue)
-   Account unlinking
-   Multiple Google accounts per user

Process

执行 Issue 分析的流程：

1. Fetch issue details using gh issue view <issue_number>

   • 获取 Issue 的完整内容

2. Review related code and project structure

   • 理解相关代码和项目结构

3. Analyze requirements thoroughly

   • 深入分析需求

4. Create detailed technical specification

   • 创建详细的技术规格

5. Follow strict TDD principles, KISS approach

   • 遵循 TDD 原则，保持简单

6. Enforce 300-line file limit where applicable

   • 文件不超过 300 行

7. Output the full technical specification for review

   • 输出完整规格供审查

完整模板

# Technical Specification: [Issue Title]

Issue: #[number]
Author: [name]
Date: [date]

## 1. Issue Summary

[Brief overview]

## 2. Problem Statement

[Clear definition of what needs to be solved]

## 3. Technical Approach

[High-level solution and architecture decisions]

## 4. Implementation Plan

1. [Step 1]
2. [Step 2]
3. [Step 3]
   ...

## 5. Test Plan

-   [Test case 1]
-   [Test case 2]
    ...

## 6. Files to Modify

-   [file1.ts] - [reason]
-   [file2.ts] - [reason]

## 7. Files to Create

-   [newfile1.ts] - [purpose]
-   [newfile2.ts] - [purpose]

## 8. Existing Utilities to Leverage

-   [utility1] - [usage]
-   [utility2] - [usage]

## 9. Success Criteria

-   [ ] [Criterion 1]
-   [ ] [Criterion 2]
-   [ ] [Criterion 3]

## 10. Out of Scope

-   [Item 1]
-   [Item 2]

---

Ready for Implementation: Yes/No
Blockers: [if any]

让 AI 帮助分析

可以让 AI 帮助分析 GitHub Issue：

请分析这个 GitHub Issue，生成技术实现规格：

[粘贴 Issue 内容]

请包括：
1. 问题陈述
2. 技术方案
3. 实现步骤
4. 测试计划
5. 文件变更清单
6. 成功标准

总结

通过系统化的 Issue 分析：

• 减少开发中的返工
• 明确实现范围和边界
• 提供清晰的验收标准
• 便于团队审查和协作

这是将模糊需求转化为可执行代码的关键步骤。