quyun-v2/backend/specs/spec01.md

# Spec 01：多租户媒体发布平台（余额隔离 / 订单与退款 / 内容定价）

> 目标：把“同一用户属于多个租户、租户可为用户充值、余额仅能在当前租户消费、租户管理员可查看订单并退款、管理员发布内容可配置价格与折扣”等需求落到可实现的业务规格，作为后续数据模型/API/权限/流程实现依据。

## 1. 背景与范围

### 1.1 背景
- 平台支持视频/音频/图片的媒体内容发布与售卖（或付费访问）。
- 平台面向多租户（Tenant）：不同租户之间的数据、资金、内容必须严格隔离。
- 同一用户（User）可加入多个租户；在每个租户内拥有独立的“租户内余额”用于消费该租户内的业务。
- 租户管理员（Tenant Admin）能对订单进行查看、发起退款等操作；管理员发布的内容可配置价格与折扣策略。

### 1.2 本 spec 覆盖
- 多租户身份与权限：同一用户多租户归属、租户内角色。
- 余额体系：租户为用户充值、租户内余额隔离、消费与退款回滚。
- 商品与订单：内容定价、折扣、下单、扣款、退款、订单审计。
- 媒体发布：内容/媒体资源的基础生命周期（上传、审核/上架、购买/访问）。

### 1.3 明确不做（暂定）
- 广告分发、推荐算法、复杂分账（创作者分成）、第三方支付直连（如微信/支付宝）细节。
- 版权确权、内容风控/涉政涉黄自动审核体系（仅预留状态与接口）。
- 跨租户资产迁移、跨租户合并结算。

## 2. 角色与核心术语

### 2.1 角色（Actors）
- 平台超级管理员（Super Admin）：平台级别的租户管理/风控/对账（可选，视项目现状）。
- 租户管理员（Tenant Admin）：租户内运营角色；发布内容、设置价格与折扣、查看订单与退款。
- 租户成员（Member）：属于某租户的普通用户；可消费该租户内容、可发布内容（若租户开放）。
- 游客/未加入租户用户：只能浏览公开内容（若允许），不可使用租户余额。

### 2.2 核心术语
- Tenant（租户）：逻辑隔离域，拥有自己的内容、订单、余额账本规则。
- TenantUser（租户成员关系）：User 在某个 Tenant 下的身份载体（含 role、balance、状态等）。
- Balance（余额）：以 TenantUser 为维度的可用余额；只可在当前 Tenant 内消费与退款回滚。
- Ledger（账本/流水）：所有余额变动必须落到可审计流水（增、减、冻结/解冻、退款）。
- Content（内容）：一条可出售/可访问的媒体内容实体（可关联多媒体资源）。
- MediaAsset（媒体资源）：视频/音频/图片的文件对象（含转码/封面/时长/尺寸等元数据）。
- Price（价格）：内容在某租户内的定价；折扣可作用于价格形成最终成交价。
- Order（订单）：用户在租户内对内容的购买/消费记录；支持退款。

## 3. 多租户与权限模型

### 3.1 多租户原则
- 所有业务数据必须带 `tenant_id`（或可推导的 tenant 归属），并在查询/写入时强制校验租户边界。
- 同一 user 在不同 tenant 下的余额、订单、内容访问权限互不影响。

### 3.2 租户内角色（最小集合）
- `member`：默认角色。
- `tenant_admin`：租户管理员。

> 备注：代码侧已有 `TenantUserRole`（member/tenant_admin），可以作为对齐基准。

### 3.3 权限矩阵（建议）
- member：
  - 可查看本租户可见内容（公开/已购买/订阅等策略见后文）。
  - 可用本租户余额购买内容/消费服务。
  - 可查看自己的订单与余额流水。
- tenant_admin：
  - 拥有 member 的所有权限。
  - 可创建/编辑/下架内容；配置价格与折扣。
  - 可查看租户内订单（按条件检索/导出）。
  - 可发起退款（遵循退款规则/风控规则）。
  - 可为租户内用户充值（如果业务允许“租户给用户发放额度”）。
- super admin（可选）：
  - 可查看全平台租户与全局审计（不在本 spec 强制实现，但建议预留）。

## 4. 余额体系（Tenant 内隔离）

