huang
95fc0b0a1b
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 8m16s
48 lines
3.2 KiB
Markdown
48 lines
3.2 KiB
Markdown
## Why
|
||
|
||
现有代理商需要通过开放接口对接套餐购买、卡状态、流量、实名和预充值钱包数据，但当前能力主要面向后台管理端，依赖后台登录态，不适合直接给第三方系统调用。需要新增一套签名校验的代理开放接口，在不暴露虚流量语义的前提下复用现有代理套餐、钱包支付和卡套餐数据能力。
|
||
|
||
功能 ID：feature-20260511-agent-open-api
|
||
|
||
## What Changes
|
||
|
||
- 新增代理开放接口域，提供账号密码、请求参数、时间戳、随机串和 `sign` 的调用校验。
|
||
- 新增单卡开放查询接口：卡流量查询、卡状态查询、卡实名状态查询。
|
||
- 新增代理开放套餐列表接口，分页返回代理可购买套餐，复用后台代理套餐列表的权限过滤，并返回生效零售价。
|
||
- 新增代理预充值钱包开放接口：余额查询、流水列表查询。
|
||
- 新增代理钱包套餐购买开放接口：一次只允许一个套餐编码，支持多张卡分开购买，允许部分成功并返回失败卡原因。
|
||
- 流量展示对外只返回真实业务口径字段：总流量、换算后的已用流量、剩余流量；不暴露虚流量、展示倍率、停机阈值等内部字段。
|
||
- 新增开放接口 DTO、Handler、Service、Store/查询方法和路由注册，继续遵守 Handler → Service → Store → Model 分层。
|
||
- 新增接口文档注册，确保 OpenAPI 文档生成器包含开放接口。
|
||
- 不新增外部依赖，签名使用 Go 标准库 HMAC-SHA256；继续使用 Fiber、GORM、Viper、Zap、Redis。
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `agent-open-api`: 定义代理开放接口的认证签名、卡查询、套餐列表、钱包余额/流水和钱包购买套餐能力。
|
||
|
||
### Modified Capabilities
|
||
|
||
无。现有后台套餐、订单、钱包和资产查询能力仅作为实现复用点，不改变其既有接口契约。
|
||
|
||
## Impact
|
||
|
||
- 影响代码范围：
|
||
- `internal/handler/openapi/`：新增代理开放接口 Handler。
|
||
- `internal/service/agent_open_api/`：新增开放接口编排服务，复用套餐、订单、钱包、资产解析等现有服务。
|
||
- `internal/model/dto/`：新增开放接口请求和响应 DTO。
|
||
- `internal/model/`：复用现有账号、店铺、卡、套餐和钱包模型，不新增开放接口账号授权模型。
|
||
- `internal/store/postgres/`：复用现有账号和店铺 Store，必要时补充按套餐编码、卡标识、钱包流水的查询方法。
|
||
- `internal/routes/`：新增 `/api/open/v1` 路由组。
|
||
- `pkg/constants/`：新增开放接口相关常量、Redis nonce 防重放 key 生成函数。
|
||
- `pkg/errors/`：补充开放接口认证、签名、时间戳、重放相关错误码。
|
||
- `cmd/api/docs.go` 与 `cmd/gendocs/main.go`：注册新增 Handler，保证文档生成覆盖。
|
||
- 数据影响：
|
||
- 不新增开放接口账号授权表；所有启用状态的代理账号默认可调用开放接口。
|
||
- Redis 记录开放接口 nonce，防止时间窗内重放。
|
||
- 性能影响：
|
||
- 列表接口分页，默认 20，最大 100。
|
||
- 签名校验只做轻量 HMAC、bcrypt 校验和 Redis nonce 写入。
|
||
- 流量查询按单卡读取当前/待生效套餐，避免设备级聚合和大范围扫描。
|