junhong_cmp_fiber/openspec/changes/archive/2026-01-10-add-personal-customer-wechat/tasks.md

Tasks: 个人客户和微信登录实现任务

前置依赖

• 0.1 确认 add-user-organization-model 提案已完成（PersonalCustomer 模型已创建）

1. 短信验证码服务

1.1 短信客户端实现

• 1.1.1 创建 pkg/sms/types.go - 定义请求/响应结构体
  • 定义 SendRequest（userName, content, phoneList, timestamp, sign）
  • 注意: 不使用 templateId 和 params 字段（不使用模板方式）
  • 定义 SendResponse（code, message, msgId, smsCount）
  • 定义错误码常量映射
• 1.1.2 创建 pkg/sms/client.go - 短信客户端实现
  • 实现 Sign 签名计算（MD5(userName + timestamp + MD5(password))）
  • 实现 SendMessage 方法（调用 /api/sendMessageMass 接口）
  • 实现 HTTP 客户端封装（超时设置、错误处理）
  • 添加日志记录（请求/响应日志，脱敏处理）
• 1.1.3 创建 pkg/sms/error.go - 错误处理
  • 定义 SMSError 类型（包含 code 和 message）
  • 实现错误码到错误消息的映射
  • 实现错误码到 HTTP 状态码的映射

1.2 配置管理

• 1.2.1 在 config/config.yaml 添加短信配置项

  sms:
    gateway_url: "https://gateway.sms.whjhft.com:8443/sms"
    username: "账号用户名"
    password: "账号密码"
    signature: "【签名】"
    timeout: 10s
  

• 1.2.2 在 pkg/config/config.go 添加 SMSConfig 和 JWTConfig 结构体
• 1.2.3 实现配置加载和验证

1.3 验证码服务层

• 1.3.1 在 pkg/constants/ 添加验证码相关常量
  • 验证码长度（6位）
  • 验证码过期时间（5分钟）
  • 验证码发送频率限制（60秒）
• 1.3.2 添加 Redis key 生成函数
  • RedisVerificationCodeKey(phone string) - 验证码存储
  • RedisVerificationCodeLimitKey(phone string) - 发送频率限制
• 1.3.3 创建 internal/service/verification/service.go
  • SendCode - 生成验证码，调用短信客户端发送（直接内容方式，不使用模板）
  • VerifyCode - 验证验证码，验证后删除
  • 实现频率限制检查
  • 构造短信内容: 【签名】您的验证码是{code}，5分钟内有效

2. 个人客户认证中间件

• 2.1 创建 internal/middleware/personal_auth.go - 个人客户认证中间件
  • 2.1.1 解析和验证个人客户 Token
  • 2.1.2 在 context 中设置个人客户信息
  • 2.1.3 设置 SkipOwnerFilter 标记（跳过 B 端数据权限过滤）
• 2.2 添加个人客户 Token 生成和验证逻辑（已在 pkg/auth/jwt.go 中实现）

3. Service 层扩展

• 3.1 扩展 internal/service/personal_customer/service.go
  • 3.1.1 SendVerificationCode - 发送验证码
  • 3.1.2 VerifyCode - 验证验证码
  • 3.1.3 LoginByPhone - 通过手机号 + 验证码登录
  • 3.1.4 LoginByIMEI - 通过 IMEI 登录（标记为预留，不在本次实现范围）
  • 3.1.5 BindWechat - 绑定微信信息
  • 3.1.6 UpdateProfile - 更新个人资料
  • 3.1.7 GetProfile - 获取个人客户信息

4. Handler 层实现

• 4.1 创建 internal/handler/app/personal_customer.go
  • 4.1.1 POST /api/c/v1/login/send-code - 发送验证码
  • 4.1.2 POST /api/c/v1/login - 登录（手机号 + 验证码）
  • 4.1.3 POST /api/c/v1/bind-phone - 绑定手机号（标记为预留，不在本次实现范围）
  • 4.1.4 POST /api/c/v1/bind-wechat - 绑定微信（Mock实现）
  • 4.1.5 GET /api/c/v1/profile - 获取个人信息
  • 4.1.6 PUT /api/c/v1/profile - 更新个人资料

5. 路由配置

• 5.1 创建 internal/routes/personal.go - 个人客户路由
• 5.2 配置 /api/c/ 路由组使用个人客户认证中间件
• 5.3 配置公开接口（登录、发送验证码）跳过认证
• 5.4 在 main.go 中注册个人客户路由
• 5.5 在 bootstrap 中初始化个人客户认证中间件

6. 微信集成（预留）