### 4.1 账户维度
- 余额账户 = `TenantUser` 维度（tenant_id + user_id）。
- `balance_available`（可用余额）：可直接消费。
- `balance_frozen`（冻结余额，可选）：用于“待支付/待确认/争议期”等场景，避免并发重复扣款。

> 你已确认需要冻结机制（5.B）。当前项目已有 `tenant_users.balance`（bigint），可作为 `balance_available` 的第一版；建议新增 `balance_frozen`（bigint）并配套流水类型 `freeze/unfreeze`。

### 4.2 充值（租户为用户充值）
定义：租户向其成员发放/充值额度，用户只能在该租户内使用。

规则建议：
- 充值必须产生一条“充值订单”或“余额流水”（建议两者都存在：订单做业务视角，流水做账本视角）。
- 充值需支持幂等：相同外部业务单号/请求幂等键重复请求，不可重复入账。
- 充值来源（可枚举）：
  - `tenant_grant`：租户后台人工/批量发放额度。
  - `user_pay`：用户实际支付购买额度（本期不做，仅预留）。

### 4.3 消费（余额扣减）
定义：用户在租户内使用余额购买内容（或支付发布/服务费用）。

你已确认“消费=购买租户内付费内容”（1.A），本 spec 将仅覆盖 `content_purchase`，发布收费等其他计费暂不纳入本期范围。

关键规则：
- 订单必须绑定 `tenant_id`，扣款只能操作该 `tenant_id` 下的 `TenantUser` 余额。
- 扣款以“最终成交价”为准，成交价由“基础价 + 折扣/优惠”计算。
- 余额不足则拒绝下单/支付。
- 需要防止并发超卖/重复扣款：建议在创建支付时使用冻结余额或基于数据库事务 + 行锁。

### 4.4 退款（订单退款回滚余额）
定义：租户管理员可对订单发起退款，退款金额回到原租户余额账户。

规则建议：
- 退款必须可追溯：关联原订单、原扣款流水。
- 支持两种策略（二选一或都做）：
  1) 全额退款：仅允许对未消费/未解锁的内容退款。
  2) 部分退款：按已消费比例/争议裁决退款（需要更复杂的计费与权益计算）。
- 你已确认仅做“全额退款 + 限时间窗”（4.A）：
  - 默认规则：`refundable_until = paid_at + 24h`；
  - 管理侧强制退款：`tenant_admin` 可忽略时间窗强制退款（必须写明原因并强审计）。
- 退款结果必须幂等：同一笔退款请求不可重复入账。
- 退款权限：仅 `tenant_admin`（或更高）可操作；member 只能发起“退款申请”。

## 5. 内容与媒体模型

### 5.1 MediaAsset（媒体资源）
支持类型：
- video：原始文件 + 转码产物 + 封面 + 时长 + 分辨率 + 编码信息
- audio：原始文件 + 转码产物 + 时长 + 码率
- image：原始文件 + 缩略图 + 尺寸

最小字段建议：
- `id`
- `tenant_id`
- `user_id`
- `type`（video/audio/image）
- `storage_provider`、`bucket`、`object_key`（或 url）
- `status`（uploaded/processing/ready/failed/deleted）
- `meta`（JSON：时长/尺寸/码率/哈希等）
- `created_at/updated_at`

### 5.2 Content（内容）
一条内容可以关联 0..N 个媒体资源（例如：视频+封面图+音频）。

最小字段建议：
- `id`
- `tenant_id`
- `user_id`
- `title`、`description`
- `status`（draft/reviewing/published/unpublished/blocked）
- `visibility`（public/tenant_only/private；可扩展）
- `preview_seconds`（默认 60）
- `preview_downloadable`（默认 false）
- `published_at`
- `created_at/updated_at`

## 6. 定价与折扣

### 6.1 定价模型（建议）
价格以“最小货币单位”存储（例如分），避免浮点误差：
- `price_amount`（int64，单位分）
- `currency`（本期固定 CNY；多币种为后续扩展）

### 6.2 折扣模型（建议最小集合）
折扣针对内容的成交价计算，可先实现“单一折扣规则”：
- `discount_type`：
  - `none`
  - `percent`（如 20% off）
  - `amount`（立减）
- `discount_value`：percent(0-100) 或 amount(分)
- `discount_start_at` / `discount_end_at`（可选）

