csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
b9733c49136c8a755d3b0307e457e14be21a7fc1
junhong_cmp_fiber/openspec/specs/personal-customer/spec.md
huang b9733c4913
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m12s
Details
fix: 修正零售价架构错误 + 清理旧微信配置 + 归档提案 + 前端接口文档 
1. 修正 retail_price 架构：
   - 删除 batch-pricing 接口的 pricing_target 字段和 retail_price 分支
     （上级只能改下级成本价，不能改零售价）
   - 新增 PATCH /api/admin/packages/:id/retail-price 接口
     （代理自己改自己的零售价，校验 retail_price >= cost_price）

2. 清理旧微信 YAML 配置（已全部迁移到数据库 tb_wechat_config）：
   - 删除 config.yaml 中 wechat.official_account 配置节
   - 删除 NewOfficialAccountApp() 旧工厂函数
   - 清理 personal_customer service 中的死代码（旧登录/绑定微信方法）
   - 清理 docker-compose.prod.yml 中旧微信环境变量和证书挂载注释

3. 归档四个已完成提案到 openspec/changes/archive/

4. 新增前端接口变更说明文档（docs/前端接口变更说明.md）

5. 修正归档提案和 specs 中关于 pricing_target 的错误描述
2026-03-19 17:39:43 +08:00

