quyun-v2/docs/plan.md

# Implementation Plan: 生产部署能力补齐（数据源统一、隔离强化、双侧审计）

**Branch**: `[prod-readiness-hardening]` | **Date**: 2026-02-08 | **Spec**: 会话需求（评估并补齐生产部署能力）
**Input**: 用户要求按 4 项标准补齐生产部署能力：
1) 前端数据来源后端接口/渲染；
2) 用户/租户数据隔离完备；
3) 超级管理员后台可审计；
4) 租户管理侧可审计。

## Summary

当前评估结果为：
- #1 前端数据来源：未完全达标（存在硬编码业务数据页面）；
- #2 用户/租户隔离：基础机制已具备，但依赖服务层手工加租户条件，仍有遗漏风险；
- #3 超管审计：已具备（audit_logs 表 + 超管查询页面/API）；
- #4 租户侧审计：未达标（仅有 audit 类通知，不等同审计日志查询能力）。

本计划目标是在最小风险下将以上 4 项全部提升为可上线状态：
- 去除生产路径硬编码业务数据；
- 强化多租户隔离“可证明性”（代码约束 + 负向测试）；
- 保持并补强超管审计覆盖；
- 增加租户管理侧可审计能力（租户范围审计日志查询 API + 页面）；
- 建立可审签发布证据链（route/swagger/test/UI flow/evidence/archive）。

## Technical Context

**Language/Version**:
- Backend: Go（Fiber + GORM-Gen）
- Frontend: Vue 3 + Vite（portal/superadmin）

**Primary Dependencies**:
- Backend: `backend/app/http/v1`, `backend/app/http/super/v1`, `backend/app/services/*`, `backend/database/models/*`
- Frontend: `frontend/portal/src/views/*`, `frontend/portal/src/api/*`, `frontend/superadmin/src/views/superadmin/*`, `frontend/superadmin/src/service/*`
- Generators: `atomctl gen route`, `atomctl swag init`

**Storage**:
- PostgreSQL（`audit_logs` 已存在，必要时补索引/查询优化）

**Testing**:
- Backend: `cd backend && env GOCACHE=$PWD/.gocache GOTMPDIR=$PWD/.gotmp go test ./...`
- Frontend Build/Lint:
  - `npm -C frontend/portal run build`
  - `npm -C frontend/portal run lint`
  - `npm -C frontend/superadmin run build`
  - `npm -C frontend/superadmin run lint`
- Frontend功能验收（页面流）:
  - 超管审计日志查询流
  - 租户管理侧审计日志查询流
  - 用户“我的点赞/收藏/订单”等后端数据回填流

**Target Platform**:
- Linux 部署环境（Web + API）

**Project Type**:
- Web application（frontend + backend）

**Performance Goals**:
- 审计日志列表接口在常规分页（20条）下 p95 <= 300ms（预发基准）
- 不引入明显回归（核心列表接口不劣化）

**Performance Measurement Protocol**:
- 测量接口：`/super/v1/audit-logs` 与新增租户审计列表接口。
- 测量条件：`page=1&limit=20`，默认排序（`created_at desc`），不带 keyword。
- 样本规则：预热 10 次后连续采样 50 次，统计 p95。
- 证据输出：写入 `docs/release-evidence/<date>.md` 的“性能基线”小节。

**Constraints**:
- 禁止手改 `*.gen.go`（路由/文档生成文件仅通过工具生成）
- 控制器保持薄层（bind -> services -> return）
- 不使用 `as any` / `@ts-ignore` / `@ts-expect-error`
- 缺陷修复最小化，不做无关重构

**Scale/Scope**:
- 覆盖 portal + superadmin + backend v1/super v1 审计与隔离相关模块
- 覆盖上线阻塞项（P0）与并行优化项（P1）

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- ✅ 符合后端分层：Controller 不直接做 DAO CRUD，统一走 `services.*`
- ✅ 符合生成文件约束：路由与 Swagger 仅通过 `atomctl` 生成
- ✅ 符合多租户前缀规范：`/v1/t/:tenantCode/*`
- ✅ 覆盖前后端联调验收要求：前端页面流 + `go test ./...`
- ✅ 计划包含任务拆解、依赖、验收标准、风险项、责任归属与里程碑

