huang
95fc0b0a1b
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 8m16s
3.2 KiB
3.2 KiB
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 写入。
- 流量查询按单卡读取当前/待生效套餐，避免设备级聚合和大范围扫描。