junhong_cmp_fiber/openspec/specs/order-management/spec.md

Capability: 订单管理

Purpose

本 capability 定义套餐购买订单的创建、查询、取消等完整生命周期管理，包括普通订单和代购订单的区分、支付方式的处理、强充要求的验证。

Requirements

Requirement: 订单类型标识

系统 SHALL 在订单模型中增加 is_purchase_on_behalf 字段，标识是否为代购订单。

Scenario: 普通订单创建

• WHEN 个人客户或代理为自己创建订单
• THEN 系统设置 is_purchase_on_behalf = false

Scenario: 代购订单创建

• WHEN 平台或代理为其他代理创建代购订单
• THEN 系统设置 is_purchase_on_behalf = true

Scenario: 查询订单列表返回订单类型

• WHEN 查询订单列表或详情
• THEN 响应包含 is_purchase_on_behalf 字段

---

Requirement: 创建套餐购买订单

系统 SHALL 允许买家创建套餐购买订单。[BREAKING] 请求体改为使用资产标识符（identifier），废弃 iot_card_id/device_id 主键字段；order_type 字段由系统根据 identifier 解析结果自动填入，请求体不再接受。创建前 MUST 验证购买权限和强充要求。后台订单接口 MUST 支持 payment_method 字段（wallet/offline），根据支付方式自动设置 is_purchase_on_behalf 标识。

后台订单创建请求（CreateAdminOrderRequest）：

{
  "identifier":      "string（资产标识符，ICCID 或 VirtualNo，必填）",
  "package_ids":     "[uint]（套餐 ID 列表，必填，1-10 个）",
  "payment_method":  "string（wallet|offline，必填）"
}

废弃字段：

• iot_card_id（原用于单卡购买）
• device_id（原用于设备购买）
• order_type（改为系统自动推断）

支付方式和订单类型映射：

• payment_method = "wallet"：扣买家钱包，is_purchase_on_behalf = false（普通订单）
• payment_method = "offline"：线下已收款，is_purchase_on_behalf = true（代购订单）

权限规则：

• wallet 支付：代理、平台、超级管理员可使用
• offline 支付：仅平台、超级管理员可使用

Scenario: 个人客户创建单卡订单

• WHEN 个人客户为自己的卡创建订单，选择一个套餐
• THEN 系统创建订单，状态为待支付，is_purchase_on_behalf = false，返回订单信息

Scenario: 个人客户创建设备订单

• WHEN 个人客户为自己的设备创建订单
• THEN 系统创建订单，订单类型为设备购买，is_purchase_on_behalf = false

Scenario: 代理创建普通订单（钱包支付）

• WHEN 代理为店铺关联的卡/设备创建订单，payment_method = "wallet"
• THEN 系统创建订单，买家类型为代理商，买家ID为店铺ID，is_purchase_on_behalf = false，payment_status = 1（待支付）

Scenario: 平台创建代购订单（线下支付）

• WHEN 平台账号为代理的卡/设备创建订单，payment_method = "offline"
• THEN 系统创建订单，is_purchase_on_behalf = true，payment_method = "offline"，payment_status = 2（已支付），直接激活套餐

Scenario: 代理尝试使用线下支付

• WHEN 代理账号创建订单，payment_method = "offline"
• THEN 系统返回错误 "只有平台可以使用线下支付"

Scenario: 平台使用钱包支付

• WHEN 平台账号创建订单，payment_method = "wallet"，指定目标代理
• THEN 系统创建普通订单，扣目标代理钱包，is_purchase_on_behalf = false

Scenario: 套餐购买验证强充要求

• WHEN 个人客户创建订单，存在强充要求，订单金额低于强充金额
• THEN 系统返回错误 "支付金额不符合强充要求"

Scenario: 套餐不在可购买范围

• WHEN 买家尝试购买不在关联系列下的套餐
• THEN 系统返回错误 "该套餐不在可购买范围内"

Scenario: 套餐已下架

• WHEN 买家尝试购买已下架的套餐
• THEN 系统返回错误 "该套餐已下架"

Scenario: 使用 VirtualNo 创建设备订单

