rogee/quyun-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
05a0d07dbb3b52c49d2e158918786f51f8a4d206
quyun-v2/docs/plan.md
Rogee 3126ed5e64 chore: refine production-readiness execution plan 
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
2026-02-08 19:47:28 +08:00

14 KiB
Raw Blame History

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)

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

Source Code (repository root)

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
Reference in New Issue View Git Blame Copy Permalink