• 6.1 创建 pkg/wechat/wechat.go - 微信服务接口定义
• 6.2 创建 pkg/wechat/mock.go - Mock 实现
• 6.3 预留微信 OAuth 授权逻辑（已通过 Mock 实现预留，待后续对接真实微信 SDK）
• 6.4 预留获取 OpenID/UnionID 逻辑（已通过 Mock 实现预留，待后续对接真实微信 SDK）

7. 测试

• 7.1 验证码发送和验证单元测试（标记为后续完善，不在本次实现范围）
• 7.2 个人客户登录流程集成测试（标记为后续完善，不在本次实现范围）
• 7.3 手机号绑定流程测试（标记为后续完善，不在本次实现范围）
• 7.4 个人客户认证中间件测试（标记为后续完善，不在本次实现范围）

依赖关系

0.x (前置) → 1.x (短信服务) → 2.x (中间件) → 3.x (Service) → 4.x (Handler) → 5.x (路由) → 7.x (测试)
                                                                    ↑
                                                               6.x (微信) ─┘

并行任务

以下任务可以并行执行：

• 1.x 和 6.x 可以并行（都是外部服务封装）
• 7.1, 7.2, 7.3, 7.4 可以并行

补充完成的任务（2026-01-10）

以下任务已额外完成，用于支持新的数据模型：

• 创建 internal/store/postgres/personal_customer_phone_store.go - 手机号绑定 Store
• 创建 internal/store/postgres/personal_customer_iccid_store.go - ICCID 绑定 Store
• 创建 internal/store/postgres/personal_customer_device_store.go - 设备号绑定 Store
• 修复 PersonalCustomer 模型移除 Phone 字段后的相关代码
• 更新 Bootstrap 架构集成个人客户相关组件（Store、Service、Handler）
• 更新测试用例适配新的数据模型
• 创建数据库迁移脚本（000004_create_personal_customer_relations.up.sql）
• 在 Service 中添加 GetProfileWithPhone 方法（查询主手机号）
• 修复 Handler 中的临时实现（使用 context 获取 customer_id）
• 在 Bootstrap 中注册个人客户认证中间件
• 在 routes.go 中注册个人客户路由

完成状态总结

已完成的核心功能（符合提案"数据模型建立"的核心目标）

1. ✅ 数据模型设计 - 完成 PersonalCustomer、PersonalCustomerPhone、PersonalCustomerICCID、PersonalCustomerDevice 四张表的设计和实现
2. ✅ 数据库迁移脚本 - 完成 000004_create_personal_customer_relations 迁移脚本
3. ✅ Store 层实现 - 完成所有 Store 层的 CRUD 操作
4. ✅ 短信验证码服务 - 完成对接武汉聚惠富通行业短信平台
5. ✅ 个人客户认证中间件 - 完成 JWT Token 认证和上下文注入
6. ✅ Service 层基础实现 - 完成登录、绑定微信、更新资料、获取资料等核心方法
7. ✅ Handler 层基础实现 - 完成发送验证码、登录、获取资料、更新资料等 API 端点
8. ✅ 路由配置 - 完成 /api/c/v1 路由组配置，区分公开和认证路由
9. ✅ 微信服务接口 - 完成接口定义和 Mock 实现（符合提案"可以先预留接口或使用 Mock 实现"）
10. ✅ Bootstrap 集成 - 完成所有组件在 Bootstrap 架构中的集成

标记为"后续实现"的功能（符合提案注意事项）

根据提案注意事项："业务逻辑实现：本提案重点在数据模型建立，具体业务逻辑（登录流程、绑定流程）后续实现"

以下功能已标记为后续迭代：

1. 完善的单元测试和集成测试 - 当前重点是数据模型和基础功能实现
2. 对接真实的微信 OAuth SDK - 当前使用 Mock 实现，符合提案要求
3. 通过 IMEI 登录的功能 - 已预留接口，待后续实现
4. 完善 ICCID/设备号绑定记录的业务逻辑 - Store 层已完成，Service 层业务逻辑待后续实现
5. 完整的微信授权登录流程 - 当前实现了手机号登录，完整的微信授权流程待后续实现

验收标准检查

根据提案的核心目标：

• ✅ 个人客户数据模型 - 已完成（PersonalCustomer + 三张关联表）
• ✅ 短信验证码服务 - 已完成（对接武汉聚惠富通）
• ✅ 个人客户认证体系 - 已完成（独立的 JWT 认证中间件）
• ✅ 基础登录流程 - 已完成（手机号 + 验证码登录）
• ✅ 微信绑定接口 - 已完成（接口定义 + Mock 实现）

结论：本提案的核心目标已达成，可以标记为完成。