# 企业微信发送消息调试与修复指南

## 🚨 当前问题

### 1. JSSDK注册回调未触发
**现象**：
```
🔍 [registerCorpWithSuite] 调用ww.register...
（之后没有任何回调日志）
```

**原因**：
- `onAgentConfigSuccess`和`onAgentConfigFail`回调都未执行
- Promise一直处于pending状态
- 可能是企业微信JSSDK环境问题

### 2. 用户身份显示"未知"
**现象**：用户实际是"脑控徐福静"，但系统显示"未知"

**原因**：
- `currentUser`未正确加载
- 或者企业微信用户信息未同步

### 3. 消息未发送到群聊
**现象**：控制台显示准备发送，但群聊中没有消息

**原因**：JSSDK注册失败导致`sendChatMessage`无法执行

---

## ✅ 修复方案

### 1. 添加超时机制
**文件**：`wxwork-sdk.service.ts`

**问题**：如果回调永不触发，会一直等待

**修复**：
```typescript
return new Promise((resolve) => {
  // 🔥 添加15秒超时机制
  const timeout = setTimeout(() => {
    console.warn('⚠️ [registerCorpWithSuite] 注册超时（15秒），可能原因：');
    console.warn('  1. 回调函数未被触发');
    console.warn('  2. 企业微信JSSDK加载失败');
    console.warn('  3. 不在正确的群聊会话中');
    console.warn('  4. 应用权限配置错误');
    resolve(false);
  }, 15000);
  
  ww.register({
    // ...
    onAgentConfigSuccess: () => {
      clearTimeout(timeout); // ✅ 清除超时
      resolve(true);
    },
    onAgentConfigFail: (err: any) => {
      clearTimeout(timeout); // ✅ 清除超时
      resolve(false);
    }
  });
});
```

### 2. 避免重复初始化SDK
**文件**：`delivery-message.service.ts`

**问题**：`stage-delivery`和`DeliveryMessageService`都会初始化SDK

**修复**：
```typescript
// 🔥 检查SDK是否已初始化（避免重复初始化）
console.log('🔍 [sendToWxwork] 检查SDK初始化状态...');
console.log('  当前SDK.cid:', this.wxworkService.cid);
console.log('  当前SDK.appId:', this.wxworkService.appId);

if (!this.wxworkService.cid || this.wxworkService.cid !== cid) {
  console.log('🔍 [sendToWxwork] SDK未初始化或CID不匹配，开始初始化...');
  await this.wxworkService.initialize(cid, appId);
  console.log('✅ [sendToWxwork] SDK初始化完成');
} else {
  console.log('✅ [sendToWxwork] SDK已初始化，跳过重复初始化');
}
```

### 3. 增强调试日志
**文件**：`wxwork-sdk.service.ts`

**添加的日志**：
```typescript
console.log('🔍 [registerCorpWithSuite] corpId:', corpConfig.corpId);
console.log('🔍 [registerCorpWithSuite] agentId:', corpConfig.agentId);
console.log('🔍 [registerCorpWithSuite] suiteId:', suiteId);
console.log('🔍 [registerCorpWithSuite] url:', location.href);
console.log('🔍 [registerCorpWithSuite] 签名生成完成:', {
  nonceStr: '666',
  timestamp: (now.getTime() / 1000).toFixed(0),
  url: location.href
});
```

---

## 🔍 问题排查步骤

### 步骤1：检查是否在正确的环境中
**必须从企业微信群聊侧边栏打开应用**

```
✅ 正确入口：群聊 → 右上角"..." → 应用 → 你的应用
❌ 错误入口：企业微信首页 → 工作台 → 应用
❌ 错误入口：浏览器直接打开
```

**原因**：
- `sendChatMessage`只能在群聊会话上下文中使用
- 从其他入口打开应用，没有群聊上下文

### 步骤2：检查URL格式
**正确格式**：
```
https://app.fmode.cn/dev/yss/#/wxwork/cDL6R1hgSi/project/project-detail/xxx
                                    ↑        ↑         ↑
                                   固定    CID    应用ID
```

**检查日志**：
```javascript
console.log('🔍 [sendToWxwork] 当前URL:', window.location.href);
// 应该包含 /wxwork/cDL6R1hgSi/project/
```

### 步骤3：等待超时日志
**如果看到超时日志**：
```
⚠️ [registerCorpWithSuite] 注册超时（15秒），可能原因：
  1. 回调函数未被触发
  2. 企业微信JSSDK加载失败
  3. 不在正确的群聊会话中
  4. 应用权限配置错误
```

