junhong_cmp_fiber/openspec/specs/admin-order-creation/spec.md

Admin Order Creation

Purpose

后台订单创建流程，为代理和平台账号提供订单创建功能。与 H5 端订单创建的核心区别：后台仅支持 wallet/offline 支付方式，且 wallet 支付立即完成扣款和套餐激活（一步到位），不创建待支付订单。

This capability supports:

• 参数验证和支付方式限制
• 钱包余额检查和一步扣款
• 权限校验（代理、平台、超管）
• 错误处理和防御性编程

ADDED Requirements

Requirement: 后台订单创建 API 参数验证

系统 SHALL 在后台订单创建 API 中强制验证请求参数，拒绝非法的支付方式。

后台订单创建使用独立的 DTO（CreateAdminOrderRequest），仅允许 wallet 和 offline 两种支付方式。Handler 层 MUST 调用 middleware.ValidateStruct(&req) 验证参数，确保 DTO 的 validate:"oneof=wallet offline" 规则生效。

Scenario: DTO 验证拒绝非法支付方式

• WHEN 后台创建订单请求中 payment_method 为 wechat 或 alipay
• THEN 系统在 Handler 层验证失败，返回错误"请求参数解析失败"（CodeInvalidParam），订单创建失败

Scenario: DTO 验证拒绝空支付方式

• WHEN 后台创建订单请求中缺少 payment_method 字段或值为空字符串
• THEN 系统在 Handler 层验证失败，返回错误"请求参数解析失败"（CodeInvalidParam），订单创建失败

Scenario: DTO 验证允许 wallet 支付

• WHEN 后台创建订单请求中 payment_method 为 wallet
• THEN 系统通过 DTO 验证，继续后续业务逻辑

Scenario: DTO 验证允许 offline 支付

• WHEN 后台创建订单请求中 payment_method 为 offline
• THEN 系统通过 DTO 验证，继续后续业务逻辑

---

Requirement: 后台订单创建权限检查

系统 SHALL 在后台订单创建时完整检查支付方式权限，所有支付方式（包括非法的）都必须经过权限校验。

权限规则：

• offline 支付：仅超管和平台账号可用
• wallet 支付：代理、平台、超管均可用
• 其他支付方式：一律拒绝（兜底检查）

Scenario: 超管可以使用 offline 支付

• WHEN 超管账号创建订单，支付方式为 offline
• THEN 系统通过权限检查，继续创建订单

Scenario: 平台账号可以使用 offline 支付

• WHEN 平台账号创建订单，支付方式为 offline
• THEN 系统通过权限检查，继续创建订单

Scenario: 代理账号不能使用 offline 支付

• WHEN 代理账号创建订单，支付方式为 offline
• THEN 系统返回错误"只有平台可以使用线下支付"（CodeForbidden），订单创建失败

Scenario: 代理账号可以使用 wallet 支付

• WHEN 代理账号创建订单，支付方式为 wallet，钱包余额充足
• THEN 系统通过权限检查，继续创建订单

Scenario: 兜底检查拒绝其他支付方式

• WHEN 后台创建订单请求中 payment_method 为 wechat（虽然 DTO 验证应该已拒绝，但作为防御性编程）
• THEN 系统在 Handler 层返回错误"后台仅支持钱包支付或线下支付"（CodeInvalidParam）

---

Requirement: 后台 wallet 订单一步到位

系统 SHALL 在后台创建 wallet 订单时立即完成余额扣款和套餐激活，不创建待支付订单。订单创建成功后 payment_status MUST 为 2（已支付）。

与 H5 端的核心区别：

• 后台：检查余额 → 扣款 → 创建已支付订单 → 激活套餐（一步完成）
• H5 端：冻结余额 → 创建待支付订单 → 用户调用支付接口 → 扣款 + 激活（两步流程）

Scenario: 后台 wallet 订单立即扣款

• WHEN 代理在后台创建订单，支付方式为 wallet，钱包余额 5000 分，订单金额 3000 分
• THEN 系统立即扣减钱包余额 3000 分，余额变为 2000 分，创建订单时 payment_status = 2，paid_at 为当前时间

Scenario: 后台 wallet 订单立即激活套餐

• WHEN 代理在后台创建 wallet 订单成功
• THEN 系统在同一事务中创建 PackageUsage 记录，套餐状态为已激活

Scenario: 后台 wallet 订单不创建待支付状态

• WHEN 代理在后台创建 wallet 订单
• THEN 系统不创建 payment_status = 1（待支付）的订单，订单创建后立即为已支付状态

Scenario: 后台 wallet 订单余额不足直接拒绝

• WHEN 代理在后台创建 wallet 订单，钱包余额 1000 分，订单金额 3000 分
• THEN 系统在事务外快速检查余额，返回错误"余额不足"（CodeInsufficientBalance），订单创建失败

Scenario: 后台 wallet 订单事务保证

• WHEN 代理在后台创建 wallet 订单
• THEN 订单创建、余额扣减、套餐激活在同一事务中完成，任一步骤失败则全部回滚

---

Requirement: 后台 offline 订单立即激活

系统 SHALL 在后台创建 offline 订单时立即激活套餐，不扣减钱包余额。订单创建成功后 payment_status MUST 为 2（已支付）。

Scenario: 平台创建 offline 订单立即激活