计算规则：
- percent：`final = price_amount * (100 - percent) / 100`
- amount：`final = max(0, price_amount - amount)`
- 必须记录下单时的“成交快照”（避免事后改价影响历史订单）。

### 6.3 谁能设置
- 仅 `tenant_admin` 可为其发布的内容设置/修改价格与折扣。
- 如果未来允许“作者发布但管理员定价”，需要在权限上增加“作者/运营”区分。

## 7. 订单模型（购买内容）

### 7.1 订单类型（建议）
为后续扩展预留 `order_type`：
- `content_purchase`：购买内容（本 spec 核心）
- `topup`：充值订单（租户发放/用户支付）
> 你已确认本期只做 1.A + 2.A，因此 `content_purchase` + `topup(tenant_grant)` 为主，`user_pay`/`service_fee` 仅作为未来扩展位保留。

### 7.2 订单状态（建议）
以余额支付为例（不接三方）：
- `created`：已创建待支付（可选，若立即扣款可跳过）
- `paid`：已扣款/支付成功
- `refunding`：退款处理中
- `refunded`：已退款
- `canceled`：已取消（未扣款）
- `failed`：失败（扣款失败/规则校验失败）

冻结机制下的状态约束建议：
- 进入 `paid` 前如发生错误（例如订单落库失败），必须执行 `unfreeze` 回滚冻结余额，并将订单标记为 `failed` 或不落库（但需保证幂等返回一致）。
  - 你已确认：订单创建成功但写 `debit_purchase` 失败时，不保留该订单记录；幂等返回“失败 + 已回滚冻结”。

### 7.3 订单字段建议
- `id`
- `tenant_id`
- `buyer_user_id`
- `order_type`
- `amount_original`（原价）
- `amount_discount`（优惠金额）
- `amount_paid`（实付）
- `currency`
- `status`
- `snapshot`（JSON：下单时价格/折扣/内容标题等快照）
- `created_at/paid_at/refunded_at`
> 订单操作者如需审计，建议使用 `operator_user_id`（例如后台代下单/代退款），或在 `snapshot` 中记录。

### 7.4 订单明细（OrderItem，建议）
内容购买通常 1 单 1 内容，但用明细便于扩展：
- `order_id`
- `content_id`
- `content_owner_user_id`（可选，用于后续分成/对账）
- `amount_line`（该行实付）
- `snapshot`（内容快照）

## 8. 余额流水（账本 Ledger）

### 8.1 设计原则
- 余额的每一次变化都必须有流水记录，可审计、可对账、可回放。
- 流水必须带 `tenant_id` 与 `tenant_user_id`（或 tenant_id+user_id）。
- 所有入账/出账/退款都强制关联“业务单据”（订单/退款单）。

### 8.2 流水类型（建议）
- `credit_topup`：充值入账
- `debit_purchase`：购买扣款
- `credit_refund`：退款回滚
- `freeze` / `unfreeze`：冻结/解冻（可选）
- `adjustment`：人工调账（需强审计）

### 8.3 幂等与一致性
- 流水表建议使用 `idempotency_key` 或 `biz_ref_type + biz_ref_id` 做唯一约束，防止重复入账。
- 扣款与订单状态更新必须在一个事务内完成（或使用可靠消息最终一致）。

## 9. 关键流程（建议版）

### 9.1 加入租户
1) user 通过邀请/申请加入 tenant
2) 创建 `TenantUser(tenant_id,user_id,role=member,balance=0)`
3) tenant_admin 可提升为 `tenant_admin`

### 9.2 租户为用户充值
1) tenant_admin 在后台选择 tenant_user、输入金额、填写备注/原因
2) 创建 `topup` 订单（或 topup 记录）
3) 写入 ledger：`credit_topup`
4) 增加 tenant_user.balance
5) 返回充值结果与可用余额

### 9.3 用户购买内容（余额支付）
1) buyer 选择 tenant 下某 content
2) 系统计算成交价（读取当前 price+discount），生成订单快照
3) 校验余额足够、内容可售、用户在该 tenant 下有效
4) 冻结余额：写入 ledger：`freeze`，`balance_available -= amount_paid`，`balance_frozen += amount_paid`
5) 创建订单（status=paid 或 created→paid）
6) 扣款落账：写入 ledger：`debit_purchase`，`balance_frozen -= amount_paid`（表示冻结转为最终扣款）
7) 写入“购买权益”（见 9.5）