• WHEN 管理员请求体携带 { identifier: "DEV-001", package_ids: [5], payment_method: "wallet" }
• THEN 系统解析 identifier 为设备，自动设置 order_type = device，创建设备购买订单

Scenario: 使用 ICCID 创建单卡订单

• WHEN 管理员请求体携带 { identifier: "898600XXXXX", package_ids: [5], payment_method: "wallet" }
• THEN 系统解析 identifier 为独立 IoT 卡（is_standalone = true），自动设置 order_type = single_card，创建单卡购买订单

Scenario: 使用绑定设备的卡 ICCID 创建订单被拒

• WHEN 管理员请求体携带 { identifier: "898600XXXXX" } 但该卡 is_standalone = false
• THEN 系统返回错误"该卡已绑定设备，请前往设备页面购买套餐"，订单不创建

Scenario: identifier 不存在

• WHEN 请求的 identifier 无法解析到任何资产
• THEN 返回错误"资产不存在"，订单不创建

---

Requirement: 查询订单列表

系统 SHALL 提供订单列表查询，支持按支付状态、订单类型、是否代购筛选。

Scenario: 个人客户查询自己的订单

• WHEN 个人客户查询订单列表
• THEN 系统只返回该客户的订单

Scenario: 代理查询店铺订单

• WHEN 代理查询订单列表
• THEN 系统返回该店铺及下级店铺的订单（包含代购订单和普通订单）

Scenario: 按代购类型筛选

• WHEN 指定 is_purchase_on_behalf = true 筛选
• THEN 系统只返回代购订单

Scenario: 按支付状态筛选

• WHEN 指定支付状态筛选
• THEN 系统只返回匹配状态的订单

---

Requirement: 查询订单详情

系统 SHALL 允许买家查询订单详情，包含订单明细。

Scenario: 查询订单详情

• WHEN 买家查询指定订单详情
• THEN 系统返回订单信息和订单明细列表

Scenario: 查询他人订单

• WHEN 买家尝试查询不属于自己的订单
• THEN 系统返回 "订单不存在" 错误

---

Requirement: 取消订单

系统 SHALL 允许买家取消未支付的订单，但代购订单不可取消。

Scenario: 取消待支付的普通订单

• WHEN 买家取消一个待支付的普通订单（is_purchase_on_behalf = false）
• THEN 系统更新订单状态为已取消

Scenario: 取消已支付订单

• WHEN 买家尝试取消已支付的订单
• THEN 系统返回错误 "已支付订单无法取消"

Scenario: 尝试取消代购订单

• WHEN 买家尝试取消代购订单（is_purchase_on_behalf = true）
• THEN 系统返回错误 "代购订单不可取消"

---

Requirement: 订单号生成

系统生成的订单号 MUST 全局唯一，格式为 ORD{YYYYMMDDHHMMSS}{6位随机数}。

Scenario: 订单号格式

• WHEN 创建新订单
• THEN 订单号格式为 ORD + 14位时间戳 + 6位随机数

Scenario: 订单号唯一

• WHEN 并发创建多个订单
• THEN 每个订单的订单号都唯一

---

Requirement: 后台订单 payment_method 字段

后台订单创建接口 MUST 支持 payment_method 字段，值为 wallet 或 offline。系统 SHALL 根据 payment_method 自动设置 is_purchase_on_behalf 标识。

Scenario: payment_method 为 wallet

• WHEN 创建订单时 payment_method = "wallet"
• THEN 系统设置 is_purchase_on_behalf = false，payment_status = 1（待支付）

Scenario: payment_method 为 offline

• WHEN 创建订单时 payment_method = "offline"
• THEN 系统设置 is_purchase_on_behalf = true，payment_status = 2（已支付），paid_at = 当前时间

Scenario: payment_method 验证

• WHEN 创建订单时 payment_method 为无效值
• THEN 系统返回参数验证错误

---

Requirement: 代购订单成本价计算

线下支付（代购订单）MUST 使用买家的成本价，钱包支付（普通订单）使用卖家的成本价。

Scenario: 线下支付使用买家成本价

• WHEN 平台创建线下支付订单，目标卡归属于代理 A，代理 A 的系列分配成本价为 100 元
• THEN 订单总金额为 100 元（买家成本价）

