归档

openspec/specs/api-doc-coverage/spec.md

@@ -0,0 +1,45 @@
+# API 文档完整性规范
+
+## MODIFIED Requirements
+
+### Requirement: OpenAPI 文档 100% 覆盖所有路由接口
+
+系统的 OpenAPI 文档应包含所有已注册的 HTTP 路由接口，覆盖率达到 100%。
+
+#### Scenario: 文档注册所有 Handler
+
+- **WHEN** 系统启动或生成 OpenAPI 文档
+- **THEN** `cmd/api/docs.go` 中的 `bootstrap.Handlers` 结构体包含全部 48 个 Handler（包括 Account、AdminOrder、AgentRecharge、Asset、AssetWallet 等）
+- **THEN** 每个 Handler 对应一个已注册的路由组（如 `/api/admin/accounts` → `handlers.Account`）
+- **THEN** 生成的 OpenAPI 文档包含这 48 个 Handler 对应的全部接口
+
+#### Scenario: 新增 Handler 时同步文档生成器
+
+- **WHEN** 开发者在 `internal/router/` 中新增一个 Handler 并注册到路由
+- **THEN** 开发者必须同时在 `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 中的 `bootstrap.Handlers` 结构体添加该 Handler 字段
+- **THEN** 若遗漏，代码审查应拒绝合并（检查清单项：**新增 Handler 时是否同步更新 docs.go/gendocs/main.go**）
+
+#### Scenario: OpenAPI 文档校验完整性
+
+- **WHEN** 执行 `go run cmd/gendocs/main.go` 生成 OpenAPI 文档
+- **THEN** 文档应包含所有已注册的接口路由
+- **THEN** 无"缺失文档"的警告或错误信息
+
+### Requirement: 文档生成器不遗漏 Handler
+
+文档生成器的 `bootstrap.Handlers` 结构体应显式列出所有 Handler，避免新增后遗漏。
+
+#### Scenario: 完整的 Handler 清单
+
+- **WHEN** 审阅 `cmd/api/docs.go` 的 `bootstrap.Handlers` 结构体定义
+- **THEN** 该结构体包含以下字段（至少 48 个，按模块分组）：
+  ```go
+  Account               *admin.AccountHandler
+  AdminOrder           *admin.OrderHandler
+  AgentRecharge        *agent.RechargeHandler
+  Asset                *admin.AssetHandler
+  AssetWallet          *admin.AssetWalletHandler
+  Authorization        *admin.AuthorizationHandler
+  // ... 共 48 个
+  ```
+- **THEN** 注释中标注每个 Handler 对应的路由前缀和功能模块

openspec/specs/dto-name-fields/spec.md

@@ -0,0 +1,83 @@
+# Response DTO 规范规范
+
+## MODIFIED Requirements
+
+### Requirement: Response DTO 必须包含状态文字字段
+
+项目所有 Response DTO 中，若包含 int 类型状态字段，必须同时包含对应的 `_name` 或 `_text` 文字字段，用于显示该状态的中文描述。
+
+#### Scenario: 账号列表 Response DTO
+
+- **WHEN** API 返回账号列表（`GET /api/admin/accounts`）
+- **THEN** 响应中每个账号对象包含 `status` 字段（int，值：0=禁用，1=启用）
+- **THEN** 响应中同时包含 `status_name` 字段（string，值："禁用"或"启用"）
+- **THEN** 前端可直接使用 `status_name` 显示在 UI 上，无需维护单独的状态枚举映射表
+
+#### Scenario: 资产详情 Response DTO
+
+- **WHEN** API 返回单个资产信息（`GET /api/admin/assets/:id`）
+- **THEN** 响应包含 `status`（int）和 `status_name`（string）
+- **WHEN** 资产包含多个状态字段（如 `network_status`、`activation_status`、`online_status`）
+- **THEN** 每个状态字段对应一个文字字段：`network_status_name`、`activation_status_name`、`online_status_name`
+
+#### Scenario: 订单详情中的多重状态
+
+- **WHEN** API 返回订单详情（`GET /api/admin/orders/:id`）
+- **THEN** 订单对象包含 `payment_status`（int）和 `payment_status_name`（string）
+- **THEN** 订单对象包含 `commission_status`（int）和 `commission_status_name`（string）
+- **THEN** 若订单还有其他 int 类型状态字段，均配有对应的 `_name` 字段
+
+### Requirement: DTO 文字字段命名规则
+
+状态文字字段的命名应遵循统一规则：`{状态字段名}_name` 或 `{状态字段名}_text`。
+
+#### Scenario: 标准命名
+
+- **WHEN** 定义 DTO 时，状态字段为 `Status`
+- **THEN** 文字字段命名为 `StatusName`（推荐）或 `StatusText`
+- **WHEN** 状态字段为 `PaymentStatus`
+- **THEN** 文字字段命名为 `PaymentStatusName` 或 `PaymentStatusText`
+
+#### Scenario: JSON 序列化一致性
+
+- **WHEN** DTO 序列化为 JSON 返回给客户端
+- **THEN** 字段名使用 snake_case（符合项目 API 规范）
+  - Go 字段 `Status` → JSON `status`
+  - Go 字段 `StatusName` → JSON `status_name`
+
+### Requirement: Service 层自动赋值 `_name` 字段
+
+Service 层在构建 Response DTO 时，应自动赋值 `_name`/`_text` 字段，映射状态常量到中文描述。
+
+#### Scenario: 获取账号详情自动赋值
+
+- **WHEN** `AccountService.GetAccount(ctx, accountID)` 被调用
+- **THEN** Service 查询数据库获取账号信息
+- **THEN** Service 构建 Response DTO，自动设置 `StatusName = constants.GetAccountStatusName(account.Status)`
+- **THEN** 返回完整的 DTO 给 Handler，Handler 直接序列化响应
+
+#### Scenario: 列表查询批量赋值
+
+- **WHEN** `AccountService.ListAccounts(ctx, query)` 被调用
+- **THEN** Service 查询数据库获取账号列表
+- **THEN** Service 遍历每个账号，批量赋值 `StatusName` 字段
+- **THEN** 返回完整列表
+
+### Requirement: 常量映射函数
+
+在 `pkg/constants/` 中为每个业务模块定义 `Get{Module}StatusName(status int) string` 函数，用于映射状态值到中文描述。
+
+#### Scenario: 账号状态映射函数
+
+- **WHEN** Service 层需要获取账号状态的中文描述
+- **THEN** 调用 `constants.GetAccountStatusName(status)`
+- **THEN** 函数返回：
+  - 若 `status == 0`，返回 `"禁用"`
+  - 若 `status == 1`，返回 `"启用"`
+  - 若状态值未知，返回 `"未知"`（不返回空字符串）
+
+#### Scenario: 订单支付状态映射函数
+
+- **WHEN** Service 层需要获取订单支付状态描述
+- **THEN** 调用 `constants.GetOrderPaymentStatusName(status)`
+- **THEN** 函数返回对应的中文（如 "待支付"、"已支付"、"已完成" 等）

openspec/specs/payment-dynamic-config/spec.md

@@ -0,0 +1,69 @@
+# 支付配置动态加载能力规范
+
+## ADDED Requirements
+
+### Requirement: 从支付配置 ID 动态加载支付实例
+
+系统在处理支付验签（订单支付回调、充值确认等）时，应根据订单/充值记录中的 `payment_config_id` 字段动态加载对应的支付配置，而不是使用全局单例 `s.wechatPayment`。
+
+#### Scenario: 订单支付回调验签
+
+- **WHEN** 微信支付回调到达 `/api/callback/wechat`，系统解析回调中的商户号和订单数据
+- **THEN** 系统根据订单表中的 `payment_config_id` 从 Redis（TTL 1h）或数据库加载对应的支付配置
+- **THEN** 系统使用该配置的私钥和证书验签回调数据
+- **THEN** 若配置不存在或当前用户无权限访问该配置，返回 `{code: 1103, msg: "支付配置不存在或无权限"}`
+
+#### Scenario: 充值订单确认支付
+
+- **WHEN** 代理用户在充值页面点击"确认支付"，提交 `recharge_order_id` 和 `amount`
+- **THEN** 系统根据充值订单表中的 `payment_config_id` 动态加载支付配置
+- **THEN** 系统调用该配置对应的支付 SDK 创建预支付单（微信 JSAPI 或 H5）
+- **THEN** 若配置无效或超配额，返回 `{code: 1103, msg: "支付配置无效，请联系商户"}`
+
+### Requirement: 支付配置 Redis 缓存
+
+系统应缓存支付配置到 Redis，减少数据库查询。
+
+#### Scenario: 首次加载配置
+
+- **WHEN** 调用 `PaymentConfigLoader.LoadConfig(ctx, configID)` 且 Redis 中不存在该配置
+- **THEN** 系统从数据库查询配置，存入 Redis（key: `payment:config:{configID}`，TTL: 1 小时）
+- **THEN** 返回加载的配置对象
+
+#### Scenario: 配置缓存命中
+
+- **WHEN** 调用 `PaymentConfigLoader.LoadConfig(ctx, configID)` 且 Redis 中存在该配置
+- **THEN** 系统直接返回 Redis 中缓存的配置
+- **THEN** 不查询数据库
+
+#### Scenario: 配置变更后清除缓存
+
+- **WHEN** 支付配置被修改（通过管理后台）
+- **THEN** 系统主动删除 Redis 中的该配置缓存（`DEL payment:config:{configID}`）
+- **THEN** 下次加载时重新从数据库读取最新配置
+
+### Requirement: 支付配置访问控制
+
+系统在加载支付配置时，根据调用场景采用不同的校验策略：
+
+> **场景分类说明**：
+> - **回调场景**：微信支付回调到达 `/api/callback/wechat`，请求来自微信服务器，无登录态，无用户身份上下文
+> - **用户操作场景**：代理用户在前端主动发起的支付相关操作（如创建充值单、查询支付配置等），有完整的登录态和用户上下文
+
+#### Scenario: 回调场景 — 商户号一致性校验
+
+- **WHEN** 微信支付回调到达，系统解析回调中的商户号（`mchid`）
+- **THEN** 系统根据订单的 `payment_config_id` 加载配置，比较配置中存储的商户号与回调携带的商户号是否一致
+- **THEN** 若不一致，记录告警日志并拒绝处理，返回非 2xx 状态码（微信会重试）
+- **NOTE** 此场景**不做用户身份鉴权**，无"代理 A/B"概念，只做商户号匹配验证
+
+#### Scenario: 用户操作场景 — 归属权限校验
+
+- **WHEN** 代理用户在前端主动操作（如创建充值单）需加载支付配置
+- **THEN** 系统检查该配置的归属（`shop_id` 或 `enterprise_id`）与当前登录用户是否匹配
+- **THEN** 若当前用户无权访问该配置，返回 `{code: 403, msg: "无权限访问该支付配置"}`
+
+#### Scenario: 平台用户无限制访问
+
+- **WHEN** 平台管理员的操作需要加载任意支付配置
+- **THEN** 系统跳过归属权限检查，允许访问所有配置（仅限用户操作场景）

openspec/specs/polling-status-constants/spec.md

@@ -0,0 +1,44 @@
+# 轮询触发日志状态常量规范
+
+## ADDED Requirements
+
+### Requirement: 轮询手动触发日志状态常量
+
+系统应在 `pkg/constants/polling.go` 中定义轮询手动触发日志的四种状态常量，避免硬编码字符串。
+
+**常量定义**：
+- `PollingManualTriggerStatusPending = "pending"`
+- `PollingManualTriggerStatusProcessing = "processing"`
+- `PollingManualTriggerStatusCompleted = "completed"`
+- `PollingManualTriggerStatusCancelled = "cancelled"`
+
+#### Scenario: 轮询触发日志记录使用常量
+
+- **WHEN** 系统记录轮询手动触发日志（插入、更新状态）
+- **THEN** 系统使用 `constants.PollingManualTriggerStatusPending` 等常量，而不是直接写字符串 `"pending"`
+
+#### Scenario: 轮询触发日志查询使用常量
+
+- **WHEN** 系统查询轮询日志（按状态筛选、状态转移判断等）
+- **THEN** 系统使用常量进行比较，而不是硬编码 `status == "pending"`
+
+#### Scenario: 常量修改时自动重构
+
+- **WHEN** 业务要求修改某个状态值（如 `"pending"` → `"awaiting"`）
+- **THEN** 开发者修改 `pkg/constants/polling.go` 中的常量定义
+- **THEN** IDE 自动检测所有使用该常量的代码，支持一键重构替换
+- **THEN** 无需手动搜索和替换散落在各文件中的硬编码字符串
+
+### Requirement: 轮询触发日志字段描述
+
+轮询手动触发日志模型（`tb_polling_manual_trigger_log`）应包含 `status` 字段，并在 DTO 中加入 `status_name` 文字字段。
+
+#### Scenario: 查询轮询触发日志返回状态文本
+
+- **WHEN** API 返回轮询手动触发日志列表（`GET /api/admin/polling/manual-triggers`）
+- **THEN** 响应中的 `status` 字段（int）对应状态常量值
+- **THEN** 响应中的 `status_name` 字段（string）显示该状态的中文描述
+  - `"pending"` → `"待处理"`
+  - `"processing"` → `"处理中"`
+  - `"completed"` → `"已完成"`
+  - `"cancelled"` → `"已取消"`