quyun-v2/docs/todo_list.md

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

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

## 当前范围与约束
- 认证仅使用 JWT（不做 OAuth/Cookie 方案）。
- 支付集成暂不做，订单/退款仅按既有数据结构做流程与统计。
- 存储需要接入本地 MinIO 进行真实 Provider 模拟，保留本地 FS 作为兜底。
- 多租户路由强隔离（`/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 |
| 鉴权与权限 | ⚠️ 部分 | `user_test.go` | 仅 OTP 登录 + 成员校验，缺中间件测试 |
| 审计参数传递 | ❌ 缺失 | 无 | 无测试覆盖 |

## 待补充测试用例

### 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 日志）
- 关键操作触发审计：如 `ReviewJoin` 后 `audit_logs` 有对应记录
- 审计记录可查询：按 `tenant`/`operator`/`action` 筛选

### T3) 内容访问策略测试补充
**扩展文件**：`backend/app/services/content_test.go`

**补充场景**：
- 未登录访问 public 内容：仅 preview + cover
- 已购买访问：完整 media
- 作者/管理员访问 private：完整 media
- 非成员访问 tenant_only：forbidden 或仅 preview
- 签名 URL 生成前权限校验

### 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`，缺中间件测试）
- ✅ 已覆盖：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`，待扩展见 T4）
- ✅ 基础：`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`，待扩展见 T3）
- ✅ 已覆盖：`tenant_only` 访问（成员/管理员允许，非成员拒绝）。
- ✅ 已覆盖：`private` 内容访问（仅作者可见）。
- ✅ 已覆盖：preview vs full 逻辑（guest/owner/buyer）。
- ❌ 待补充：未登录访问 public 内容仅返回 preview + cover。
- ❌ 待补充：签名 URL 生成前权限校验。

### 9) 审计参数传递规范化（已完成）
**需求目标**
- 审计服务禁止自行读取 `ctx`，改为显式传入操作者信息。

**技术方案（后端）**
- 调整 `services.Audit` 方法签名与调用方传参。
- 关键操作补齐操作者字段。

**测试方案**（❌ 缺失，待补充见 T2）
- 待补充：`Audit.Log` 正常落库，验证各字段。
- 待补充：关键操作（如 `ReviewJoin`）触发审计记录。
- 待补充：审计记录可按 `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。
- 进度：已补齐 S3 配置示例与 `CheckOnBoot` 可选自检开关。

**测试方案**
- 本地 FS + MinIO + 真实 Provider 三套配置可用性。

### 17) 媒体处理管线适配对象存储（S3/MinIO）
**需求目标**
- 在对象存储模式下，媒体处理任务可完整执行并回传产物。

**技术方案（后端）**
- Worker：从对象存储下载源文件到临时目录 → FFmpeg 处理 → 结果上传回对象存储 → 清理临时文件。
- 产物：封面/预览片段自动生成并回写 `media_assets`。
- 本地 FS 仍保留兼容路径（开发/测试使用）。
 - 进度：本地视频处理已可生成封面资产（ffmpeg 可用时）。

**测试方案**
- 对象存储模式下上传视频触发处理，封面/预览可访问；任务异常可重试。

### 18) 支付集成
**需求目标**
- 最终阶段对接真实支付。

**技术方案（后端）**
- 接入支付网关并补齐回调/退款逻辑。

**测试方案**
- 沙箱支付 + 回调验签。

---

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

## 里程碑建议
- M1：完成 P0
- M2：完成 P1
- M3：完成 P2