quyun-v2/backend/specs/spec01-backlog.md

Spec01 可执行 Backlog（按接口/表/状态机/验收用例）

本文从 backend/specs/spec01-gap-analysis.md 的“差异点/未实现项”拆解为可落地的 backlog。每条尽量可独立开发、可验收、可回滚。

0. 约定（用于所有条目）

• P0/P1/P2：优先级从高到低；P0=阻塞核心目标，P1=重要增强，P2=可延后。
• 验收方式：默认用“service 测试 + http 层冒烟”覆盖；涉及对象存储/转码的条目允许先用 mock/本地 minio 方案。
• 租户隔离硬约束：任何带 id 的资源访问都必须校验 tenant_id 边界。

Epic A：公开内容/游客访问（当前未落地）

当前 /t/:tenantCode/v1/* 默认强制“登录 + 必须是租户成员”，不满足 spec01 的“游客可浏览公开内容（若允许）”。

A1（P0, Middleware/API）增加“公开读接口路由组”

• 新增路由组（建议二选一）：
  1. GET /t/:tenantCode/v1/public/contents（公开列表）
  2. GET /t/:tenantCode/v1/public/contents/:contentID（公开详情）
  3. GET /t/:tenantCode/v1/public/contents/:contentID/preview（公开试看资源）
• 中间件策略：
  • 仅 TenantResolve；
  • 可选 TenantOptionalAuth：有 token 则解析写 ctx，无 token 允许继续（用于展示“已购/作者/已登录”差异）。
• 响应语义：
  • 仅返回 visibility=public 且 status=published 的内容；
  • HasAccess 在公开接口里定义为：free || owner || purchased（若无登录则恒为 false，除非 free=真）。
• 验收用例：
  • 未登录可拉取公开内容列表/详情/preview；
  • 未登录访问 visibility=tenant_only/private 返回权限错误或 404（按统一策略定）；
  • 已登录但非成员：公开内容可读；非公开内容不可读；购买/余额接口不可用。

A2（P1, State/Rule）明确 visibility 与主资源访问关系

• 规则固化（写入接口文档 + tests）：
  • visibility 只控制“内容详情是否可见”；主资源（main role）仍需 free/owner/purchased；
  • public + free 是否允许游客看正片：需要业务明确（建议允许，减少“公开但看不了”的困惑）。
• 验收用例：
  • public + price=0：游客能拿到 main assets；
  • public + price>0：游客不能拿到 main assets，但能拿到 preview assets。

Epic B：MediaAsset 上传/处理全链路（当前缺失）

已有 media_assets、content_assets 表，但缺少“上传→处理→对外下发”的闭环接口与状态机。

B1（P0, API）上传初始化：申请上传凭证/直传参数

• 新增接口（tenant_admin）：
  • POST /t/:tenantCode/v1/admin/media_assets/upload_init
• 请求字段：
  • type（video/audio/image）
  • content_type（mime，可选）
  • file_size（可选，用于限额）
  • sha256（可选，用于去重/审计）
• 返回字段（按存储 provider 定）：
  • asset_id
  • upload_url / form_fields（S3 POST policy）/ headers
  • expires_at
• DB：
  • 创建 media_assets(status=uploaded, provider/bucket/object_key/meta)；
  • object_key 由后端生成，避免客户端指定路径。
• 验收用例：
  • tenant_admin 调用成功返回可用上传信息；
  • member/非 admin 调用被拒绝；
  • asset 必须绑定正确 tenant_id/user_id。

B2（P0, API/State）上传完成回调：触发处理并进入 processing

• 新增接口（tenant_admin 或 system）：
  • POST /t/:tenantCode/v1/admin/media_assets/:assetID/upload_complete
• 行为：
  • 校验 asset.status=uploaded；
  • 写入必要 meta（duration/width/height 可后置）；
  • 状态迁移：uploaded -> processing；
  • 触发异步处理（先允许 stub：写入任务表或发消息）。
• 验收用例：
  • 重复调用幂等（第二次返回同一结果，不重复触发任务）；
  • 非法状态迁移返回明确错误码（status conflict）。

B3（P1, API）查询资源：详情与列表

• 新增接口（tenant_admin）：
  • GET /t/:tenantCode/v1/admin/media_assets
  • GET /t/:tenantCode/v1/admin/media_assets/:assetID
• 查询字段：
  • status/type/created_at 过滤；分页。
• 验收用例：
  • 只能查本租户资源；
  • deleted_at 过滤策略一致（默认不返回已删除）。

B4（P1, State Machine）固化 media_assets 状态机与允许迁移

• 状态集合：uploaded/processing/ready/failed/deleted。
• 允许迁移：
  • uploaded → processing
  • processing → ready | failed
  • ready/failed → deleted（软删）
• 验收用例：
  • 任意越权迁移失败；
  • ready 才允许绑定到 content_assets（见 Epic C）。

Epic C：资源下发与防直链（当前为“返回对象信息”，未形成安全下发）

目前内容资源接口返回 models.MediaAsset，可能包含 bucket/object_key 等内部定位信息；spec01 希望通过“短时效播放凭证/签名 URL/token”下发，并且 preview 与 main 资源彻底区分。

C1（P0, API/DTO）资源下发改为“签名 URL/Token”响应

• 调整接口返回 DTO：
  • GET /t/:tenantCode/v1/contents/:contentID/preview
  • GET /t/:tenantCode/v1/contents/:contentID/assets
• 响应字段建议：
  • asset_id
  • type
  • play_url（短时效）
  • expires_at
  • meta（可展示字段的白名单，如 duration/width/height）
• 实现要点：
  • 后端对 provider（minio/s3/oss）生成签名 URL；
  • 绝不返回可长期复用的直链或裸 object_key（除非配置允许且仅内网）。
• 验收用例：
  • 返回的 URL 具备过期时间；
  • 无权限时不返回任何可用播放地址；
  • 日志/审计中记录 tenant_id/content_id/user_id/role/asset_id。

C2（P1, Rule/Validation）校验 preview 必须独立产物

• 约束（二选一落库方式）：
  1. media_assets.meta.variant=preview/main（或 is_preview）
  2. 新增列 media_assets.variant（枚举）
• 绑定校验：
  • content_assets.role=preview 只能绑定 variant=preview；
  • role=main 只能绑定 variant=main。
• 验收用例：
  • 用 main 资源绑定 preview 被拒绝；
  • preview 秒数只对 preview 下发生效。

Epic D：异步退款/风控预留（当前 refunding 未使用）

D1（P2, State Machine）引入 refunding 并定义状态迁移

• 订单状态机补齐：
  • paid → refunding → refunded | failed
• 接口语义：
  • POST refund 返回 refunding；
  • 单独的 job/worker 完成 credit_refund + revoke access + status->refunded。
• 验收用例：
  • 重复退款请求幂等；
  • refunding 期间不得重复扣款/重复回收权益；
  • 失败可重试（明确重试幂等键策略）。

Epic E：审计字段结构化（当前充值操作者更多在 snapshot/remark）

E1（P1, DB/API）tenant_ledgers 增加操作者字段与业务引用字段

• DB 变更（建议）：
  • tenant_ledgers.operator_user_id bigint NULL
  • tenant_ledgers.biz_ref_type varchar(32) NULL（order/refund/topup/etc）
  • tenant_ledgers.biz_ref_id bigint NULL
  • 对 (tenant_id, biz_ref_type, biz_ref_id, type) 做唯一约束（或与 idempotency_key 二选一作为主幂等源）。
• 验收用例：
  • 充值/退款/购买相关 ledger 必须写入 operator_user_id（admin/buyer/system）；
  • 后台可按 operator_user_id 检索敏感操作流水。

E2（P1, DB/Order）topup 结构化操作者字段（可选）

• DB 变更（二选一）：
  1. 在 orders 增加 operator_user_id（对 topup 更直观）
  2. 保持在 snapshot，但保证 ledger/operator 字段可追溯
• 验收用例：
  • 导出订单时能明确区分“充值发起人”和“充值受益人”。

1. 建议交付顺序（最小闭环）

1. A1 → A2（先把公开读能力与语义定死）
2. B1 → B2 → B4（上传/处理状态机闭环；任务系统可先 stub）
3. C1 → C2（把资源下发安全化，再强制 preview 独立产物）
4. E1（审计增强，避免后续追溯成本）
5. D1（如确需异步退款/风控，再引入）