huang
95fc0b0a1b
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 8m16s
52 lines
5.2 KiB
Markdown
52 lines
5.2 KiB
Markdown
## 1. 数据模型、常量和错误码
|
||
|
||
- [x] 1.1 不新增开放接口账号授权表；所有启用的代理账号默认可调用开放接口，继续复用 `tb_account` 和店铺数据权限。
|
||
- [x] 1.2 复用现有 `Account` 与 `Shop` 模型，不新增开放接口授权模型。
|
||
- [x] 1.3 复用现有 `AccountStore` 和 `ShopStore` 查询账号与下级店铺，不新增开放接口授权 Store。
|
||
- [x] 1.4 在 `pkg/constants/` 新增开放接口 Header 名称、签名时间窗、批次号前缀、Redis nonce key 生成函数等常量，并为所有常量添加中文注释。
|
||
- [x] 1.5 在 `pkg/errors/` 新增开放接口认证、签名无效、时间戳无效、nonce 重放等错误码和中文错误消息。
|
||
- [x] 1.6 验证：运行 `gofmt` 覆盖新增 Go 文件，运行 `go build ./cmd/api` 确认基础模型与常量可编译。
|
||
|
||
## 2. 开放接口签名认证中间件
|
||
|
||
- [x] 2.1 新增开放接口认证中间件，解析 `X-Agent-Account`、`X-Agent-Password`、`X-Agent-Timestamp`、`X-Agent-Nonce`、`X-Agent-Sign`。
|
||
- [x] 2.2 实现签名原文构造：方法、路径、排序后的 query、body SHA256、时间戳、nonce、账号，排除 `sign` 字段。
|
||
- [x] 2.3 使用 bcrypt 校验后台账号密码，使用 HMAC-SHA256 重算签名，并用常量时间比较校验签名。
|
||
- [x] 2.4 使用 Redis `SET NX` 写入开放接口 nonce，按签名时间窗设置 TTL，拒绝重复 nonce。
|
||
- [x] 2.5 校验账号类型、账号状态和关联店铺状态；所有启用代理账号默认允许调用开放接口。
|
||
- [x] 2.6 认证通过后注入代理上下文：用户ID、用户类型、店铺ID、下级店铺ID列表，保证现有权限过滤可复用。
|
||
- [x] 2.7 对开放接口密码、签名、nonce 等敏感字段做日志脱敏，避免访问日志和错误日志泄露。
|
||
- [ ] 2.8 验证：使用构造好的签名请求和篡改参数请求，通过 curl 手动确认成功、签名失败、nonce 重放、密码错误、非代理账号、禁用账号等分支。
|
||
|
||
## 3. DTO 与开放接口业务服务
|
||
|
||
- [x] 3.1 新增开放接口 DTO：卡流量、卡状态、实名状态、套餐列表、钱包购买、钱包余额、钱包流水的请求和响应结构，description 使用中文。
|
||
- [x] 3.2 新增 `agent_open_api.Service`，通过结构体字段注入账号、店铺、卡、套餐、钱包、订单等现有 Store/Service。
|
||
- [x] 3.3 实现单卡标识解析逻辑：支持 ICCID、虚拟号、MSISDN，必须解析为 IoT 卡，设备标识返回参数错误。
|
||
- [x] 3.4 实现卡流量查询：查询生效和待生效 `PackageUsage`，补充套餐编码和系列名称，只返回真实业务口径流量字段，不返回虚流量内部字段。
|
||
- [x] 3.5 实现卡状态查询：按 `network_status` 映射正常/停机，并返回停机原因。
|
||
- [x] 3.6 实现卡实名状态查询：按 `real_name_status` 返回 `is_realnamed`。
|
||
- [x] 3.7 实现代理套餐列表：复用代理套餐过滤和生效零售价逻辑，分页返回套餐ID、编码、名称、系列、类型、成本价、生效零售价、总流量、有效天数。
|
||
- [x] 3.8 实现预充值钱包余额查询：主钱包不存在时返回 0 余额，存在时返回余额、冻结余额、可用余额和币种。
|
||
- [x] 3.9 实现预充值钱包流水查询：复用主钱包流水字段和过滤条件，只查询当前代理主钱包。
|
||
- [x] 3.10 实现钱包套餐购买：按单个套餐编码解析套餐，逐张卡调用后台钱包订单创建逻辑，记录每张卡成功订单号或失败原因，允许部分成功。
|
||
- [ ] 3.11 验证：使用 PostgreSQL MCP 或 SQL 查询核对套餐、卡、钱包和订单数据；使用 curl 手动核对所有开放接口响应字段和错误分支。
|
||
|
||
## 4. Handler、路由和依赖注入
|
||
|
||
- [x] 4.1 新增 `internal/handler/openapi` 包，实现开放接口 Handler，Handler 只负责参数解析、校验和统一响应。
|
||
- [x] 4.2 新增 `internal/routes/open.go`，注册 `/api/open/v1` 路由组和全部 7 个开放接口。
|
||
- [x] 4.3 更新 `internal/routes/routes.go`，在总路由入口挂载开放接口路由和签名认证中间件。
|
||
- [x] 4.4 更新 `internal/bootstrap/types.go`、`internal/bootstrap/services.go`、`internal/bootstrap/handlers.go`，完成开放接口 Service、Store、Handler 的结构体字段注入。
|
||
- [x] 4.5 更新 `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 的 `bootstrap.Handlers` 初始化，确保新增 Handler 进入文档生成器。
|
||
- [x] 4.6 验证：运行 `go build ./cmd/api` 和 `go build ./cmd/gendocs`，确认路由、依赖注入和文档入口可编译。
|
||
|
||
## 5. 文档、索引和最终验证
|
||
|
||
- [x] 5.1 新增 `docs/agent-open-api/功能总结.md`，说明签名规则、字段口径、接口列表、错误码和对接示例。
|
||
- [x] 5.2 更新 README 或接口文档索引，加入代理开放接口文档入口。
|
||
- [x] 5.3 运行 OpenAPI 文档生成命令，确认 `/api/open/v1` 下全部接口出现在文档中。
|
||
- [x] 5.4 运行 `openspec validate add-agent-open-api --strict`，修正 OpenSpec 结构问题。
|
||
- [x] 5.5 运行 `ccc index` 更新代码索引。
|
||
- [ ] 5.6 最终验证：手动执行签名成功、签名失败、卡流量、卡状态、实名状态、套餐列表、钱包余额、钱包流水、多卡部分成功购买、余额不足购买等场景，并记录验证结果。
|