quyun-v2/backend/specs/spec01-gap-analysis.md

Spec01 vs 当前实现：功能对比与后续需求规则

本文基于 backend/specs/spec01.md，对照当前后端实现（数据表 / service / HTTP 路由），用于：

• 快速确认“已实现/部分实现/未实现”的范围边界；
• 固化后续需求补充时需要遵循的规则与约束，避免在多租户与资金链路上走偏。

1. 已实现（与 spec01 对齐）

1.1 多租户隔离与租户成员

• 租户上下文解析：所有租户 API 按 tenantCode 解析租户并写入 ctx（middleware）。
• 必须为租户成员：/t/:tenantCode/v1/* 默认强制登录 + 必须属于租户（middleware），不属于租户会直接拒绝。
• 角色模型：tenant_users.role（member/tenant_admin）存在，租户管理接口有 role 校验。
• 加入租户：支持邀请码加入与申请加入（tenantjoin 模块）。

1.2 余额体系（可用 + 冻结）与账本流水

• 账户维度：users(id)；字段包含 balance、balance_frozen（全局余额，可在已加入租户间共享消费）。
• 账本流水：tenant_ledgers 记录每次余额变更，含：
  • type（freeze / unfreeze / debit_purchase / credit_refund 等）；
  • balance_before/after、frozen_before/after 快照；
  • idempotency_key 唯一约束（tenant+user 维度）用于幂等落账。
• 一致性：账本落地实现包含行锁与“余额/冻结余额不得为负”的不变量校验。

1.3 内容、定价与权益

• 内容模型：contents（status/visibility/preview_seconds 等）。
• 内容定价：content_prices（price_amount + discount_* 时间窗）。
• 订单快照：购买时将价格/折扣/内容信息写入 orders.snapshot，避免改价影响历史订单。
• 权益模型：content_access(tenant_id,user_id,content_id)；购买授予 active，退款置为 revoked。
• 试看：区分 preview/main 资源角色；/preview 不要求购买，/assets 要求已购/免费/作者。

1.4 订单、购买、充值与退款

• 订单与明细：orders + order_items；支持 type=content_purchase 与状态流转。
• 购买（余额支付）：支持冻结→扣款（消耗冻结）→授予权益；并发靠行锁+冻结方案防止透支。
• 购买幂等：idempotency_key 支持“至多一次”购买语义；失败会写回滚标记并稳定返回“失败+已回滚”。
• 充值：已移除（不提供按租户充值能力）。
• 退款：租户管理员可对已支付订单退款；默认时间窗（paid_at + 24h），可 force 绕过；退款入账 + 回收权益。
• 后台订单查询：支持管理员按条件分页查询与导出（CSV）。

2. 部分实现 / 需要明确的差异点

2.1 “游客/公开内容”未落地

spec01 允许“游客/未加入租户用户浏览公开内容（若允许）”。当前实现中，/t/:tenantCode/v1/* 默认要求登录且必须是租户成员。

若要支持“公开内容给非成员/未登录用户访问”，需要单独的路由与中间件策略（至少绕过 TenantRequireMember，并重新定义 visibility=public 的含义）。

2.2 订单状态 refunding 未使用

spec01 给出 refunding 中间态建议；当前退款实现通常直接落到 refunded（事务内完成退款账本+权益回收+订单更新）。

若未来需要异步退款（例如接第三方支付、风控审核），应补齐 refunding 状态的状态机与重试/幂等规则。

2.3 操作者审计字段不完全结构化

spec01 建议在订单侧保留 operator_user_id 等结构化字段。当前实现：

• 退款操作者落在 orders.refund_operator_user_id；
• 充值操作者主要在 orders.snapshot/ledger remark 中体现（结构化程度较弱）。

若后续需要强审计/报表，应明确哪些操作必须“结构化字段 + 快照”双写。

3. 未实现（spec01 提到但系统暂缺）

3.1 MediaAsset 上传/处理全链路

已存在 media_assets 表及内容关联 content_assets，但目前缺少：

• 上传/回调/转码/处理状态流转接口；
• 存储签名 URL/防盗链/短时 token 下发机制；
• “preview 资源必须是独立转码产物”的生产链路约束与校验。

4. 后续需求“规则”（建议强制遵循）

4.1 多租户规则（硬约束）

• 所有新增业务表必须具备 tenant_id，或能从主实体可推导且在查询/写入时强校验租户边界。
• 每个 HTTP API 必须明确：是否需要登录、是否需要租户成员、是否需要 tenant_admin、是否允许跨租户访问（默认禁止）。

4.2 资金/余额规则（硬约束）

• 任何会改变余额/冻结余额的行为，都必须：
  • 走账本（tenant_ledgers）并记录 before/after；
  • 定义唯一幂等键策略（稳定、可重放、可查证）；
  • 明确事务边界与失败补偿（尤其是“冻结成功但后续失败”的回滚路径）。
• 余额不允许为负；冻结余额不允许为负；这是系统级不变量，需求不得破坏。

4.3 订单规则（硬约束）

• 订单必须有快照（至少包含：内容标题、定价、折扣、成交价、时间、请求 idempotency_key）。
• 任何“可重试”的下单/退款/充值动作必须给出幂等语义：重复请求返回同一结果，不重复扣款/入账。
• 需求必须明确：失败时是否保留订单、订单处于何种终态、以及客户端应如何重试。

4.4 权益与资源访问规则（硬约束）

• “是否可看正片”只取决于：免费/作者/权益（content_access=active）；客户端表现不构成安全措施。
• 试看资源必须与正片资源隔离（不同 asset role + 不同存储对象），需求不得允许复用正片资源做试看。
• 退款后权益必须立即失效（revoked），并且该规则优先级高于缓存/前端展示。

4.5 状态机与审计规则（建议）

• 对所有引入状态的实体（content/order/media_asset/tenant_user），需求必须附带：
  • 允许的状态集合；
  • 允许的状态迁移；
  • 幂等行为（重复迁移是否允许、返回什么）。
• 对敏感操作（充值/退款/调账/封禁），需求必须明确：
  • 操作者字段（operator_user_id）是否结构化落库；
  • 原因字段是否必填；
  • 审计可检索性（按租户/用户/时间/单据维度）。

5. 参考实现位置（便于后续对齐）

• 数据库迁移：
  • backend/database/migrations/20251216011456_tenant_users.sql
  • backend/database/migrations/20251217223000_media_contents.sql
  • backend/database/migrations/20251218120000_orders_ledgers.sql
• 中间件（租户上下文/成员校验）：
  • backend/app/middlewares/tenant.go
  • backend/app/http/tenant/routes.manual.go
  • backend/app/http/tenant_join/routes.manual.go
• 业务服务（核心资金与订单链路）：
  • backend/app/services/ledger.go
  • backend/app/services/order.go
  • backend/app/services/content.go
• HTTP 路由（对外能力清单）：
  • backend/app/http/tenant/*.go
  • backend/app/http/tenant_join/*.go
  • backend/app/http/super/*.go（可选：平台侧）