失败回滚（必须）：
- 若步骤 4 成功而步骤 5/6 失败：必须写入 `unfreeze` 并回滚余额（`balance_available += amount_paid`，`balance_frozen -= amount_paid`），同时保证幂等键再次请求能返回最终一致结果。
- 若步骤 5 成功但步骤 6 失败：执行 `unfreeze` 回滚后不落库订单，并对该幂等键固定返回“失败+已回滚”（不可重复创建新订单）。

### 9.4 租户管理员退款
1) tenant_admin 选中订单，校验可退款（状态/风控/时间窗）
2) 创建退款记录（可选），订单状态→refunding
3) 写入 ledger：`credit_refund`（金额=退款金额）
4) 增加 tenant_user.balance（可用余额）
5) 订单状态→refunded，记录 refunded_at 与操作者
6) 收回/标记权益（若需要）

你已确认退款对权益的处理：
- 退款成功后，将对应 `content_access.status` 置为 `revoked`（立即失效）。

### 9.5 购买权益（访问控制）
最小实现建议：记录 `content_access`（tenant_id, content_id, user_id, order_id, status, created_at）。
- 访问内容时，校验：
  - content 是否公开（public）或
  - user 是否拥有 `content_access` 且有效

你已确认需要“试看/预览”（3.B），建议增加：
- `content_assets.role=preview`（或单独字段），允许未购买用户访问 preview 资源；
- 正片资源（main）仍需 `content_access` 校验；
- 订单快照中记录“当时预览策略”，避免策略变更导致争议。

预览边界建议（最小可用）：
- preview 资源必须与 main 资源彻底区分（不同 object_key / 不同转码模板），避免客户端绕过。
- preview 可以额外加频控/防盗链（后续），但不影响本期的租户隔离与权益校验。

你已确认的试看策略：
- 固定时长试看：默认前 `60s`（仅 streaming，不允许下载）。

## 10. 查询与后台能力（Tenant Admin）

### 10.1 订单查询
筛选条件建议：
- 时间范围（created_at/paid_at）
- buyer_user_id / 用户关键字
- content_id / 内容标题关键字
- 订单状态、订单类型
- 金额范围

### 10.2 退款操作
输入项建议：
- 退款金额（默认=实付）
- 退款原因（枚举 + 备注）
- 是否立即生效（余额体系通常立即入账）

输出与审计：
- 记录操作者、操作时间、原订单快照、退款快照、对应流水 id

## 11. 已确认的关键决策（用于锁定实现）

你已确认：
- 消费=购买租户内付费内容（1.A）
- 充值来源=仅租户后台发放额度（2.A）
- 内容支持试看/预览（3.B）：固定时长前 `60s`，不允许下载
- 退款=全额退款 + 默认时间窗 `paid_at + 24h`，且租户管理侧允许强制退款（需强审计）
- 余额需要冻结机制（5.B），并要求“失败回滚 + 幂等返回一致”
- 金额=仅 CNY（分）（6.A）

## 12. 里程碑拆分（建议）
- M1：TenantUser 余额隔离 + 充值入账 + 余额支付下单 + 订单查询 + 全额退款。
- M2：内容发布全链路（media asset/processing 状态）、内容访问权益、折扣生效与订单快照。
- M3：冻结/部分退款/风控规则/对账导出/批量充值。

## 13. 数据模型草案（供对齐）

> 注：字段名为建议，最终以现有项目的命名/生成器约束为准。金额统一用 `int64`（分）。

### 13.1 tenant_users（已存在，建议扩展方向）
- `tenant_id`, `user_id`
- `role`（member/tenant_admin）
- `balance`（可用余额，已存在）
- （可选）`balance_frozen`
- `status`（active/disabled/pending 等）

### 13.2 media_assets
- `id`, `tenant_id`, `user_id`, `type`
- `status`（uploaded/processing/ready/failed/deleted）
- `provider`, `bucket`, `object_key`（或 `url`）
- `meta`（JSON：hash、duration、width、height、bitrate、codec...）
- `created_at`, `updated_at`

### 13.3 contents
- `id`, `tenant_id`, `user_id`
- `title`, `description`
- `status`（draft/reviewing/published/unpublished/blocked）
- `visibility`（public/tenant_only/private）
- `published_at`, `created_at`, `updated_at`

