# 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

无。