158 lines
5.8 KiB
Markdown
158 lines
5.8 KiB
Markdown
# Implementation Plan: 多租户隔离优先 + 契约对齐
|
||
|
||
**Branch**: `N/A` | **Date**: 2026-01-23 | **Spec**: `docs/review_report.md`
|
||
**Input**: 生产评估与当前系统缺口确认
|
||
|
||
**Note**: 本计划遵循 `docs/templates/plan-template.md`。
|
||
|
||
## Summary
|
||
|
||
本阶段聚焦多租户强隔离、鉴权与权限完善、超管接口补齐，并同步前后端契约（路由前缀、参数命名、ID 类型）以形成最小可运行闭环。
|
||
|
||
## Technical Context
|
||
|
||
**Language/Version**: Go 1.22, Node 20+ (Vite), Vue 3
|
||
**Primary Dependencies**: Fiber, GORM-Gen, PrimeVue
|
||
**Storage**: PostgreSQL + Redis
|
||
**Testing**: `go test ./...`, `npm -C frontend/superadmin run build && npm -C frontend/superadmin run lint`
|
||
**Target Platform**: Linux server (Docker ready)
|
||
**Project Type**: Web application (backend + frontend)
|
||
**Performance Goals**: N/A (遵循现有服务要求)
|
||
**Constraints**: 多租户隔离、鉴权强制、生成文件不可手改
|
||
**Scale/Scope**: 现有核心业务与超管链路可跑通
|
||
|
||
## Constitution Check
|
||
|
||
- 必须遵循 `backend/llm.txt`：DTO 注释、路由规范、服务层约束、生成流程。
|
||
- `*.gen.go`、`backend/docs/docs.go` 禁止手改，必须通过 `atomctl` 生成。
|
||
- Controller 仅做绑定与调用，`tenantID/userID` 从 Controller 传入 Service。
|
||
|
||
## Project Structure
|
||
|
||
### Documentation (this feature)
|
||
|
||
```text
|
||
docs/
|
||
├── plan.md
|
||
└── templates/
|
||
└── plan-template.md
|
||
```
|
||
|
||
### Source Code (repository root)
|
||
|
||
```text
|
||
backend/
|
||
├── app/
|
||
│ ├── http/
|
||
│ ├── middlewares/
|
||
│ └── services/
|
||
├── database/
|
||
└── docs/
|
||
|
||
frontend/
|
||
├── portal/
|
||
└── superadmin/
|
||
```
|
||
|
||
**Structure Decision**: 采用现有 `backend/` + `frontend/` 双端结构。
|
||
|
||
## Plan Phases
|
||
|
||
### Phase 1: 影响面确认与现有能力盘点
|
||
- 明确 `/t/:tenantCode/v1` 作为统一路由前缀。
|
||
- 盘点必须补齐的超管接口与核心业务链路。
|
||
|
||
### Phase 2: 多租户强隔离（后端）
|
||
- 新增 tenant 解析中间件，注入 `tenantID` 到上下文。
|
||
- 所有业务路由切换为 `/t/:tenantCode/v1` 前缀。
|
||
- Service 层所有查询显式带 `tenantID` 条件。
|
||
|
||
### Phase 3: 鉴权与权限（后端）
|
||
- 拆分 `AuthOptional` / `AuthRequired`。
|
||
- 超管路由增加 `super_admin` 角色校验。
|
||
- 完成 `Super.Login` / `CheckToken`。
|
||
|
||
### Phase 4: 超管接口实现（后端）
|
||
- 补齐超管统计、列表、详情接口实现与 DTO 映射。
|
||
- 分页接口统一使用 `requests.Pager`。
|
||
|
||
### Phase 5: 契约对齐（前后端）
|
||
- API 前缀与路由基座统一。
|
||
- 统一参数命名与 ID 类型。
|
||
- 更新前端调用与路由配置。
|
||
|
||
### Phase 6: 生成与回归
|
||
- `atomctl gen route` / `atomctl gen provider` / `atomctl swag init`。
|
||
- 关键流程自测与最小回归。
|
||
|
||
## Tasks
|
||
|
||
**Format**: `[ID] [P?] [Story] Description`
|
||
|
||
### Phase 1: Foundational
|
||
- [ ] T001 [US0] 盘点现有路由与接口空实现（`backend/app/http/*`, `backend/app/services/*`）
|
||
- [ ] T002 [US0] 确认多租户前缀与 tenant 解析策略（`/t/:tenantCode/v1`）
|
||
|
||
### Phase 2: User Story 1 - 多租户强隔离 (P1)
|
||
**Goal**: 路由前缀与服务查询强制 tenant 隔离。
|
||
|
||
- [ ] T010 [US1] 新增 tenant 解析中间件（`backend/app/middlewares/tenant_resolver.go`）
|
||
- [ ] T011 [US1] 调整 HTTP 模块路由前缀与注解（`backend/app/http/**/routes.manual.go` + controller 注解）
|
||
- [ ] T012 [US1] Controller 中提取 `tenantID` 并显式传入 Service（`backend/app/http/**`）
|
||
- [ ] T013 [US1] Service 查询统一加 `tenantID` 条件（`backend/app/services/*`）
|
||
|
||
**Checkpoint**: 所有业务路由在 `/t/:tenantCode/v1` 下可访问，查询带租户隔离。
|
||
|
||
### Phase 3: User Story 2 - 鉴权与权限 (P1)
|
||
**Goal**: 受保护接口强制鉴权，超管角色校验。
|
||
|
||
- [ ] T020 [US2] 拆分并实现 `AuthOptional` / `AuthRequired`（`backend/app/middlewares/*`）
|
||
- [ ] T021 [US2] 超管路由注入角色校验中间件（`backend/app/http/super/v1/routes.manual.go`）
|
||
- [ ] T022 [US2] 完成 `Super.Login` / `CheckToken`（`backend/app/services/super.go`）
|
||
|
||
**Checkpoint**: 受保护接口必须授权；超管接口角色有效。
|
||
|
||
### Phase 4: User Story 3 - 超管接口补齐 (P1)
|
||
**Goal**: 超管核心页面可用，不再空实现。
|
||
|
||
- [ ] T030 [US3] 统计/列表/详情接口实现与 DTO 映射（`backend/app/services/super.go`）
|
||
- [ ] T031 [US3] 统一分页返回 `requests.Pager`（`backend/app/http/super/v1/*`）
|
||
|
||
**Checkpoint**: 超管关键接口返回有效数据。
|
||
|
||
### Phase 5: User Story 4 - 契约对齐 (P1)
|
||
**Goal**: 前后端路由、参数、ID 类型一致。
|
||
|
||
- [ ] T040 [US4] 统一后端路由前缀与 `@Router` 参数（`backend/app/http/**`）
|
||
- [ ] T041 [US4] 统一 API 参数命名（后端 `@Bind` 与前端调用匹配）
|
||
- [ ] T042 [US4] ID 类型调整与前端适配（`backend/app/http/**`, `frontend/portal/*`, `frontend/superadmin/*`）
|
||
|
||
**Checkpoint**: 前后端关键链路可跑通。
|
||
|
||
### Phase 6: Generation & Regression
|
||
- [ ] T050 [US5] 生成路由与 provider（`atomctl gen route`, `atomctl gen provider`）
|
||
- [ ] T051 [US5] 生成 swagger（`atomctl swag init`）
|
||
- [ ] T052 [US5] 回归测试（`go test ./...`，必要时前端 build/lint）
|
||
|
||
## Dependencies
|
||
|
||
- Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6。
|
||
- Phase 2 完成后，Phase 3/4 可并行推进，但路由前缀需先统一。
|
||
|
||
## Acceptance Criteria
|
||
|
||
- 多租户路由与解析生效，查询强制带 `tenantID`。
|
||
- 受保护接口必须鉴权通过；超管接口具备角色校验。
|
||
- 超管核心页面可调用对应接口获取数据。
|
||
- 前后端接口路径与参数命名一致。
|
||
- 生成文件已更新且未手改。
|
||
|
||
## Risks
|
||
|
||
- 路由前缀变更影响全部前端调用。
|
||
- ID 类型调整涉及 DTO/前端展示与校验，需要逐模块推进。
|
||
|
||
## Complexity Tracking
|
||
|
||
无。
|