## Project Structure

### Documentation (this phase)

```text
docs/
├── plan.md                               # 当前执行计划（本文件）
├── release-evidence/<date>.md            # 验收证据模板与执行结果
└── plans/<date>.md                       # 阶段完成归档
```

### Source Code (repository root)

```text
backend/
├── app/http/v1/
│   ├── routes.manual.go
│   ├── routes.gen.go                     # 生成文件（勿手改）
│   ├── user.go
│   ├── creator.go
│   └── (new) audit_logs.go               # 若新增租户侧审计接口
├── app/http/super/v1/
│   ├── audit_logs.go
│   ├── routes.manual.go
│   └── routes.gen.go                     # 生成文件（勿手改）
├── app/services/
│   ├── audit.go
│   ├── order.go
│   ├── content.go
│   ├── coupon.go
│   ├── tenant*.go
│   └── super.go
└── docs/
    ├── docs.go                           # 生成文件（勿手改）
    ├── swagger.yaml                      # 生成文件（勿手改）
    └── swagger.json                      # 生成文件（勿手改）

frontend/
├── portal/
│   └── src/
│       ├── api/
│       ├── router/index.js
│       └── views/
└── superadmin/
    └── src/
        ├── router/index.js
        ├── service/
        └── views/superadmin/
```

**Structure Decision**: 在现有目录内增量修复，不新增独立子项目；优先复用现有 service 与 DTO，确保变更可控。

## Plan Phases

### Phase 1 — 前端数据源统一（P0）
目标：满足“前端业务数据必须来自后端接口/渲染”。
- 基于 router 生成“生产页面 -> 数据来源(API/mock/static)”清单。
- 替换生产路径中的硬编码业务数据（示例：Portal 用户侧业务列表）。
- 处理 Superadmin demo 数据风险：默认禁入生产菜单/路由（必要时移出生产构建入口）。

### Phase 2 — 用户/租户隔离强化（P0）
目标：把“依赖人工自觉加条件”改为“可验证、可回归”。
- 梳理关键服务（order/content/coupon/tenant/wallet）过滤点。
- 对高风险路径补足 query-time tenant/user 约束。
- 增加跨租户越权负向测试并形成隔离矩阵证据。

### Phase 3 — 审计能力补齐（超管 + 租户）（P0）
目标：满足 #3/#4 审计要求。
- 超管侧：盘点并补齐关键操作 `Audit.Log` 覆盖。
- 租户侧：新增租户审计查询 API + 页面，附角色权限控制。
- 完成 route 生成与 Swagger 生成，确保接口可见且可调试。

### Phase 4 — 验证、证据与发布门禁（P0）
目标：形成可审签的上线证据。
- 执行 backend 全量测试与双前端 build/lint。
- 执行前端页面流验收并按模板记录证据。
- 输出发布门禁检查单（Pass/Fail + 证据路径）。
- 阶段通过后归档 `docs/plan.md` 到 `docs/plans/<date>.md`，并清空 `docs/plan.md`。

## Tasks