### 13.4 content_assets（内容与媒体关联表）
- `tenant_id`, `content_id`, `asset_id`
- `role`（main/cover/preview 等）
- `sort`

### 13.5 content_prices（内容定价；或直接放 contents）
- `tenant_id`, `user_id`, `content_id`
- `currency`
- `price_amount`
- `discount_type`, `discount_value`
- `discount_start_at`, `discount_end_at`
- `updated_at`

### 13.6 orders / order_items
- orders：
  - `id`, `tenant_id`, `buyer_user_id`, `order_type`, `status`
  - `amount_original`, `amount_discount`, `amount_paid`, `currency`
  - `snapshot`（JSON），`idempotency_key`（唯一）
  - `created_at`, `paid_at`, `refunded_at`
- order_items：
  - `order_id`, `tenant_id`, `content_id`
  - `amount_line`
  - `snapshot`（JSON）

### 13.7 balance_ledgers（强烈建议新增）
- `id`, `tenant_id`, `user_id`（或 `tenant_user_id`）
- `direction`（credit/debit）
- `type`（credit_topup/debit_purchase/credit_refund/...）
- `amount`（正数）
- `balance_before`, `balance_after`（可选但强审计）
- `biz_ref_type`, `biz_ref_id`（唯一约束，幂等）
- `operator_user_id`（谁触发：admin/buyer/system）
- `note`, `created_at`

### 13.8 content_access（购买权益）
- `tenant_id`, `content_id`, `user_id`, `order_id`
- `status`（active/revoked/expired）
- `created_at`, `revoked_at`

## 14. API 草案（只描述意图，不锁死路径）

### 14.1 租户侧（Tenant Admin）
- 充值：
  - `POST /tenants/:tenant_id/users/:user_id/topup`（amount, note, idempotency_key）
- 订单查询：
  - `GET /tenants/:tenant_id/orders`（分页+筛选）
  - `GET /tenants/:tenant_id/orders/:id`
- 退款：
  - `POST /tenants/:tenant_id/orders/:id/refund`（amount?, reason, idempotency_key）
- 内容管理：
  - `POST /tenants/:tenant_id/contents`（草稿）
  - `PATCH /tenants/:tenant_id/contents/:id`（编辑/上架/下架）
  - `PUT /tenants/:tenant_id/contents/:id/price`（价格+折扣）

### 14.2 用户侧（Member）
- 浏览内容：
  - `GET /tenants/:tenant_id/contents`（可见列表）
  - `GET /tenants/:tenant_id/contents/:id`
- 购买：
  - `POST /tenants/:tenant_id/orders`（content_id, idempotency_key）
- 我的订单/余额：
  - `GET /tenants/:tenant_id/me/orders`
  - `GET /tenants/:tenant_id/me/balance`
  - `GET /tenants/:tenant_id/me/ledgers`

## 15. 边界条件与非功能要求（落地时容易踩坑）

### 15.1 并发与一致性
- 同一用户并发下单：必须避免“余额被扣成负数”（事务行锁/冻结机制/乐观锁三选一）。
- 同一幂等键重复请求：返回同一订单/同一结果，不重复扣款/入账。
- 价格/折扣被修改：历史订单不受影响，必须依赖订单快照。

### 15.2 多租户隔离
- 任何带 `order_id/content_id/asset_id` 的 API，都必须校验其 `tenant_id` 属于当前上下文租户。
- 后台“按用户查询订单/余额”也必须限定到租户维度，避免跨租户泄露。

### 15.3 金额与舍入
- 金额统一使用整数分；percent 折扣的舍入规则需要固定（建议向下取整），并写入订单快照。

### 15.4 审计与追责
- 充值、退款、调账必须记录 `operator_user_id`、原因、时间、请求来源。
- 建议为后台敏感操作增加二次确认/权限分级（后续）。

### 15.6 试看与禁下载（3.B 已确认）
- 必须从“资源形态”上实现禁下载：preview 仅提供 60s 的独立转码产物，不复用 main 资源。
- 媒体访问接口仅下发短时效播放凭证/地址（例如签名 URL/Token），避免返回可长期复用的直链。
- 客户端不提供“下载”入口不构成安全措施，服务端与存储策略必须生效。

### 15.5 可观测性
- 关键链路（下单扣款/退款入账/上传处理）打点日志：tenant_id、user_id、biz_ref、耗时、结果码。