**解决方法**：
1. 确认从群聊侧边栏打开
2. 检查企业微信管理后台权限配置
3. 确认应用已发布

### 步骤4：检查应用权限
**企业微信管理后台检查清单**：
```
1. 登录企业微信管理后台
2. 应用管理 → 你的应用
3. 接口权限：
   ✅ "发送消息到聊天中" (sendChatMessage)
4. 可信域名：
   ✅ app.fmode.cn
5. 应用状态：
   ✅ 已启用
```

### 步骤5：检查用户身份
**添加调试日志**：
```typescript
console.log('👤 当前用户:', this.currentUser);
console.log('👤 用户ID:', this.currentUser?.id);
console.log('👤 用户姓名:', this.currentUser?.get('name'));
```

**如果显示"未知"**：
- 检查`ngOnInit`中是否正确加载了`currentUser`
- 检查企业微信用户信息是否同步

---

## 🧪 测试方法

### 测试1：验证JSSDK注册
**预期日志顺序**：
```
🔐 初始化企业微信SDK...
🔍 [registerCorpWithSuite] 开始注册JSSDK...
🔍 [registerCorpWithSuite] 平台检测: wxwork
🔍 [registerCorpWithSuite] API列表: [...]
🔍 [registerCorpWithSuite] 获取企业配置，CID: cDL6R1hgSi
🔍 [registerCorpWithSuite] 企业配置: {...}
🔍 [registerCorpWithSuite] 套件ID: dk2559ba758f33d8f5
🔍 [registerCorpWithSuite] 调用ww.register...
🔍 [registerCorpWithSuite] corpId: wpAs2qCQAAYofoUhMXBDS8L7z1YCXHYw
🔍 [registerCorpWithSuite] agentId: 1000017
🔍 [registerCorpWithSuite] suiteId: dk2559ba758f33d8f5
🔍 [registerCorpWithSuite] url: https://app.fmode.cn/...
🔍 [registerCorpWithSuite] 获取签名...
🔍 [registerCorpWithSuite] Ticket: ...
🔍 [registerCorpWithSuite] 签名生成完成: {...}
✅ [registerCorpWithSuite] AgentConfig注册成功!  ← 关键！
✅ 企业微信SDK初始化成功
```

**如果15秒后看到超时警告**：
```
⚠️ [registerCorpWithSuite] 注册超时（15秒）
```

**说明**：回调未触发，需要检查入口和权限

### 测试2：验证消息发送
**点击"发送消息"后的预期日志**：
```
📤 [发送消息] 开始发送...
🔍 [sendToWxwork] ========== 开始发送流程 ==========
🔍 [sendToWxwork] 当前URL: https://...
🔍 [sendToWxwork] 企业微信环境检测: true
🔍 [sendToWxwork] 检查SDK初始化状态...
✅ [sendToWxwork] SDK已初始化，跳过重复初始化
📧 准备发送消息到企业微信...
🔍 [sendChatMessage] ========== 开始发送消息 ==========
🔍 [sendChatMessage] 消息类型: text
🔍 [sendChatMessage] 开始注册JSSDK...
✅ [sendChatMessage] URL未变化，使用缓存的注册状态
🔍 [sendChatMessage] JSSDK注册结果: true
🔍 [sendChatMessage] 调用ww.sendChatMessage...
✅ [sendChatMessage] 消息发送成功!
✅ 文本消息已发送
✅ 所有消息已发送到企业微信
```

---

## 📝 使用示例

### 示例1：发送纯文本消息
```typescript
// 在stage-delivery.component.ts中
await this.deliveryMessageService.createTextMessage(
  this.project.id!,
  'white_model',
  '老师，白模阶段完成，请查看确认',
  this.currentUser
);
```

**效果**：群聊中显示文本消息

### 示例2：发送文本+图片
```typescript
await this.deliveryMessageService.createImageMessage(
  this.project.id!,
  'rendering',
  ['https://example.com/image1.jpg', 'https://example.com/image2.jpg'],
  '老师，渲染图已完成，请查看效果',
  this.currentUser
);
```

**效果**：
1. 先发送文本消息
2. 然后逐个发送图文消息（带预览）

### 示例3：直接调用SDK发送（测试用）
```typescript
// 直接调用WxworkSDKService（用于测试）
await this.wxworkSDKService.sendChatMessage({
  msgtype: 'text',
  text: {
    content: '测试消息'
  }
});
```

