huang
9c6d4a3bd4
- 添加个人客户微信登录和手机验证码登录接口 - 实现个人客户设备、ICCID、手机号关联管理 - 添加短信发送服务（HTTP 客户端） - 添加微信认证服务（含 mock 实现） - 添加 JWT Token 生成和验证工具 - 创建数据库迁移脚本（personal_customer 关联表） - 修复测试文件中的路由注册参数错误 - 重构 scripts 目录结构（分离独立脚本到子目录） Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
202 lines
7.2 KiB
Markdown
202 lines
7.2 KiB
Markdown
# personal-customer Specification
|
||
|
||
## Purpose
|
||
TBD - created by archiving change add-personal-customer-wechat. Update Purpose after archive.
|
||
## Requirements
|
||
### Requirement: 短信验证码服务
|
||
|
||
系统 SHALL 提供短信验证码服务，对接行业短信平台，支持发送验证码到指定手机号，验证码存储在 Redis 中并设置过期时间。
|
||
|
||
#### 短信服务对接规范
|
||
|
||
**短信服务商**: 武汉聚惠富通（行业短信）
|
||
**接口网关**: `https://gateway.sms.whjhft.com:8443/sms`
|
||
**协议版本**: HTTP JSON API v1.6
|
||
**接口文档**: 参考 `docs/第三方文档/SMS_HTTP_1.6.md`
|
||
|
||
**使用接口**: 短信批量发送接口 `/api/sendMessageMass`
|
||
|
||
**发送方式**: 直接发送内容（不使用短信模板）
|
||
|
||
**短信内容格式**: `【签名】自定义内容`
|
||
- 签名部分（如 `【签名】`）需提前向服务商报备并审核通过
|
||
- 自定义内容为实际短信文本
|
||
- 示例: `【签名】您的验证码是123456，5分钟内有效`
|
||
|
||
**请求参数规范**:
|
||
```json
|
||
{
|
||
"userName": "账号用户名（从配置读取）",
|
||
"content": "【签名】您的验证码是{验证码}，5分钟内有效",
|
||
"phoneList": ["13500000001"],
|
||
"timestamp": 1596254400000, // 当前时间戳（毫秒）
|
||
"sign": "e315cf297826abdeb2092cc57f29f0bf" // MD5(userName + timestamp + MD5(password))
|
||
}
|
||
```
|
||
|
||
**Sign 计算规则**:
|
||
- 计算方式: `MD5(userName + timestamp + MD5(password))`
|
||
- 示例:
|
||
- `userName = "test"`
|
||
- `password = "123"`
|
||
- `timestamp = 1596254400000`
|
||
- `MD5(password) = "202cb962ac59075b964b07152d234b70"`
|
||
- `组合字符串 = "test1596254400000202cb962ac59075b964b07152d234b70"`
|
||
- `sign = MD5(组合字符串) = "e315cf297826abdeb2092cc57f29f0bf"`
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 0, // 0-成功，其他-失败（参考响应状态码列表）
|
||
"message": "处理成功",
|
||
"msgId": 123456, // 短信消息ID（用于后续追踪）
|
||
"smsCount": 1 // 消耗计费数
|
||
}
|
||
```
|
||
|
||
**配置项** (需在 `config.yaml` 中添加):
|
||
```yaml
|
||
sms:
|
||
gateway_url: "https://gateway.sms.whjhft.com:8443/sms"
|
||
username: "账号用户名"
|
||
password: "账号密码"
|
||
signature: "【签名】" # 短信签名（需提前报备）
|
||
timeout: 10s
|
||
```
|
||
|
||
**错误处理**:
|
||
- `code=0`: 发送成功
|
||
- `code=5`: 账号余额不足（记录错误日志，返回用户友好提示）
|
||
- `code=16`: 时间戳差异过大（检查服务器时间）
|
||
- 其他错误码: 参考文档第13节"响应状态码列表"
|
||
|
||
**重要说明**:
|
||
- 本系统使用直接内容发送方式,不使用短信模板
|
||
- 请求中只需要 `content` 字段,不需要 `templateId` 和 `params` 参数
|
||
- 短信内容必须包含已报备的签名,格式为 `【签名】` + 自定义文本
|
||
|
||
#### Scenario: 发送验证码成功
|
||
- **WHEN** 用户请求发送验证码到有效手机号
|
||
- **THEN** 系统生成6位数字验证码，存储到 Redis（过期时间5分钟），调用短信服务发送
|
||
|
||
#### Scenario: 验证码频率限制
|
||
- **WHEN** 用户在60秒内重复请求发送验证码
|
||
- **THEN** 系统拒绝请求并返回错误"请60秒后再试"
|
||
|
||
#### Scenario: 短信发送失败
|
||
- **WHEN** 短信服务返回错误（如余额不足、账号异常等）
|
||
- **THEN** 系统记录错误日志，返回用户友好提示"短信发送失败，请稍后重试"
|
||
|
||
#### Scenario: 验证码验证成功
|
||
- **WHEN** 用户提交正确的验证码
|
||
- **THEN** 系统验证通过并删除 Redis 中的验证码
|
||
|
||
#### Scenario: 验证码验证失败
|
||
- **WHEN** 用户提交错误的验证码
|
||
- **THEN** 系统返回错误"验证码错误"
|
||
|
||
#### Scenario: 验证码过期
|
||
- **WHEN** 用户提交的验证码已超过5分钟
|
||
- **THEN** 系统返回错误"验证码已过期"
|
||
|
||
---
|
||
|
||
### Requirement: 个人客户登录流程
|
||
|
||
系统 SHALL 支持个人客户通过 ICCID（网卡号）或 IMEI（设备号）登录，首次登录需绑定手机号并验证。
|
||
|
||
#### Scenario: 已绑定用户登录
|
||
- **WHEN** 用户输入 ICCID/IMEI，且该 ICCID/IMEI 已绑定手机号
|
||
- **THEN** 系统发送验证码到已绑定手机号，用户验证后登录成功
|
||
|
||
#### Scenario: 未绑定用户首次登录
|
||
- **WHEN** 用户输入 ICCID/IMEI，且该 ICCID/IMEI 未绑定手机号
|
||
- **THEN** 系统提示用户输入手机号，发送验证码，验证后创建个人客户记录并登录
|
||
|
||
#### Scenario: 登录成功返回Token
|
||
- **WHEN** 用户验证码验证通过
|
||
- **THEN** 系统生成个人客户专用 Token 并返回
|
||
|
||
#### Scenario: ICCID/IMEI 不存在
|
||
- **WHEN** 用户输入的 ICCID/IMEI 在资产表中不存在
|
||
- **THEN** 系统返回错误"设备号不存在"（注：资产表后续实现）
|
||
|
||
---
|
||
|
||
### Requirement: 手机号绑定
|
||
|
||
系统 SHALL 支持个人客户绑定手机号，一个手机号可以关联多个 ICCID/IMEI（即一个个人客户可以拥有多个资产）。
|
||
|
||
#### Scenario: 绑定新手机号
|
||
- **WHEN** 个人客户请求绑定手机号，且该手机号未被其他用户绑定
|
||
- **THEN** 系统发送验证码，验证后绑定手机号
|
||
|
||
#### Scenario: 手机号已被绑定
|
||
- **WHEN** 个人客户请求绑定的手机号已被其他用户绑定
|
||
- **THEN** 系统返回错误"该手机号已被绑定"
|
||
|
||
#### Scenario: 更换手机号
|
||
- **WHEN** 个人客户已有绑定手机号，请求更换为新手机号
|
||
- **THEN** 系统需要同时验证旧手机号和新手机号后才能更换
|
||
|
||
---
|
||
|
||
### Requirement: 微信信息绑定
|
||
|
||
系统 SHALL 支持个人客户绑定微信信息（OpenID、UnionID），用于后续的微信支付和消息推送。
|
||
|
||
#### Scenario: 微信授权绑定
|
||
- **WHEN** 个人客户在微信环境中授权登录
|
||
- **THEN** 系统获取并存储 OpenID 和 UnionID
|
||
|
||
#### Scenario: 微信信息更新
|
||
- **WHEN** 个人客户重新授权微信
|
||
- **THEN** 系统更新 OpenID 和 UnionID
|
||
|
||
#### Scenario: 查询微信绑定状态
|
||
- **WHEN** 请求个人客户信息时
|
||
- **THEN** 系统返回是否已绑定微信（不返回具体的 OpenID/UnionID）
|
||
|
||
---
|
||
|
||
### Requirement: 个人客户认证中间件
|
||
|
||
系统 SHALL 提供独立于 B 端账号的个人客户认证中间件，用于 /api/c/ 路由组的请求认证。
|
||
|
||
#### Scenario: Token验证成功
|
||
- **WHEN** 请求携带有效的个人客户 Token
|
||
- **THEN** 中间件解析 Token，在 context 中设置个人客户信息
|
||
|
||
#### Scenario: Token验证失败
|
||
- **WHEN** 请求携带无效或过期的 Token
|
||
- **THEN** 中间件返回 401 Unauthorized 错误
|
||
|
||
#### Scenario: 跳过B端数据权限过滤
|
||
- **WHEN** 个人客户认证成功后
|
||
- **THEN** 中间件在 context 中设置 SkipOwnerFilter 标记，Store 层跳过 shop_id 过滤
|
||
|
||
#### Scenario: 公开接口跳过认证
|
||
- **WHEN** 请求访问 /api/c/v1/login 或 /api/c/v1/login/send-code
|
||
- **THEN** 中间件跳过认证，允许访问
|
||
|
||
---
|
||
|
||
### Requirement: 个人客户路由分组
|
||
|
||
系统 SHALL 将个人客户相关的 API 放在 /api/c/v1/ 路由组下，与 B 端 API（/api/v1/）隔离。
|
||
|
||
#### Scenario: 登录相关接口
|
||
- **WHEN** 请求 POST /api/c/v1/login/send-code
|
||
- **THEN** 系统发送验证码（公开接口）
|
||
|
||
#### Scenario: 个人信息接口
|
||
- **WHEN** 请求 GET /api/c/v1/profile
|
||
- **THEN** 系统返回当前登录的个人客户信息（需认证）
|
||
|
||
#### Scenario: B端和C端隔离
|
||
- **WHEN** 个人客户 Token 访问 /api/v1/ 接口
|
||
- **THEN** 系统返回 401 Unauthorized（Token 类型不匹配）
|
||
|
||
---
|
||
|