- [ ] T1 建立“生产部署能力差距台账”（含 router->页面->数据来源盘点）。
- [ ] T2 替换 Portal 生产路径中的硬编码业务数据来源。
- [ ] T3 下线或隔离 Superadmin demo 数据路由（防止进入生产流量路径）。
- [ ] T4 建立后端隔离审计清单（order/content/coupon/tenant/wallet）。
- [ ] T5 对高风险服务补充 tenant/user query-time 约束（最小改动）。
- [ ] T6 增加跨租户越权测试用例并纳入回归。
- [ ] T7 盘点超管关键操作审计埋点，补齐缺失 `Audit.Log` 调用。
- [ ] T8 设计并实现租户侧审计日志查询 API（租户范围、权限受控）。
- [ ] T9 执行 `cd backend && atomctl gen route` 并校验新增路由注册。
- [ ] T10 实现租户管理侧审计页面（筛选、分页、时间范围、动作类型）。
- [ ] T11 补充审计相关 API 注释与字段定义（operator/action/target/detail）。
- [ ] T12 执行 `cd backend && atomctl swag init` 并校验 Swagger 产物更新。
- [ ] T13 执行 backend 全量测试 `go test ./...`。
- [ ] T14 执行 portal/superadmin build + lint。
- [ ] T15 创建并冻结验收证据模板：`docs/release-evidence/<date>.md`。
- [ ] T16 执行前端页面流验收并填充证据模板（含截图/日志/结论）。
- [ ] T17 汇总发布门禁清单并形成 Go/No-Go 结论。
- [ ] T18 阶段完成后归档 `docs/plan.md` 到 `docs/plans/<date>.md`，并清空 `docs/plan.md`。

## Dependencies

- T1 -> T2/T3/T4/T7（先冻结缺口，再实施）
- T4 -> T5 -> T6 -> T13（隔离设计先行，测试跟进）
- T7 -> T8 -> T9 -> T10（先有后端能力与路由，再接前端）
- T8 -> T11 -> T12（接口定义后再生成 Swagger）
- T2/T3/T10 -> T14/T16（前端改造完成后再构建与页面验收）
- T15 -> T16 -> T17（证据模板先行）
- T9/T12/T13/T14/T16 -> T17（发布结论依赖完整证据链）
- T17(Go) -> T18（仅 Go 才归档；No-Go 不归档）

## Owner Roles (RACI-lite)

> 说明：每个任务必须有唯一 DRI（Directly Responsible Individual）与一个 Approver。

| Role | 主要职责 |
|------|----------|
| Tech Lead (Overall) | 统筹范围、顺序、风险与里程碑审签 |
| Backend Lead | 隔离强化、审计后端能力、生成流程与后端验证 |
| Frontend Portal Owner | Portal/租户侧页面改造与联调 |
| Frontend Superadmin Owner | Superadmin 生产路径治理与联调 |
| QA Owner | 回归用例、页面流验收、证据完整性审查 |
| Release Owner | 发布门禁、Go/No-Go 会议与归档执行 |

## Task Accountability (DRI / Approver)

| Task | DRI | Approver |
|------|-----|----------|
| T1 | Tech Lead | QA Owner |
| T2 | Frontend Portal Owner | Tech Lead |
| T3 | Frontend Superadmin Owner | Tech Lead |
| T4 | Backend Lead | Tech Lead |
| T5 | Backend Lead | QA Owner |
| T6 | QA Owner | Backend Lead |
| T7 | Backend Lead | Tech Lead |
| T8 | Backend Lead | Tech Lead |
| T9 | Backend Lead | Tech Lead |
| T10 | Frontend Portal Owner | QA Owner |
| T11 | Backend Lead | Tech Lead |
| T12 | Backend Lead | Tech Lead |
| T13 | Backend Lead | QA Owner |
| T14 | Frontend Superadmin Owner | QA Owner |
| T15 | QA Owner | Release Owner |
| T16 | QA Owner | Release Owner |
| T17 | Release Owner | Tech Lead |
| T18 | Release Owner | Tech Lead |

## Execution Schedule (10 Working Days)

> 计划周期：10个工作日。发生阻塞时顺延，不压缩验证与证据阶段。