• WHEN 平台账号创建订单，支付方式为 offline
• THEN 系统创建订单时 payment_status = 2，paid_at 为当前时间，立即激活套餐

Scenario: offline 订单不扣钱包

• WHEN 平台账号创建 offline 订单
• THEN 系统不扣减任何钱包余额（因为是线下支付）

Scenario: offline 订单不检查余额

• WHEN 平台账号创建 offline 订单，钱包余额为 0
• THEN 系统仍然创建订单成功（因为线下支付不依赖钱包）

---

Requirement: 后台订单创建错误处理

系统 SHALL 在后台订单创建失败时返回明确的错误信息，不泄露底层细节。

错误码使用规范：

• 参数验证失败：CodeInvalidParam（不泄露具体校验错误）
• 权限不足：CodeForbidden
• 余额不足：CodeInsufficientBalance
• 钱包不存在：CodeWalletNotFound
• 其他错误：CodeInternalError

Scenario: 参数验证失败不泄露细节

• WHEN 后台创建订单请求参数验证失败（如支付方式非法）
• THEN 系统返回 CodeInvalidParam 错误码，错误消息为通用的"请求参数解析失败"，不包含具体的 validator 错误信息

Scenario: 钱包余额不足返回明确错误

• WHEN 代理创建 wallet 订单，余额不足
• THEN 系统返回 CodeInsufficientBalance 错误码，错误消息为"余额不足"

Scenario: 钱包不存在返回明确错误

• WHEN 代理创建 wallet 订单，钱包不存在
• THEN 系统返回 CodeWalletNotFound 错误码，错误消息为"钱包不存在"

Scenario: 套餐激活失败回滚并返回错误

• WHEN 后台创建订单时余额扣减成功但套餐激活失败
• THEN 事务回滚，钱包余额恢复，返回套餐激活失败错误（CodeInternalError）

---

Requirement: 后台订单创建防重复

系统 SHALL 使用幂等性检查防止同一订单重复创建和重复扣款。

幂等性策略：

• 使用 Redis 业务键：order:idempotency:{buyer_type}:{buyer_id}:{order_type}:{carrier_type}:{carrier_id}:{sorted_package_ids}
• TTL：3 分钟
• 分布式锁：order:create:lock:{carrier_type}:{carrier_id}，TTL 10 秒

Scenario: 重复创建订单返回已创建结果

• WHEN 代理在后台对同一张卡的同一套餐组合在 3 分钟内重复创建订单
• THEN 系统返回第一次创建的订单信息，不重复扣款

Scenario: 并发创建订单使用分布式锁

• WHEN 两个请求同时为同一张卡创建订单
• THEN 只有一个请求获取到分布式锁并创建订单，另一个请求返回"操作进行中，请勿重复提交"（CodeTooManyRequests）

Scenario: 幂等性 key 超时后可重新创建

• WHEN 订单创建成功 3 分钟后，代理再次创建相同订单
• THEN 系统创建新订单（因为幂等性 key 已过期）

---

Requirement: 后台订单 API 响应格式

系统 SHALL 在后台订单创建成功后返回完整的订单信息，包含支付状态、实际支付金额、操作者信息等。

响应字段（OrderResponse）：

• id：订单 ID
• order_no：订单号
• payment_status：支付状态（后台订单必为 2-已支付）
• payment_method：支付方式（wallet 或 offline）
• paid_at：支付时间（不为 NULL）
• total_amount：订单总金额
• actual_paid_amount：实际支付金额（仅 wallet 有值）
• operator_id：操作者 ID
• operator_type：操作者类型（agent/platform）
• purchase_role：购买角色（self_purchase/purchase_for_subordinate/purchased_by_platform）

Scenario: wallet 订单响应包含实际支付金额

• WHEN 代理在后台创建 wallet 订单成功
• THEN 响应包含 actual_paid_amount 字段，值为实际扣减的钱包金额

Scenario: offline 订单响应不包含实际支付金额

• WHEN 平台创建 offline 订单成功
• THEN 响应的 actual_paid_amount 字段为 NULL（因为线下支付不扣钱包）

Scenario: 代购订单响应包含操作者信息

• WHEN 上级代理为下级代理购买套餐
• THEN 响应包含 operator_id（上级店铺 ID）、operator_type = "agent"、purchase_role = "purchase_for_subordinate"

---

Requirement: 后台订单创建与 H5 端隔离

系统 SHALL 使用独立的 Service 方法处理后台订单创建，避免与 H5 端订单创建逻辑混淆。

架构设计：

• 后台：OrderHandler.Create() → OrderService.CreateAdminOrder()
• H5 端：OrderHandler.Create() → OrderService.CreateH5Order()

Scenario: 后台调用独立的 Service 方法

• WHEN 后台创建订单
• THEN Handler 层调用 OrderService.CreateAdminOrder() 方法，不调用通用的 Create() 方法

Scenario: H5 端调用独立的 Service 方法

• WHEN H5 端创建订单
• THEN Handler 层调用 OrderService.CreateH5Order() 方法，不影响后台订单创建逻辑

Scenario: Service 方法命名明确职责

• WHEN 开发人员查看代码
• THEN 方法命名（CreateAdminOrder vs CreateH5Order）清楚表明了后台和 H5 端的差异，防止误用