quyun-v2/docs/todo_list.md

TODOlist（需求梳理 + 技术方案）

目标：作为后续开发与测试的对照清单，明确范围、方案、接口、数据与测试策略。

当前范围与约束

• 认证仅使用 JWT（不做 OAuth/Cookie 方案）。
• 支付集成暂不做，订单/退款仅按既有数据结构做流程与统计。
• 存储需要接入本地 MinIO 进行真实 Provider 模拟，保留本地 FS 作为兜底。
• 当前测试只使用本地存储；S3 存储测试后续独立进行。
• 多租户路由强隔离（/t/:tenantCode/v1 + TenantResolver）已启用，后续仅做细节优化。

统一原则

• 所有后端改动遵循 backend/llm.txt 规范与 GORM-Gen 访问方式。
• 分层约束：Controller 仅做绑定与调用，业务与 DB 仅在 services。
• 每个需求至少配套：接口说明 + 数据变更（如有）+ 关键业务校验 + 单元测试。

测试规范

服务测试（必须）

• 使用 Convey + testify/suite 框架（参考 backend/tests/README.md）。
• 每个服务方法至少覆盖：正常路径 + 主要错误分支。
• 数据准备使用 database.Truncate + 直接 GORM-Gen 创建。
• 断言使用 Convey 的 So 函数，遵循 当...那么... 语义结构。

中间件测试（按需）

• HTTP 层行为使用 httptest + fiber.Test。
• 验证响应码 + 响应体 + ctx.Locals 状态。

集成测试（关键路径）

• 覆盖完整业务流程（如：申请 → 审核 → 成员可见）。
• 使用真实 DB 连接（v2_test 数据库）。

前端验收

• 当前依赖手动验收（参考 docs/seed_verification.md）。
• 重要流程变更需截图或录屏确认。

测试覆盖现状

模块	状态	测试文件	覆盖范围
租户成员体系	✅ 完善	tenant_member_test.go	申请/取消/审核/邀请/成员管理
上传会话归属	✅ 完善	common_test.go	owner 校验/forbidden/not found
内容访问策略	✅ 完善	content_test.go	tenant_only/private/preview/guest/full
鉴权与权限	✅ 完善	user_test.go, middlewares_test.go	OTP 登录 + 成员校验 + 中间件
审计参数传递	✅ 完善	audit_test.go	落库/查询/跨租户筛选

待补充测试用例

T1) 鉴权中间件测试（已完成）

测试文件：backend/app/middlewares/middlewares_test.go

已覆盖场景：