| Day | Focus | 任务 | Primary Owner | 协作方 | 当日退出标准 |
|-----|-------|------|---------------|--------|--------------|
| D1 | 基线与证据机制冻结 | T1, T4(启动), T15 | Tech Lead, Backend Lead, QA Owner | Release Owner | 差距台账冻结；隔离清单初版；证据模板落盘 |
| D2 | 前端数据源整改（Portal） | T2(Portal核心页面) | Frontend Portal Owner | Backend Lead | 生产路径硬编码业务数据改为 API 拉取 |
| D3 | 前端生产路径治理（Superadmin） | T2(收尾), T3 | Frontend Superadmin Owner | Tech Lead | demo 路由完成隔离且不进入生产入口 |
| D4 | 隔离约束补强（一） | T5(order/content) | Backend Lead | QA Owner | 关键查询改为 query-time 约束，完成自检 |
| D5 | 隔离约束补强（二）+ 负向测试 | T5(coupon/tenant/wallet), T6 | Backend Lead, QA Owner | Tech Lead | 跨租户负向测试覆盖核心场景并通过 |
| D6 | 审计覆盖补漏 + 租户审计API开发 | T7, T8(启动) | Backend Lead | Frontend Portal Owner | 审计补漏清单清零；租户审计 API 代码完成 |
| D7 | 路由生成与后端可调用性 | T9, T8(联调收口) | Backend Lead | Tech Lead | `atomctl gen route` 完成且新增路由注册可见 |
| D8 | 租户审计前端与接口文档定义 | T10, T11 | Frontend Portal Owner | Backend Lead, QA Owner | 租户审计页面接通后端；注释字段定义完成 |
| D9 | 文档生成 + 构建测试 | T12, T13, T14 | Backend Lead, Frontend Superadmin Owner | QA Owner | Swagger 产物更新；go test 与双前端 build/lint 可复现 |
| D10 | 页面流验收与发布评审 | T16, T17, T18(条件触发) | QA Owner, Release Owner | 全员 | 页面流证据齐全；Go/No-Go 结论明确；Go 时完成归档与清空 |

## Milestones

- **M1 (D3 End): 前端生产数据源统一完成**  
  Exit Criteria: 生产路径无硬编码业务记录数据；demo 路由已隔离。

- **M2 (D5 End): 多租户隔离强化完成**  
  Exit Criteria: 高风险服务完成 query-time 约束；跨租户负向测试通过。

- **M3 (D9 End): 双侧审计能力与生成链路完成**  
  Exit Criteria: 超管审计补漏完成；租户审计 API + 页面可用；route/swagger 生成成功。

- **M4 (D10 End): 发布门禁与归档完成**  
  Exit Criteria: 测试、构建、页面流证据与门禁结论完整；Go 时归档并清空活动 plan。

## Acceptance Criteria

1. 前端生产路径不再存在硬编码业务数据列表（允许 UI 常量，不允许业务记录数据常量）。
2. 用户/租户隔离具备可回归证据：跨租户访问负向测试通过，关键接口均有 tenant/user 约束。
3. 超级管理员后台审计可用：可按租户、操作者、动作、时间筛查审计日志。
4. 租户管理侧审计可用：租户管理员可查询本租户审计日志，且无法查看其他租户数据。
5. 新增/调整审计 API 后，必须完成 `atomctl gen route` 且路由注册可验证。
6. 新增/调整审计 API 后，必须完成 `atomctl swag init` 且 swagger 产物与接口一致。
7. 若涉及前端改动，必须完成页面流验收；同时完成 backend `go test ./...`。
8. 发布门禁清单全部通过后方可标记“具备生产部署能力”；且需执行归档到 `docs/plans/<date>.md` 并清空 `docs/plan.md`。

## Risks

- **风险1：前端替换数据源引发页面空态/交互回归**
  - 缓解：逐页替换 + 空态兜底 + 页面流测试。

- **风险2：隔离强化引发历史“宽查询”行为变化**
  - 缓解：先补负向测试，再做最小修复，避免大规模重构。

- **风险3：审计日志增长导致查询性能下降**
  - 缓解：按测量协议验证 p95，必要时补复合索引并复测。

- **风险4：租户侧审计权限定义不清**
  - 缓解：实现前冻结角色矩阵（owner/admin/member），验收时执行越权测试。

- **风险5：证据缺失导致 Go/No-Go 争议**
  - 缓解：统一证据模板、固定路径、固定 DRI/Approver 审核链。

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| N/A | N/A | N/A |