### 示例4：发送图文消息（带链接）
```typescript
await this.wxworkSDKService.sendChatMessage({
  msgtype: 'news',
  news: {
    link: 'https://app.fmode.cn/survey/xxx',
    title: '项目需求调查问卷',
    desc: '请填写项目需求，我们会尽快为您设计',
    imgUrl: 'https://example.com/survey-cover.jpg'
  }
});
```

**效果**：群聊中显示卡片式图文消息，点击跳转到问卷链接

---

## 🔧 常见错误及解决方案

### 错误1：注册超时
**错误信息**：
```
⚠️ [registerCorpWithSuite] 注册超时（15秒）
```

**解决方案**：
1. ✅ **重新从群聊侧边栏打开应用**
2. ✅ 检查企微管理后台的应用权限配置
3. ✅ 确认应用已发布且启用
4. ✅ 检查可信域名配置

### 错误2：Permission Denied
**错误信息**：
```
❌ [sendChatMessage] 消息发送失败!
errMsg: "sendChatMessage:fail no permission"
```

**解决方案**：
1. 企微管理后台 → 应用管理 → 你的应用
2. 接口权限 → 开启"发送消息到聊天中"
3. 保存并等待5分钟生效

### 错误3：Not in Session
**错误信息**：
```
errMsg: "sendChatMessage:fail not in session"
```

**解决方案**：
1. ❌ 不要从企微首页"工作台"打开
2. ✅ **必须从群聊侧边栏打开**
3. 路径：群聊 → 右上角"..." → 应用

### 错误4：用户身份未知
**现象**：显示"未知"而不是"脑控徐福静"

**解决方案**：
```typescript
// 在ngOnInit中确保正确加载用户
if (!this.currentUser && this.cid) {
  console.log('👤 获取当前用户...');
  const wxwork = new WxworkAuth({ cid: this.cid, appId: 'project' });
  this.currentUser = await wxwork.currentProfile();
  
  console.log('👤 当前用户:', this.currentUser);
  console.log('👤 用户姓名:', this.currentUser?.get('name'));
}
```

---

## 🎯 核心要点

### 1. 入口必须正确
```
✅ 群聊侧边栏 → 应用
❌ 企微首页工作台
❌ 浏览器直接打开
```

### 2. URL必须包含wxwork路径
```
https://app.fmode.cn/dev/yss/#/wxwork/cDL6R1hgSi/project/...
                                     ↑必须包含这部分
```

### 3. SDK初始化顺序
```
1. 组件ngOnInit → wxworkSDKService.initialize()
2. 用户点击发送 → DeliveryMessageService.sendToWxwork()
3. 检查已初始化 → 跳过重复初始化
4. 调用sendChatMessage → 发送消息
```

### 4. 超时机制
- **15秒内必须完成注册**
- 如果超时，返回false并提示原因
- 不会一直等待导致UI卡死

---

## 📝 修复文件清单

### 1. wxwork-sdk.service.ts ✅
**修改内容**：
- 添加15秒超时机制
- 增强调试日志（corpId、agentId、suiteId、url、签名详情）
- clearTimeout在回调中清除定时器

### 2. delivery-message.service.ts ✅
**修改内容**：
- 检查SDK是否已初始化，避免重复初始化
- 添加SDK状态检查日志

### 3. wxwork-sendmessage-debug-fix.md ✅
**内容**：
- 完整的问题分析
- 详细的排查步骤
- 使用示例和常见错误解决方案

---

## 🚀 部署后测试步骤

### 步骤1：构建和部署
```powershell
ng build yss-project --base-href=/dev/yss/
.\deploy.ps1
```

### 步骤2：从群聊侧边栏打开
1. 在企业微信中打开任意群聊
2. 点击右上角"..."
3. 选择你的应用
4. 进入项目详情

### 步骤3：观察初始化日志
```
✅ 应该看到：AgentConfig注册成功!
❌ 如果看到：注册超时
```

### 步骤4：发送测试消息
1. 进入"交付执行"阶段
2. 点击"发送消息"
3. 输入或选择消息内容
4. 点击发送
5. **检查群聊中是否显示消息**

### 步骤5：验证用户身份
```
✅ 应该显示：脑控徐福静
❌ 如果显示：未知
```

---

**修复完成时间**：2025-11-30 13:45  
**修复类型**：超时机制 + 重复初始化避免 + 调试增强  
**优先级**：🔥 高  
**测试状态**：待部署验证