• AuthOptional：无 token 访问正常通过，ctx.Locals 无 user
• AuthOptional：有效 token 访问，ctx.Locals 有 user
• AuthRequired：无 token 访问返回 401
• AuthRequired：过期 token 返回 401
• AuthRequired：有效 token 正常通过
• super_admin 校验：非 super_admin 角色访问 /super/v1/* 返回 403
• super_admin 校验：super_admin 角色访问正常通过

T2) 审计日志测试（已完成）

测试文件：backend/app/services/audit_test.go

已覆盖场景：

• Audit.Log 正常落库：验证 tenantID/operatorID/action/targetID/detail
• Audit.Log 缺参：operatorID=0 时行为（warn 日志）
• 审计记录可查询：按 tenant/operator/action 筛选

T3) 内容访问策略测试补充（已完成）

扩展文件：backend/app/services/content_test.go

已覆盖场景：

• 未登录访问 public 内容：仅 preview + cover
• 已购买访问：完整 media
• 作者/管理员访问 private：完整 media
• 非成员访问 tenant_only：forbidden 或仅 preview

T4) 超管写操作测试（已完成）

扩展文件：backend/app/services/super_test.go

已覆盖场景：

• CreateTenant：验证 expired_at 计算正确
• CreateTenant：验证 tenant_users 管理员关系写入
• 创作者设置读写：超管可读取/更新任意租户设置
• 收款账户管理：超管新增/编辑/禁用
• 用户资料编辑：超管可更新基础字段

P0（必须先做）

1) 租户成员体系（加入/邀请/审核）（已完成）

需求目标

• 完成租户成员生命周期：申请加入、审核通过/拒绝、邀请加入。
• tenant_only 内容在“成员审核通过”后可访问；未审核需前置引导。

技术方案（后端）

• API
  • 申请加入：POST /t/:tenantCode/v1/tenants/:id<int>/join
  • 取消申请：DELETE /t/:tenantCode/v1/tenants/:id<int>/join
  • 接受邀请：POST /t/:tenantCode/v1/tenants/:id<int>/invites/accept
  • 管理员审核：POST /t/:tenantCode/v1/creator/members/:id<int>/review
  • 邀请成员：POST /t/:tenantCode/v1/creator/members/invite
• DB
  • 使用现有 tenant_join_requests / tenant_invites 表（如已存在则复用；缺失则通过迁移新增）。
• Service
  • 校验：用户是否已是成员/是否已申请；审核流转合法性；邀请有效期。
  • 申请成功后写 tenant_join_requests；审核通过写 tenant_users。
  • 对 tenant_only 内容访问：需要 tenant_users.status=verified 或已购买。

测试方案（✅ 已覆盖 tenant_member_test.go）

• 申请加入：创建 pending 请求、重复申请拦截、已是成员时拒绝。
• 取消申请：正常取消、请求不存在时返回 not found。
• 审核流程：approve 后写入 tenant_users、reject 后状态变更。
• 邀请创建：生成有效邀请码、设置过期时间与使用次数。
• 接受邀请：正常加入、used_count 递增、邀请失效后拒绝。
• 成员管理：列表分页、移除成员后不可查。
• 邀请管理：列表查询、禁用邀请后状态变更。

2) 鉴权与权限收口（必需）（已完成）

需求目标

• 受保护接口强制鉴权，超管接口增加 super_admin 角色校验。
• 补齐 Super.Login / CheckToken 逻辑。

技术方案（后端）

• 中间件：拆分 AuthOptional / AuthRequired，路由按需使用。
• 超管接口：校验 JWT roles 含 super_admin。
• 服务：补齐登录、token 续期/失效逻辑。

测试方案（✅ 已覆盖 user_test.go/middlewares_test.go）

• ✅ 已覆盖：OTP 登录 + 租户成员校验（允许登录，资源访问再校验权限）。
• ✅ 已覆盖：User.Me 无 context user 时失败。
• ✅ 已覆盖：AuthOptional/AuthRequired 中间件行为（见 T1）。
• ✅ 已覆盖：super_admin 角色校验（非超管访问 /super/v1/* 返回 403）。

3) 上传会话归属测试补齐（已完成）

需求目标

• 覆盖上传会话归属校验的服务测试（防止越权）。

技术方案（后端）

• 为 Common.UploadPart 增加服务测试，验证 owner mismatch 返回 ErrForbidden。

测试方案（✅ 已覆盖 common_test.go）

• AbortUpload：owner 可取消、非 owner 返回 forbidden、不存在返回 not found。
• UploadPart：owner 可上传、非 owner 返回 forbidden。

4) 超管全量可编辑（补齐写操作缺口）（已完成）

需求目标

• 超管可对系统内现有对象执行“修改/新增/删除/审核”等操作，不受租户边界限制。
• 补齐已存在能力但缺少 /super/v1 写入口的模块。

技术方案（后端）

• 租户创建完善
  • POST /super/v1/tenants：补齐 expired_at（基于 duration）与 tenant_users 管理员成员关系写入。
• 创作者设置超管入口
  • 新增 GET /super/v1/creators/:tenantID<int>/settings
  • 新增 PUT /super/v1/creators/:tenantID<int>/settings
  • 复用 services.Creator.GetSettings/UpdateSettings，由超管直传 tenantID + operatorID。
• 收款账户超管管理
  • 新增 POST /super/v1/creators/:tenantID<int>/payout-accounts
  • 新增 PATCH /super/v1/payout-accounts/:id<int>（编辑/禁用/备注）
  • 复用现有收款账户结构体与校验逻辑。
• 用户资料超管编辑
  • 新增 PATCH /super/v1/users/:id<int>（允许更新昵称/头像/实名标记等基础字段）。

测试方案（✅ 已覆盖 super_test.go）

• ✅ CreateTenant 后 expired_at 与 tenant_users 均落库。
• ✅ 超管读取/更新创作者设置。
• ✅ 超管新增/编辑收款账户。
• ✅ 超管更新用户资料，字段校验生效。

5) 通知模板支持编辑（已完成）

需求目标

• 支持模板更新、启用/停用，避免误建模板不可修正。

技术方案（后端/前端）

• API
  • 新增 PATCH /super/v1/notifications/templates/:id<int>
  • （可选）新增 DELETE /super/v1/notifications/templates/:id<int>
• 前端：Notifications.vue 增加“编辑模板”弹窗与启用开关。

测试方案

• 编辑模板后列表与详情一致。
• 禁用模板后不允许用于群发（或提示不可用）。

6) 本地 MinIO 模拟真实存储 Provider（已完成）

需求目标

• 本地环境可用 MinIO 模拟真实 S3 Provider，验证上传/访问链路。

技术方案（后端/本地环境）

• Docker：拉起 MinIO（含 access/secret、bucket 初始化）。
• Storage 配置支持 S3/MinIO 模式（endpoint + path style）。
• 更新 docs/storage_provider.md 与新增 smoke test 文档。

测试方案

• 上传 -> MinIO -> 读取 URL 可访问。
• 本地 FS 与 MinIO 配置切换可用。

---

P1（高优先）

7) ID 类型统一（int64 / model 注入）（已完成）

需求目标

• 所有业务 ID 使用 int64，路由参数统一 :id<int>。

技术方案（后端）

• Controller/DTO：string → int64，补齐字段级中文注释。
• Service：移除 cast.ToInt64，使用 int64 与 model 注入。
• Swagger/Route：补齐 <int> 约束。

测试方案

• 关键接口：正常请求 + 参数类型错误时返回明确错误。

8) 内容访问策略完善（资源权限与预览差异化）（已完成）

需求目标

• 媒体资源访问遵循：未购仅预览，已购全量，作者/管理员全量。
• 签名 URL 或下载地址生成前进行权限校验。

技术方案（后端）

• Service
  • Content.Get 根据 visibility + status + access 决定 MediaUrls。
  • Common.GetAssetURL 或资源下载接口增加权限校验参数（通过内容ID校验）。
• 规则
  • public + 未购：仅 preview + cover
  • tenant_only + 已购/成员/作者/管理员：完整
  • private：仅作者/管理员

测试方案（✅ 已覆盖 content_test.go）

• ✅ tenant_only 访问（成员/管理员允许，非成员拒绝）。
• ✅ private 内容访问（仅作者可见）。
• ✅ preview vs full 逻辑（guest/owner/buyer）。
• ✅ 未登录访问 public 内容仅返回 preview + cover。

9) 审计参数传递规范化（已完成）

需求目标

• 审计服务禁止自行读取 ctx，改为显式传入操作者信息。

技术方案（后端）

• 调整 services.Audit 方法签名与调用方传参。
• 关键操作补齐操作者字段。

测试方案（✅ 已覆盖 audit_test.go）

• ✅ Audit.Log 正常落库，验证各字段。
• ✅ 审计记录可按 tenant/operator/action 筛选。

10) 创作者中心 - 团队成员管理（Portal UI）（已完成）

需求目标

• 补齐创作者侧成员列表/邀请/审核等管理能力，覆盖成员生命周期。
• 角色/状态可视化，支持管理员移除或禁用成员。

技术方案（前端/后端）

• 前端：frontend/portal/src/views/creator/ 新增成员管理页面（列表/邀请/审核）。
• API（如缺失需补齐）：
  • 成员列表：GET /t/:tenantCode/v1/creator/members
  • 邀请列表/撤销：GET /t/:tenantCode/v1/creator/members/invites、DELETE /t/:tenantCode/v1/creator/members/invites/:id<int>
  • 申请列表：GET /t/:tenantCode/v1/creator/members/join-requests
  • 已有：POST /t/:tenantCode/v1/creator/members/invite、POST /t/:tenantCode/v1/creator/members/:id<int>/review
• Service：复用 services.Tenant 现有邀请/审核逻辑，补齐列表查询与权限校验。

测试方案

• 列表分页/筛选；邀请创建/撤销；审核通过后成员列表可见；权限拦截。

---

P2（中优先）

11) 运营统计报表（曝光/转化/订单/退款）（已完成）

需求目标

• 提供租户维度与时间范围的核心指标统计与导出。

技术方案（后端）

• API
  • 总览：GET /t/:tenantCode/v1/creator/dashboard（已有，需扩展）
  • 明细统计：GET /t/:tenantCode/v1/creator/reports/overview
  • 导出：POST /t/:tenantCode/v1/creator/reports/export
• Service
  • 聚合：订单、退款、内容曝光（views/likes）、转化率（访问->成交）。
• 导出：同步 CSV（如需异步任务与下载链接，可在后续迭代补齐）。

测试方案

• 统计口径一致性；筛选组合；导出任务可用性。

12) 超管后台治理能力（健康度/异常监控/内容审核）（已完成）

需求目标

• 提供超管对租户的健康指标、异常趋势、内容合规审核。

技术方案（后端）

• API
  • 租户健康度统计：GET /super/v1/tenants/health
  • 内容审核流：POST /super/v1/contents/:id<int>/review
• Service
  • 指标聚合 + 异常阈值定义。
  • 审核状态流转与通知。

测试方案

• 审核状态流转有效性；异常阈值命中结果。

13) 性能优化（避免 N+1）（已完成）

需求目标

• 列表/统计场景避免逐条查询。

技术方案（后端）

• 引入批量查询/聚合 SQL，替换逐条查询。
• 重点：订单列表、租户列表统计。

测试方案

• 对比查询次数/耗时（可选） + 数据正确性。

14) 租户公开页完善（Portal）（已完成）

需求目标

• 完善租户主页信息与内容聚合体验。

技术方案（前端/后端）

• 前端：frontend/portal/src/views/tenant/ 增加简介/关于模块。
• 若内容聚合维度不足，补齐筛选参数（如专辑/最新/最热）与接口字段。

测试方案

• 不同筛选维度下内容列表正确；空内容/无简介时展示兜底。

15) 微信生态清理（已完成）

需求目标

• 移除微信登录/分享/支付相关逻辑，降低维护成本。

技术方案（后端/前端/文档）

• 后端：清理 auth 路由与服务中的微信授权/回调逻辑（如存在）。
• 前端：移除 Portal 登录页/分享中的微信依赖与 UI。
• 配置/文档：清理 config.toml、specs/*、docs/* 的微信配置与说明；移除无用 SDK 依赖。

测试方案

• 登录、分享、支付路径不再引用微信 SDK；构建与 lint 通过。

---

P3（延后）

16) 真实存储 Provider 接入（生产）（已完成）

需求目标

• 接入 OSS/云存储（生产环境），统一上传/访问路径策略。

技术方案（后端）

• 通过配置注入 Provider，保留本地 FS/MinIO 作为 dev fallback。
• 已完成：
  • backend/config.prod.toml 配置生产 MinIO（quyun-01 bucket）
  • CheckOnBoot 启动时自检连通性
  • 完整 E2E 测试验证：InitUpload → UploadPart → CompleteUpload → 签名URL访问 → Delete

测试方案

• ✅ 本地 FS 配置可用（开发默认）
• ✅ MinIO S3 Provider 配置可用（config.prod.toml）
• ✅ 上传/访问/删除完整链路验证通过

17) 媒体处理管线适配对象存储（S3/MinIO）（已完成）

需求目标

• 在对象存储模式下，媒体处理任务可完整执行并回传产物。

技术方案（后端）

• Worker：从对象存储下载源文件到临时目录 → FFmpeg 处理 → 结果上传回对象存储 → 清理临时文件。
• 产物：封面/预览片段自动生成并回写 media_assets。
• 本地 FS 仍保留兼容路径（开发/测试使用）。
• 已完成：
  • Storage.Download 支持 local copy + S3 FGetObject
  • MediaProcessWorker 支持对象存储流程（下载 → FFmpeg → 上传封面 → 清理）
  • 封面派生资产在 S3 模式走 PutObject（不再 rename）

测试方案

• ✅ ENV_LOCAL=test go test ./backend/app/jobs -run Test_MediaProcessWorkerLocal -count=1
• ✅ ENV_LOCAL=minio go test ./backend/app/jobs -run Test_MediaProcessWorkerS3 -count=1

18) 支付集成（已调整为余额支付）

需求目标

• 移除第三方支付，仅保留余额支付。
• 充值通过充值码兑换或超管充值完成。
• 充值码激活/兑换全链路审计。

技术方案（后端）

• 去除外部支付入口与回调，订单仅支持 balance。
• 新增充值码表 + 激活/兑换服务，超管可批量生成充值码。
• 超管可直接为用户充值，生成充值订单与账本记录。

测试方案

• 余额支付下单/支付成功。
• 充值码激活、兑换成功后余额到账。
• 超管充值成功写入订单与账本。

---

已完成

• 租户成员体系（加入/邀请/审核）。
• 鉴权与权限收口（AuthOptional/AuthRequired、super_admin 校验、Super.Login/CheckToken）。
• 鉴权中间件测试与审计日志测试补齐。
• 上传会话归属测试补齐（UploadPart owner mismatch）。
• ID 类型统一（int64 / model 注入，upload_id 等非数值标识除外）。
• 内容访问策略完善（资源权限与预览差异化）。
• 内容访问策略测试补齐（guest/owner/buyer/tenant_only）。
• 审计参数传递规范化（Audit 显式传参）。
• 审计操作显式传入操作者信息（服务层不再依赖 ctx 读取）。
• 超管全量可编辑（租户创建补齐、创作者设置/结算账户/用户资料写入口）。
• 超管写操作测试补齐（创作者设置/收款账户/用户资料）。
• OTP 登录流程与租户成员校验（允许登录，资源访问再校验权限）。
• 通知模板支持编辑（超管接口 + 前端编辑入口）。
• 本地 MinIO 模拟真实存储 Provider（本地容器与文档指引）。
• 运营统计报表（overview + CSV 导出基础版）。
• 超管后台治理能力（健康度/异常监控/内容审核）。
• 性能优化（避免 N+1：订单/租户列表批量聚合 + topics 聚合）。
• 多租户强隔离（/t/:tenantCode/v1 + TenantResolver）。
• 真实存储 Provider 接入（生产 MinIO S3 配置与 E2E 验证）。
• 媒体处理管线适配对象存储（S3/MinIO）。

里程碑建议

• M1：完成 P0
• M2：完成 P1
• M3：完成 P2