文档

openspec/specs/purchase-on-behalf/spec.md

@@ -0,0 +1,145 @@
+# Capability: 代购订单
+
+## Purpose
+
+本 capability 定义代购订单功能，允许平台或代理为其他代理创建套餐购买订单，使用线下支付方式，订单创建后直接完成支付并激活套餐。
+
+## Requirements
+
+### Requirement: 平台创建代购订单
+
+系统 SHALL 允许平台账号为代理创建代购订单，使用线下支付方式，订单创建后直接标记为已支付。
+
+#### Scenario: 平台为一级代理代购
+- **WHEN** 平台账号为一级代理的卡创建代购订单，选择套餐，支付方式为线下支付
+- **THEN** 系统创建订单，buyer_id = 一级代理店铺ID，is_purchase_on_behalf = true，payment_method = "offline"，payment_status = 2（已支付）
+
+#### Scenario: 平台为二级代理代购
+- **WHEN** 平台账号为二级代理的卡创建代购订单
+- **THEN** 系统创建订单，buyer_id = 二级代理店铺ID，is_purchase_on_behalf = true
+
+#### Scenario: 代购订单价格使用代理成本价
+- **WHEN** 平台为代理创建代购订单，套餐价格 100 元，代理成本价 80 元
+- **THEN** 订单金额为 80 元（代理成本价）
+
+#### Scenario: 查询卡归属代理
+- **WHEN** 平台选择卡创建代购订单
+- **THEN** 系统查询卡的 shop_id，作为订单的 buyer_id
+
+#### Scenario: 查询设备归属代理
+- **WHEN** 平台选择设备创建代购订单
+- **THEN** 系统查询设备的 shop_id，作为订单的 buyer_id
+
+---
+
+### Requirement: 代理创建代购订单
+
+系统 SHALL 允许代理账号为其他代理（通常是下级代理）创建代购订单。
+
+#### Scenario: 一级代理为二级代理代购
+- **WHEN** 一级代理为二级代理的卡创建代购订单，选择套餐，支付方式为线下支付
+- **THEN** 系统创建订单，buyer_id = 二级代理店铺ID，is_purchase_on_behalf = true，payment_method = "offline"
+
+#### Scenario: 代购订单使用买家成本价
+- **WHEN** 一级代理为二级代理代购，套餐价格 100 元，二级代理成本价 90 元
+- **THEN** 订单金额为 90 元（买家成本价）
+
+---
+
+### Requirement: 代购订单自动完成
+
+代购订单创建后 SHALL 自动完成支付流程，激活套餐，但不触发一次性佣金。
+
+#### Scenario: 代购订单自动激活套餐
+- **WHEN** 创建代购订单成功
+- **THEN** 系统自动激活套餐（创建 PackageUsage 记录）
+
+#### Scenario: 代购订单不扣钱包
+- **WHEN** 创建代购订单
+- **THEN** 系统不扣减任何钱包余额（线下已收款）
+
+#### Scenario: 代购订单不更新累计充值
+- **WHEN** 代购订单完成
+- **THEN** 系统不更新卡/设备的 accumulated_recharge 字段
+
+#### Scenario: 代购订单计算差价佣金
+- **WHEN** 代购订单完成，买家有上级代理
+- **THEN** 系统计算差价佣金（买家成本价 - 上级成本价），发放给上级代理
+
+#### Scenario: 代购订单不触发一次性佣金
+- **WHEN** 代购订单完成
+- **THEN** 系统不检查一次性佣金阈值，不发放一次性佣金
+
+---
+
+### Requirement: 代购订单查询
+
+系统 SHALL 在订单列表中正确显示代购订单。
+
+#### Scenario: 平台查询代购订单
+- **WHEN** 平台账号查询订单列表
+- **THEN** 系统返回所有代购订单（is_purchase_on_behalf = true），包含创建人信息
+
+#### Scenario: 代理查询收到的代购订单
+- **WHEN** 代理查询订单列表，包含别人为自己代购的订单
+- **THEN** 系统返回买家为自己的代购订单
+
+#### Scenario: 代购订单标识
+- **WHEN** 查询订单详情
+- **THEN** 订单响应包含 is_purchase_on_behalf 字段，前端可以显示"代购订单"标签
+
+---
+
+### Requirement: 代购订单权限控制
+
+系统 SHALL 严格控制代购订单的创建权限。
+
+#### Scenario: 只有平台账号可以使用线下支付
+- **WHEN** 代理账号尝试创建订单时选择支付方式为 offline
+- **THEN** 系统返回错误 "只有平台账号可以使用线下支付"
+
+#### Scenario: 平台账号可以为任何代理代购
+- **WHEN** 平台账号为任意层级代理创建代购订单
+- **THEN** 系统允许创建
+
+#### Scenario: 代理账号只能为下级代理代购
+- **WHEN** 代理账号尝试为上级或平级代理创建代购订单
+- **THEN** 系统返回错误 "只能为下级代理代购套餐"
+
+---
+
+### Requirement: 代购订单记录
+
+系统 SHALL 完整记录代购订单的创建人和买家信息。
+
+#### Scenario: 记录创建人
+- **WHEN** 平台/代理创建代购订单
+- **THEN** 订单的 creator 字段记录创建人账号ID
+
+#### Scenario: 区分创建人和买家
+- **WHEN** 查询代购订单详情
+- **THEN** creator（创建人）!= buyer_id（买家），可以追溯是谁代购的
+
+---
+
+### Requirement: 代购订单不可取消
+
+代购订单创建后 SHALL 不可取消，因为已自动完成。
+
+#### Scenario: 尝试取消代购订单
+- **WHEN** 尝试取消一个代购订单（is_purchase_on_behalf = true）
+- **THEN** 系统返回错误 "代购订单不可取消"
+
+---
+
+### Requirement: 线下支付方式常量
+
+系统 SHALL 定义线下支付方式常量。
+
+#### Scenario: 支付方式枚举
+- **WHEN** 创建订单时选择支付方式
+- **THEN** payment_method 可选值包含：wallet, wechat, alipay, offline
+
+#### Scenario: 线下支付只用于代购
+- **WHEN** payment_method = "offline"
+- **THEN** 订单必须标记为 is_purchase_on_behalf = true