csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

重置项目上下文与规范文档

Browse Source
This commit is contained in:
break
2026-08-07 16:18:07 +08:00
parent 6611ca5226
commit 79e2d9ff92
1900 changed files with 1552 additions and 348365 deletions
Download Patch File Download Diff File Expand all files Collapse all files

453
openspec/specs/personal-customer/spec.md
View File

@@ -1,448 +1,59 @@
# personal-customer Specification
# personal-customer 当前行为
## Purpose
TBD - created by archiving change add-personal-customer-wechat. Update Purpose after archive.
描述个人客户身份与资产归属隔离的当前行为。
## Requirements
### Requirement: 短信验证码服务
系统 SHALL 提供短信验证码服务，对接行业短信平台，支持发送验证码到指定手机号，验证码存储在 Redis 中并设置过期时间。
### Requirement: 个人客户身份
#### 短信服务对接规范
系统 SHALL 支持个人客户通过既有认证入口登录、退出并查询当前资料。
**短信服务商**: 武汉聚惠富通（行业短信）
**接口网关**: `https://gateway.sms.whjhft.com:8443/sms`
**协议版本**: HTTP JSON API v1.6
**接口文档**: 参考 `docs/第三方文档/SMS_HTTP_1.6.md`
#### Scenario: 个人客户身份
**使用接口**: 短信批量发送接口 `/api/sendMessageMass`
- **GIVEN** 个人客户提供有效登录材料
- **WHEN** 请求认证
- **THEN** 系统返回个人客户身份和访问凭证
**发送方式**: 直接发送内容（不使用短信模板）
### Requirement: 资产归属查询
**短信内容格式**: `【签名】自定义内容`
- 签名部分（如 `【签名】`）需提前向服务商报备并审核通过
- 自定义内容为实际短信文本
- 示例: `【签名】您的验证码是123456，5分钟内有效`
系统 SHALL 只向个人客户返回当前绑定或可识别的卡与设备资产。
**请求参数规范**:
```json
{
"userName": "账号用户名（从配置读取）",
"content": "【签名】您的验证码是{验证码}，5分钟内有效",
"phoneList": ["13500000001"],
"timestamp": 1596254400000, // 当前时间戳（毫秒）
"sign": "e315cf297826abdeb2092cc57f29f0bf" // MD5(userName + timestamp + MD5(password))
}
```
#### Scenario: 资产归属查询
**Sign 计算规则**:
- 计算方式: `MD5(userName + timestamp + MD5(password))`
- 示例:
- `userName = "test"`
- `password = "123"`
- `timestamp = 1596254400000`
- `MD5(password) = "202cb962ac59075b964b07152d234b70"`
- `组合字符串 = "test1596254400000202cb962ac59075b964b07152d234b70"`
- `sign = MD5(组合字符串) = "e315cf297826abdeb2092cc57f29f0bf"`
- **GIVEN** 客户已认证
- **WHEN** 查询资产列表或详情
- **THEN** 返回该客户可见的资产而不包含其他客户资产
**响应格式**:
```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
```
本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
**错误处理**:
- `code=0`: 发送成功
- `code=5`: 账号余额不足（记录错误日志，返回用户友好提示）
- `code=16`: 时间戳差异过大（检查服务器时间）
- 其他错误码: 参考文档第13节"响应状态码列表"
### 个人客户 - 认证
**重要说明**:
- 本系统使用直接内容发送方式,不使用短信模板
- 请求中只需要 `content` 字段,不需要 `templateId` 和 `params` 参数
- 短信内容必须包含已报备的签名,格式为 `【签名】` + 自定义文本
`POST /api/c/v1/auth/bind-phone`（绑定手机号）；`POST /api/c/v1/auth/change-phone`（更换手机号）；`POST /api/c/v1/auth/logout`（退出登录）；`POST /api/c/v1/auth/miniapp-login`（小程序登录）；`POST /api/c/v1/auth/send-code`（发送验证码）；`POST /api/c/v1/auth/verify-asset`（资产验证）；`POST /api/c/v1/auth/wechat-login`（公众号登录）。仅在开发模式开启时，系统 SHALL 额外提供 `POST /api/c/v1/auth/dev-login`。
#### Scenario: 发送验证码成功
- **WHEN** 用户请求发送验证码到有效手机号
- **THEN** 系统生成6位数字验证码，存储到 Redis（过期时间5分钟），调用短信服务发送
### 个人客户 - 账户
#### Scenario: 验证码频率限制
- **WHEN** 用户在60秒内重复请求发送验证码
- **THEN** 系统拒绝请求并返回错误"请60秒后再试"
`GET /api/c/v1/profile`（获取个人资料）；`PUT /api/c/v1/profile`（更新个人资料）。
#### Scenario: 短信发送失败
- **WHEN** 短信服务返回错误（如余额不足、账号异常等）
- **THEN** 系统记录错误日志，返回用户友好提示"短信发送失败，请稍后重试"
### 个人客户 - 微信
#### Scenario: 验证码验证成功
- **WHEN** 用户提交正确的验证码
- **THEN** 系统验证通过并删除 Redis 中的验证码
`GET /api/c/v1/wechat/appid`（获取当前生效的公众号 AppID）；`GET /api/c/v1/wechat/jssdk-config`（获取微信 JSSDK 签名配置）。
#### Scenario: 验证码验证失败
- **WHEN** 用户提交错误的验证码
- **THEN** 系统返回错误"验证码错误"
### 个人客户 - 资产
#### Scenario: 验证码过期
- **WHEN** 用户提交的验证码已超过5分钟
- **THEN** 系统返回错误"验证码已过期"
`GET /api/c/v1/asset/info`（资产信息）；`GET /api/c/v1/asset/package-history`（资产套餐历史）；`GET /api/c/v1/asset/packages`（资产可购套餐列表）；`POST /api/c/v1/asset/refresh`（资产刷新）。
---
### 个人客户 - 设备
### Requirement: 个人客户登录流程
`GET /api/c/v1/device/cards`（获取设备卡列表）；`POST /api/c/v1/device/factory-reset`（恢复出厂设置）；`POST /api/c/v1/device/reboot`（设备重启）；`POST /api/c/v1/device/switch-card`（设备切卡）；`POST /api/c/v1/device/wifi`（设备WiFi配置）。
系统 SHALL 支持个人客户通过 ICCID（网卡号）或 IMEI（设备号）登录，首次登录需绑定手机号并验证。
### 个人客户 - 实名
#### Scenario: 已绑定用户登录
- **WHEN** 用户输入 ICCID/IMEI，且该 ICCID/IMEI 已绑定手机号
- **THEN** 系统发送验证码到已绑定手机号，用户验证后登录成功
`GET /api/c/v1/realname/link`（获取实名认证链接）。
#### 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 删除或失效对应客户绑定，使旧客户再次访问时触发重新绑定流程
### 个人客户 - 换货
`POST /api/c/v1/exchange/{id}/shipping-info`（提交收货信息）；`GET /api/c/v1/exchange/pending`（查询待处理换货单）。