mini-starter/docs/stories/007.001.story.md

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

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

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调用示例

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 - 用户故事文档
• mini/src/pages/profile/index.tsx - 已修改的个人中心页面
• mini/tests/pages/profile.test.tsx - 个人中心页面测试文件
• mini/.env.development - 开发环境配置
• 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代理在质量保证过程中填写