# 钉钉扫码登录功能 - 开发计划草案
## 1. 目标
完成 `dingtalk.ts` 模块的开发，实现一个完整的、基于OAuth2.0的钉钉扫码登录流程，为MCP工具提供安全、可靠的个人身份认证。
---
## 2. 核心实现步骤
整个流程将围绕获取`accessToken`展开，可以分为以下几个关键步骤：
### **步骤 1: 构造并展示登录二维码**
- **任务**:
1. 从配置文件 (`config.ts`) 读取钉钉应用的 `appid` 和预设的 `redirect_uri`。
2. 构造一个符合钉钉开放平台规范的扫码登录URL。
- URL中需包含 `appid`, `response_type=code`, `scope=openid`, `redirect_uri` 等参数。
3. 将生成的URL转换为二维码。
4. 在终端或通过其他方式（如自动打开浏览器）向用户展示这个二维码，并引导用户扫码。
### **步骤 2: 启动本地服务器处理回调**
- **任务**:
1. 在用户扫码的同时，动态启动一个本地的轻量级Web服务器（如使用`http`模块）。
2. 这个服务器只监听一个特定的端口和路径，该路径必须与在钉钉开发者后台配置的 `redirect_uri` 相匹配。
3. 服务器启动后会一直等待，直到接收到来自钉钉的回调请求。
### **步骤 3: 接收并解析授权码 (authCode)**
- **任务**:
1. 当用户在手机上扫码并确认登录后，钉钉服务器会302重定向到我们的本地服务器地址，并在URL参数中附带一个临时的**授权码 (authCode)**。
2. 本地服务器接收到这个请求后，需要立即解析URL，成功提取出`authCode`。
3. 成功提取后，应向浏览器返回一个友好的成功提示页面（如"登录成功，请关闭此页面"），并自动关闭本地服务器以释放端口。
### **步骤 4: 用授权码换取AccessToken**
- **任务**:
1. 这是最核心的一步，需要在后端（即我们的MCP工具内部）完成。
2. 使用 `axios` 或其他HTTP客户端，向钉钉的Token获取接口 (`/v1.0/oauth2/userAccessToken`) 发起一个 **POST** 请求。
3. 请求体中必须包含 `clientId` (即`appid`), `clientSecret`, `code` (即上一步获取的`authCode`), 和 `grantType=authorization_code`。
4. 钉钉服务器验证通过后，会在响应中返回 `accessToken`, `refreshToken`, `expireIn` 等信息。
### **步骤 5: 获取用户信息并返回结果**
- **任务**:
1. （可选但推荐）使用上一步获取到的`accessToken`，再次调用钉钉的API (`/v1.0/contact/users/me`)，获取当前登录用户的基本信息（如姓名、部门等）。
2. 将 `accessToken` 和用户信息封装成一个标准的结果对象。
3. 将这个结果对象返回给 `handleDingTalkLogin` 主流程，由主流程将其存入 `TokenManager`。
---
## 3. 待办清单
- [ ] **配置**：在 `config.ts` 中添加钉钉的 `appid` 和 `clientSecret` 字段。
- [ ] **依赖**：确认是否需要添加新的npm包（如`qrcode-terminal`用于在终端显示二维码）。
- [ ] **实现**：按照上述步骤完成 `dingtalk.ts` 中的 `login()` 方法。
- [ ] **测试**：编写或执行端到端测试，确保整个流程畅通。
- [ ] **清理**：确保本地服务器能被正确关闭，避免端口占用。
