junhong_cmp_fiber/openspec/changes/archive/2026-05-11-add-agent-open-api/tasks.md

1. 数据模型、常量和错误码

• 1.1 不新增开放接口账号授权表；所有启用的代理账号默认可调用开放接口，继续复用 tb_account 和店铺数据权限。
• 1.2 复用现有 Account 与 Shop 模型，不新增开放接口授权模型。
• 1.3 复用现有 AccountStore 和 ShopStore 查询账号与下级店铺，不新增开放接口授权 Store。
• 1.4 在 pkg/constants/ 新增开放接口 Header 名称、签名时间窗、批次号前缀、Redis nonce key 生成函数等常量，并为所有常量添加中文注释。
• 1.5 在 pkg/errors/ 新增开放接口认证、签名无效、时间戳无效、nonce 重放等错误码和中文错误消息。
• 1.6 验证：运行 gofmt 覆盖新增 Go 文件，运行 go build ./cmd/api 确认基础模型与常量可编译。

2. 开放接口签名认证中间件

• 2.1 新增开放接口认证中间件，解析 X-Agent-Account、X-Agent-Password、X-Agent-Timestamp、X-Agent-Nonce、X-Agent-Sign。
• 2.2 实现签名原文构造：方法、路径、排序后的 query、body SHA256、时间戳、nonce、账号，排除 sign 字段。
• 2.3 使用 bcrypt 校验后台账号密码，使用 HMAC-SHA256 重算签名，并用常量时间比较校验签名。
• 2.4 使用 Redis SET NX 写入开放接口 nonce，按签名时间窗设置 TTL，拒绝重复 nonce。
• 2.5 校验账号类型、账号状态和关联店铺状态；所有启用代理账号默认允许调用开放接口。
• 2.6 认证通过后注入代理上下文：用户ID、用户类型、店铺ID、下级店铺ID列表，保证现有权限过滤可复用。
• 2.7 对开放接口密码、签名、nonce 等敏感字段做日志脱敏，避免访问日志和错误日志泄露。
• 2.8 验证：使用构造好的签名请求和篡改参数请求，通过 curl 手动确认成功、签名失败、nonce 重放、密码错误、非代理账号、禁用账号等分支。

3. DTO 与开放接口业务服务

• 3.1 新增开放接口 DTO：卡流量、卡状态、实名状态、套餐列表、钱包购买、钱包余额、钱包流水的请求和响应结构，description 使用中文。
• 3.2 新增 agent_open_api.Service，通过结构体字段注入账号、店铺、卡、套餐、钱包、订单等现有 Store/Service。
• 3.3 实现单卡标识解析逻辑：支持 ICCID、虚拟号、MSISDN，必须解析为 IoT 卡，设备标识返回参数错误。
• 3.4 实现卡流量查询：查询生效和待生效 PackageUsage，补充套餐编码和系列名称，只返回真实业务口径流量字段，不返回虚流量内部字段。
• 3.5 实现卡状态查询：按 network_status 映射正常/停机，并返回停机原因。
• 3.6 实现卡实名状态查询：按 real_name_status 返回 is_realnamed。
• 3.7 实现代理套餐列表：复用代理套餐过滤和生效零售价逻辑，分页返回套餐ID、编码、名称、系列、类型、成本价、生效零售价、总流量、有效天数。
• 3.8 实现预充值钱包余额查询：主钱包不存在时返回 0 余额，存在时返回余额、冻结余额、可用余额和币种。
• 3.9 实现预充值钱包流水查询：复用主钱包流水字段和过滤条件，只查询当前代理主钱包。
• 3.10 实现钱包套餐购买：按单个套餐编码解析套餐，逐张卡调用后台钱包订单创建逻辑，记录每张卡成功订单号或失败原因，允许部分成功。
• 3.11 验证：使用 PostgreSQL MCP 或 SQL 查询核对套餐、卡、钱包和订单数据；使用 curl 手动核对所有开放接口响应字段和错误分支。

4. Handler、路由和依赖注入

• 4.1 新增 internal/handler/openapi 包，实现开放接口 Handler，Handler 只负责参数解析、校验和统一响应。
• 4.2 新增 internal/routes/open.go，注册 /api/open/v1 路由组和全部 7 个开放接口。
• 4.3 更新 internal/routes/routes.go，在总路由入口挂载开放接口路由和签名认证中间件。
• 4.4 更新 internal/bootstrap/types.go、internal/bootstrap/services.go、internal/bootstrap/handlers.go，完成开放接口 Service、Store、Handler 的结构体字段注入。
• 4.5 更新 cmd/api/docs.go 和 cmd/gendocs/main.go 的 bootstrap.Handlers 初始化，确保新增 Handler 进入文档生成器。
• 4.6 验证：运行 go build ./cmd/api 和 go build ./cmd/gendocs，确认路由、依赖注入和文档入口可编译。

5. 文档、索引和最终验证

• 5.1 新增 docs/agent-open-api/功能总结.md，说明签名规则、字段口径、接口列表、错误码和对接示例。
• 5.2 更新 README 或接口文档索引，加入代理开放接口文档入口。
• 5.3 运行 OpenAPI 文档生成命令，确认 /api/open/v1 下全部接口出现在文档中。
• 5.4 运行 openspec validate add-agent-open-api --strict，修正 OpenSpec 结构问题。
• 5.5 运行 ccc index 更新代码索引。
• 5.6 最终验证：手动执行签名成功、签名失败、卡流量、卡状态、实名状态、套餐列表、钱包余额、钱包流水、多卡部分成功购买、余额不足购买等场景，并记录验证结果。