Scenario: 钱包支付使用卖家成本价

• WHEN 代理 A 为自己的卡创建钱包支付订单，代理 A 的上级代理 B 的系列分配成本价为 120 元
• THEN 订单总金额为 120 元（卖家成本价）

---

Requirement: 代购订单不触发佣金和累计充值

代购订单（is_purchase_on_behalf = true）SHALL 计算差价佣金，MUST NOT 触发一次性佣金，MUST NOT 更新累计充值。

Scenario: 代购订单计算差价佣金

• WHEN 代购订单支付成功，买家成本价 100 元，套餐建议成本价 80 元
• THEN 系统计算差价佣金 20 元，分配给上级代理

Scenario: 代购订单不触发一次性佣金

• WHEN 代购订单支付成功，符合一次性佣金触发条件
• THEN 系统 MUST NOT 触发一次性佣金

Scenario: 代购订单不更新累计充值

• WHEN 代购订单支付成功
• THEN 系统 MUST NOT 更新卡/设备的 accumulated_recharge 字段

---

Requirement: 主套餐购买时自动排队

系统 SHALL 在用户购买主套餐时，如果已有生效中的主套餐，自动将新套餐设置为待生效状态并分配 priority。

Scenario: 首个主套餐立即生效

• WHEN 载体首次购买主套餐
• THEN PackageUsage status=1, priority=1, activated_at=支付完成时间

Scenario: 第二个主套餐自动排队

• WHEN 载体已有生效中主套餐，购买第2个主套餐
• THEN PackageUsage status=0, priority=2, pending_realname_activation=false

Requirement: 加油包购买前检查主套餐

系统 SHALL 在用户购买加油包前，检查是否有生效中或待生效的主套餐。

Scenario: 无主套餐时购买加油包失败

• WHEN 用户购买加油包，但载体无主套餐
• THEN 系统返回错误 400 "必须有主套餐才能购买加油包"

Scenario: 有主套餐时可购买加油包

• WHEN 用户购买加油包，载体有生效中主套餐
• THEN 系统创建订单成功，PackageUsage master_usage_id=主套餐ID

Requirement: 客户端未实名时禁止购买套餐

系统 SHALL 在客户端购买套餐时，检查载体的实名状态。

Scenario: 客户端未实名购买返回错误

• WHEN 客户通过 H5 端购买套餐，载体未实名
• THEN 系统返回错误 403 "设备/卡必须先完成实名认证才能购买套餐"

Scenario: 后台管理端可为未实名载体购买

• WHEN 管理员通过后台为未实名载体购买套餐
• THEN 系统创建订单成功，PackageUsage status=0, pending_realname_activation=true

---

Requirement: 订单响应包含资产标识符

订单响应（OrderResponse）SHALL 包含资产标识符字段，前端无需额外请求即可展示资产信息。

新增响应字段：

• asset_identifier：下单时资产的标识符快照（ICCID 或 VirtualNo）
• asset_type：资产类型（single_card 对应 iot_card，device 对应 device）

Scenario: 查看订单详情时展示资产标识符

• WHEN 管理员查询订单详情 GET /api/admin/orders/:id
• THEN 响应中包含 asset_identifier（如 "DEV-001"）和 asset_type（如 "device"）
• THEN 即使原资产已被删除，asset_identifier 仍可读（快照字段）

---

Requirement: 订单列表支持按资产标识符过滤

系统 SHALL 在订单列表查询（OrderListRequest）中支持 identifier 过滤参数，按照资产标识符精确匹配订单（匹配 asset_identifier 快照字段）。

Scenario: 按 ICCID 查询该卡的历史订单

• WHEN 管理员查询 GET /api/admin/orders?identifier=898600XXXXX
• THEN 返回 asset_identifier = "898600XXXXX" 的所有订单（分页）

Scenario: 按设备 VirtualNo 查询该设备的历史订单

• WHEN 管理员查询 GET /api/admin/orders?identifier=DEV-001
• THEN 返回 asset_identifier = "DEV-001" 的所有订单（分页）

Scenario: 标识符无匹配订单

• WHEN 管理员查询不存在订单的 identifier
• THEN 返回空列表（items: []，total: 0），不返回错误