449 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 类型不匹配）
---
### Requirement: OpenAPI 文档集成
个人客户 API SHALL 纳入项目的 OpenAPI 文档生成体系，使用统一的 `Register()` 机制注册路由。
#### Scenario: 路由注册纳入文档
- **WHEN** 个人客户路由使用 `Register()` 函数注册
- **THEN** 路由自动出现在生成的 OpenAPI 文档中
- **AND** 文档包含完整的请求/响应结构、认证信息和中文描述
#### Scenario: 文档标签分类
- **WHEN** 生成 OpenAPI 文档
- **THEN** 个人客户 API 使用 "个人客户 - 认证" 和 "个人客户 - 账户" 等中文标签分类
- **AND** 与后台管理 API 标签区分
#### Scenario: 响应格式统一
- **WHEN** 个人客户 API 返回响应
- **THEN** 使用统一的 envelope 格式：`{code, msg, data, timestamp}`
- **AND** 与后台管理 API 响应格式一致
**实现位置**: `internal/routes/personal.go`
**文档路径**: `/api/c/v1` 路由组在 `docs/admin-openapi.yaml` 中可见
---
### Requirement: 个人客户路由必须纳入文档体系
个人客户 API 路由注册 SHALL 使用 `Register(...)` 机制，与其他路由（admin、h5）保持一致。
#### Scenario: RegisterPersonalRoutes 函数签名变更
- **WHEN** 定义 `RegisterPersonalRoutes` 函数
- **THEN** 函数签名为：
```go
func RegisterPersonalRoutes(doc *openapi.Generator, basePath string, handlers *bootstrap.Handlers)
```
- **AND** 不再接受 `*fiber.App` 参数
#### Scenario: 使用 RouteSpec 注册路由
- **WHEN** 在 `RegisterPersonalRoutes` 中注册路由
- **THEN** 使用 `doc.Register(openapi.RouteSpec{...})` 注册
- **AND** 每个路由包含完整的元数据（Method, Path, Handler, Summary, Tags, Auth, Input, Output）
#### Scenario: 路由路径保持不变
- **WHEN** 改造路由注册方式
- **THEN** 路由路径保持 `/api/c/v1/xxx` 格式
- **AND** 不修改路径结构
- **AND** 与现有客户端保持兼容
### Requirement: 个人客户 API 的文档元数据
个人客户 API 的 RouteSpec SHALL 包含中文 Summary 和统一的 Tags。
#### Scenario: Summary 使用中文描述
- **WHEN** 定义个人客户 API 的 RouteSpec
- **THEN** Summary 字段使用中文描述（如 "获取个人客户卡详情"）
- **AND** 描述简洁明了（一行以内）
#### Scenario: Tags 统一为"个人客户"
- **WHEN** 定义个人客户 API 的 RouteSpec
- **THEN** Tags 字段包含 `["个人客户"]`
- **AND** 所有个人客户 API 使用相同的 tag
- **AND** 在 OpenAPI 文档中归类到同一分组
#### Scenario: Auth 字段正确设置
- **WHEN** 定义个人客户 API 的 RouteSpec
- **THEN** 需要认证的接口设置 `Auth: true`
- **AND** 无需认证的接口（如微信登录）设置 `Auth: false`
### Requirement: 个人客户路由在文档中可见
生成的 OpenAPI 文档 SHALL 包含所有个人客户 API 路由。
#### Scenario: 文档包含 /api/c/v1 路径
- **WHEN** 生成 OpenAPI 文档（`go run cmd/gendocs/main.go`）
- **THEN** 生成的 `logs/openapi.yaml` 包含 `/api/c/v1` 路径
- **AND** 路径数量与 `RegisterPersonalRoutes` 中注册的一致
#### Scenario: 个人客户接口在文档中正确分组
- **WHEN** 查看生成的 OpenAPI 文档
- **THEN** 个人客户接口在 "个人客户" tag 下
- **AND** 与其他模块（admin、h5）分组隔离
#### Scenario: 接口元数据完整
- **WHEN** 查看个人客户接口的 OpenAPI 定义
- **THEN** 每个接口包含：
- Summary（中文摘要）
- Description（详细说明，如有）
- Parameters（路径参数、查询参数）
- RequestBody（请求体 schema）
- Responses（响应 schema，包含 envelope）
- Security（认证要求）
### Requirement: 个人客户 Handler 在文档生成器中注册
个人客户 Handler SHALL 在 `BuildDocHandlers()` 中构造。
#### Scenario: BuildDocHandlers 包含 PersonalCustomer
- **WHEN** 调用 `openapi.BuildDocHandlers()`
- **THEN** 返回的 `bootstrap.Handlers` 包含 `PersonalCustomer` 字段
- **AND** PersonalCustomer 使用 `personal.NewPersonalCustomerHandler(nil)` 构造
#### Scenario: 文档生成不执行 Handler 逻辑
- **WHEN** 为文档生成构造 PersonalCustomer handler
- **THEN** 所有依赖参数传入 `nil`
- **AND** 文档生成过程不会调用 handler 的实际业务逻辑
- **AND** nil 依赖不会导致 panic
### Requirement: 路由注册调用方式更新
`internal/routes/routes.go` 中对 `RegisterPersonalRoutes` 的调用 SHALL 传入正确的参数。
#### Scenario: routes.go 传入 doc 参数
- **WHEN** 在 `routes.go` 中调用 `RegisterPersonalRoutes`
- **THEN** 传入 `doc *openapi.Generator` 参数
- **AND** 传入 basePath（如 `/api/c/v1`）
- **AND** 传入 handlers
#### Scenario: 文档生成时调用 RegisterPersonalRoutes
- **WHEN** 文档生成流程调用路由注册
- **THEN** `RegisterPersonalRoutes` 被调用
- **AND** 个人客户路由被注册到文档生成器
- **AND** 不启动 Fiber 服务器
### Requirement: 向后兼容性
路由注册方式的改造 SHALL 保持 API 行为不变。
#### Scenario: 改造后 API 响应格式不变
- **WHEN** 改造路由注册方式
- **THEN** API 的响应格式与改造前一致
- **AND** 响应包含 envelope：`{code, msg, data, timestamp}`
#### Scenario: 改造后路径不变
- **WHEN** 改造路由注册方式
- **THEN** 所有路径保持 `/api/c/v1/xxx` 格式
- **AND** 客户端无需修改请求 URL
#### Scenario: 改造后认证逻辑不变
- **WHEN** 改造路由注册方式
- **THEN** 认证中间件继续生效
- **AND** 需要认证的接口仍需提供有效 Token
- **AND** 认证失败时返回 401 错误
---
### Requirement: 微信标识索引策略
系统 MUST 将 `tb_personal_customer.wx_open_id` 的索引从唯一索引调整为普通索引：删除 `uniqueIndex`，改为 `index`。
#### Scenario: 多条记录允许相同 wx_open_id
- **WHEN** 数据库中写入两条具有相同 `wx_open_id` 的个人客户记录
- **THEN** 数据库层 MUST 不再因唯一约束报错
#### Scenario: 查询性能仍受索引保障
- **WHEN** 按 `wx_open_id` 执行查询
- **THEN** 系统 MUST 继续命中普通索引以保障查询性能
### Requirement: 个人客户登录主流程改为微信授权
系统 SHALL 将个人客户登录主流程从“手机号 + 验证码登录”调整为“资产验证 + 微信授权登录”。
- 新登录入口：
- `POST /api/c/v1/auth/verify-asset`（A1，无认证）
- `POST /api/c/v1/auth/wechat-login`（A2，无认证）
- `POST /api/c/v1/auth/miniapp-login`（A3，无认证）
- 请求与响应要点：
- A2/A3 请求体 MUST 包含 `code` 与 `asset_token`
- A2/A3 响应体 MUST 包含 `token`、`need_bind_phone`、`is_new_user`
- 错误码：
- `1006` 参数错误
- `1002` token 无效或过期
- `1040` 微信授权失败
#### Scenario: 通过微信授权完成登录
- **WHEN** 用户先完成 A1，再提交 A2 或 A3
- **THEN** 系统 SHALL 完成客户识别/创建、资产绑定并返回登录 token
#### Scenario: 不再支持旧手机号直登入口
- **WHEN** 客户端调用旧手机号登录路径（如 `/api/c/v1/login`）
- **THEN** 系统 MUST 按新路由规范拒绝或迁移提示，不再作为主登录路径
### Requirement: 手机号从“登录凭据”调整为“登录后补充资料”
系统 MUST 将手机号能力调整为登录后绑定/换绑，而非登录入口。
- 相关接口：
- `POST /api/c/v1/auth/send-code`（A4，无认证）
- `POST /api/c/v1/auth/bind-phone`（A5，需认证）
- `POST /api/c/v1/auth/change-phone`（A6，需认证）
- 响应字段：
- A5/A6 MUST 返回绑定后的 `phone`
#### Scenario: 首次登录后要求绑定手机号
- **WHEN** `client.require_phone_binding=true` 且用户未绑定手机号
- **THEN** 登录响应 MUST 返回 `need_bind_phone=true`
- **THEN** 用户通过 A4+A5 完成绑定后进入业务页面
### Requirement: 微信身份字段迁移到 OpenID 关联能力
系统 SHALL 保留 `PersonalCustomer.wx_open_id` 与 `wx_union_id` 字段的兼容性，但新登录链路 MUST 以 `PersonalCustomerOpenID` 为主。
#### Scenario: 读取用户微信身份
- **WHEN** 登录流程需要按微信身份识别客户
- **THEN** 系统 MUST 优先查询 `PersonalCustomerOpenID`
- **THEN** 不再依赖 `PersonalCustomer` 单字段承载多 AppID 场景
---
### Requirement: 换货迁移时更新个人客户资产绑定
系统 SHALL 在 H5 全量迁移成功后，更新 `PersonalCustomerDevice` 的资产标识绑定关系：
- 若旧资产存在客户绑定，绑定中的 `virtual_no` MUST 更新为新资产 `virtual_no`
- 更新后客户对资产访问连续，不需重新登录即可看到新资产
#### Scenario: 迁移后客户绑定跟随新资产
- **WHEN** 旧资产存在个人客户绑定且执行了 `migrate_data=true`
- **THEN** 系统 MUST 将绑定记录的 `virtual_no` 更新为新资产虚拟号
---
### Requirement: 转新时清除个人客户绑定
系统 SHALL 在 H7 转新时清除该资产在 `PersonalCustomerDevice` 中的绑定关系，避免旧客户继续访问新代际资产。
#### Scenario: 转新后旧客户需重新绑定
- **WHEN** 资产转新完成
- **THEN** 系统 MUST 删除或失效对应客户绑定，使旧客户再次访问时触发重新绑定流程
Reference in New Issue View Git Blame Copy Permalink