# Story 007.001: 微信客服功能优化

## Status
Draft

## Story
**As a** 小程序用户，
**I want** 能够直接通过微信客服功能联系客服，
**so that** 可以快速获得帮助和解决问题。

## Acceptance Criteria
1. 用户点击个人中心的"联系客服"按钮时，直接打开微信客服聊天界面
2. 使用微信官方API `wx.openCustomerServiceChat` 实现客服功能
3. 从环境变量读取企业ID和客服链接配置
4. 现有的个人中心页面布局和样式保持不变
5. 新的客服功能遵循现有的微信API调用模式
6. 与现有的用户认证系统保持兼容
7. 添加客服功能相关的单元测试
8. 更新相关文档说明客服功能已可用
9. 验证现有功能无回归

## Tasks / Subtasks
- [x] 修改个人中心页面的客服按钮点击事件处理 (mini/src/pages/profile/index.tsx)
- [x] 实现 `Taro.openCustomerServiceChat` API调用
- [x] 从环境变量读取企业ID和客服链接配置
- [x] 添加错误处理和降级方案
- [x] 编写单元测试验证客服功能
- [x] 验证现有功能无回归
- [x] 更新相关文档

## Dev Notes

### 技术栈要求
- **前端框架**: Taro 4.x + React
- **小程序平台**: 微信小程序
- **API调用**: 微信小程序官方API
- **状态管理**: React Query (TanStack Query)
- **UI组件**: 自定义组件 + Heroicons

### 项目结构
- **个人中心页面**: `mini/src/pages/profile/index.tsx`
- **环境变量配置**: `mini/.env.development`, `mini/.env.production`
- **微信客服文档**: `docs/wx-kefu.md`
- **错误处理规范**: `docs/error-handling.md`

### API 集成
- **微信客服API**: `wx.openCustomerServiceChat`
- **环境变量**:
  - `TARO_APP_WX_CORP_ID=wwc6d7911e2d23b7fb`
  - `TARO_APP_WX_KEFU_URL=https://work.weixin.qq.com/kfid/kfc5f4d729bc3c893d7`

### 实现细节

#### 环境变量配置
已配置完成：
- `TARO_APP_WX_CORP_ID=wwc6d7911e2d23b7fb`
- `TARO_APP_WX_KEFU_URL=https://work.weixin.qq.com/kfid/kfc5f4d729bc3c893d7`

#### 代码位置
- 修改文件：`/mnt/code/176-162-template-21/mini/src/pages/profile/index.tsx`
- 替换第273-296行的"功能开发中..."代码

#### API调用示例
```typescript
const handleCustomerService = () => {
  try {
    wx.openCustomerServiceChat({
      extInfo: {
        url: process.env.TARO_APP_WX_KEFU_URL
      },
      corpId: process.env.TARO_APP_WX_CORP_ID,
      success: () => {
        console.log('客服聊天打开成功')
      },
      fail: (error) => {
        console.error('客服聊天打开失败:', error)
        Taro.showToast({
          title: '客服功能暂不可用，请稍后重试',
          icon: 'none'
        })
      }
    })
  } catch (error) {
    console.error('客服功能异常:', error)
    Taro.showToast({
      title: '客服功能异常，请稍后重试',
      icon: 'none'
    })
  }
}
```

### 错误处理
- **API调用失败**: 显示友好提示信息
- **网络错误**: 实现重试机制
- **兼容性检查**: 确保微信小程序基础库版本支持

### 用户体验
- **加载状态**: 显示操作进度指示器
- **操作反馈**: 使用 Taro.showToast 显示操作结果
- **降级方案**: API失败时显示友好提示

### 项目结构对齐
- **组件位置**: 符合现有的页面组织模式
- **API设计**: 遵循现有的微信API调用模式
- **文件命名**: 保持现有的kebab-case命名约定
- **导入导出**: 使用ES模块和现有别名系统

## Testing

### 测试标准
- **测试文件位置**:
  - 前端单元测试: `mini/tests/unit/pages/profile.test.tsx`
- **测试框架**: Vitest + Testing Library
- **测试模式**: 模拟微信API调用
- **覆盖率要求**: 核心业务逻辑 ≥ 80%

### 关键测试场景
- 客服按钮点击事件测试
- 微信客服API调用测试
- 错误处理测试
- 环境变量配置测试
- 降级方案测试

### 测试数据管理
- **模拟环境变量**: 测试环境配置
- **API模拟**: 模拟微信API成功和失败场景
- **边界测试**: 测试不同微信基础库版本兼容性

## Risk and Compatibility Check

### 风险评估
- **主要风险**: 微信客服API调用失败影响用户体验
- **缓解措施**: 实现错误处理和降级方案
- **回滚方案**: 恢复显示"功能开发中..."提示

### 兼容性验证
- [ ] 对现有API无破坏性变更
- [ ] 无数据库变更
- [ ] UI变更遵循现有设计模式
- [ ] 性能影响可忽略

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|---------|
| 2025-10-30 | 1.0 | 初始故事创建 | John (PM) |

## Dev Agent Record

### Agent Model Used
- Claude Sonnet 4.5

### Completion Notes List
- ✅ 故事需求分析和范围定义
- ✅ 技术方案设计
- ✅ 风险评估和兼容性检查
- ✅ 修改个人中心页面客服功能实现
- ✅ 添加环境变量配置检查
- ✅ 实现错误处理和降级方案
- ✅ 创建单元测试文件
- ✅ 修复TypeScript类型错误

### File List
- [docs/stories/007.001.story.md](docs/stories/007.001.story.md) - 用户故事文档
- [mini/src/pages/profile/index.tsx](mini/src/pages/profile/index.tsx) - 已修改的个人中心页面
- [mini/tests/pages/profile.test.tsx](mini/tests/pages/profile.test.tsx) - 个人中心页面测试文件
- [mini/.env.development](mini/.env.development) - 开发环境配置
- [mini/.env.production](mini/.env.production) - 生产环境配置

### Debug Log References
- 修复了TypeScript类型错误：环境变量可能为undefined的问题
- 使用Taro.openCustomerServiceChat替代wx.openCustomerServiceChat
- 添加了环境变量配置检查

### Change Log
| Date | Version | Description | Author |
|------|---------|-------------|---------|
| 2025-10-30 | 1.0 | 初始故事创建 | John (PM) |
| 2025-10-30 | 1.1 | 实现微信客服功能 | James (Dev) |

### Status
Ready for Review

## QA Results
*此部分将由QA代理在质量保证过程中填写*