# Web-Admin 超级管理员与菜单/区域权限 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 在保持前端静态菜单模式前提下，实现 `super_admin` + 运营管理人员(`admin`) 的菜单 code 授权和多区域数据权限，并完成迁移与联调。

**Architecture:** 后端新增“用户-区域范围”和“用户-菜单 code”关系表；登录后前端拉取授权 code 过滤本地静态菜单；接口侧仅保留角色与区域范围守卫。

**Tech Stack:** FastAPI + SQLAlchemy + Vue3 + Pinia + Element Plus + MySQL

---

### Task 1: 数据库迁移脚本落地

**Files:**
- Create: `backend/scripts/migration_20260429_user_scope_menu_code.sql`
- Modify: `docs/superpowers/specs/2026-04-29-web-admin-super-admin-menu-region-design.md`
- Test: `docs/sql/sanqiang.sql` (对照结构)

- [ ] **Step 1: 编写新表 DDL**
- [ ] **Step 2: 编写历史表 DDL**
- [ ] **Step 3: 添加必要索引与约束**
- [ ] **Step 4: 编写角色迁移 SQL (`admin -> super_admin`)**
- [ ] **Step 5: 编写测试运营管理员与授权示例 SQL**
- [ ] **Step 6: 在测试库执行并验证建表/插数成功**

Run: `mysql -u<user> -p<pass> sanqiang < backend/scripts/migration_20260429_user_scope_menu_code.sql`  
Expected: DDL/DML 全部执行成功，无主键或唯一冲突。

---

### Task 2: 后端模型与 CRUD 支撑

**Files:**
- Modify: `backend/app/models/models.py`
- Create: `backend/app/crud/user_region_scope.py`
- Create: `backend/app/crud/user_menu_scope.py`
- Modify: `backend/app/crud/__init__.py`
- Test: `backend/app/crud/user.py`

- [ ] **Step 1: 在模型中新增 `SysUserRegionScope`、`SysUserRegionScopeHis`**
- [ ] **Step 2: 在模型中新增 `SysUserMenuScope`、`SysUserMenuScopeHis`**
- [ ] **Step 3: 新建 CRUD，支持按 user_id 查询/全量覆盖更新**
- [ ] **Step 4: CRUD 更新逻辑增加历史表写入**
- [ ] **Step 5: 补齐角色枚举 `super_admin` 相关常量**

Run: `python -m py_compile backend/app/models/models.py backend/app/crud/user_region_scope.py backend/app/crud/user_menu_scope.py`  
Expected: 无语法错误。

---

### Task 3: 认证与授权基础信息扩展

**Files:**
- Modify: `backend/app/core/auth.py`
- Modify: `backend/app/api/public.py`
- Create: `backend/app/core/menu_permission.py`
- Test: `backend/app/api/public.py`

- [ ] **Step 1: 扩展 current-user 返回 `isSuperAdmin` 与 `regionIds`**
- [ ] **Step 2: 新增 `GET /web/auth/menu-codes` 接口**
- [ ] **Step 3: 新增读取用户菜单 code 列表逻辑**
- [ ] **Step 4: 超级管理员返回全量标识**

Run: `pytest -q backend/tests`  
Expected: 认证相关测试通过（若缺失测试，至少手工验证接口返回结构）。

---

### Task 4: 菜单 code 查询与菜单管理接口

**Files:**
- Modify: `backend/app/api/admin.py`
- Modify: `backend/app/api/public.py`
- Modify: `backend/app/api/menu.py`
- Test: `backend/app/main.py`

- [ ] **Step 1: 完成 `GET /web/auth/menu-codes` 接口**
- [ ] **Step 2: 完成菜单授权 CRUD 接口（按 code）**
- [ ] **Step 3: 与 `super_admin` 全量菜单逻辑打通**
- [ ] **Step 4: 校验菜单 code 返回结构与前端静态路由一致**
- [ ] **Step 5: 保持接口侧不引入 menu-code 鉴权**

Run: `uvicorn backend.app.main:app --reload`  
Expected: 服务启动成功，菜单 code 接口返回正确。

---

### Task 5: 区域多选与区域范围守卫

**Files:**
- Modify: `backend/app/api/admin.py`
- Modify: `backend/app/crud/user.py`
- Modify: `backend/app/schemas/user.py`
- Test: `backend/app/api/admin.py`

- [ ] **Step 1: 用户新增/编辑接口支持 `regionIds` 入参**
- [ ] **Step 2: 新增 `admin` 可见区域集合查询逻辑**
- [ ] **Step 3: 区域相关查询统一应用 `allowed_region_ids`**
- [ ] **Step 4: 请求传入越权 `regionId` 时返回 403**
- [ ] **Step 5: 保持 `super_admin` 不受区域限制**

Run: `pytest -q backend/tests`  
Expected: 用户与区域权限相关用例通过；越权返回 403。

---

### Task 6: 用户管理页面改造（前端）

**Files:**
- Modify: `web-admin/src/views/system/user/index.vue`
- Modify: `web-admin/src/api/admin.ts`
- Modify: `web-admin/src/api/system-manage.ts`
- Create: `web-admin/src/views/system/user/modules/user-menu-scope-dialog.vue`
- Test: `web-admin/src/views/system/user/index.vue`

- [ ] **Step 1: 新增双层 Tab（运营管理人员/区域用户 + 区域 Tab）**
- [ ] **Step 2: 新增/编辑 `admin` 弹窗区域改为多选**
- [ ] **Step 3: 新增“菜单权限管理”操作与弹窗**
- [ ] **Step 4: 对接菜单 code 授权接口**
- [ ] **Step 5: 对接 `regionIds` 保存接口**

Run: `pnpm --dir web-admin dev`  
Expected: 页面可正常操作，新增/编辑/授权流程完整。

---

### Task 7: 左侧菜单 code 过滤（前端静态菜单模式）

**Files:**
- Modify: `web-admin/src/store/modules/menu.ts`
- Modify: `web-admin/src/router/core/MenuProcessor.ts`
- Modify: `web-admin/src/router/guards/beforeEach.ts`
- Modify: `web-admin/src/api/auth.ts`
- Test: `web-admin/src/router/modules/sqxp.ts`

- [ ] **Step 1: 登录后调用 `GET /web/auth/menu-codes`**
- [ ] **Step 2: 在本地静态菜单树按 code 过滤**
- [ ] **Step 3: 实现“仅补齐顶级父菜单”规则**
- [ ] **Step 4: 无菜单权限展示空状态页面**
- [ ] **Step 5: `super_admin` 直接全菜单**

Run: `pnpm --dir web-admin build`  
Expected: 构建通过，路由注册无异常。

---

### Task 8: 迁移执行与回归验证

**Files:**
- Modify: `docs/superpowers/specs/2026-04-29-web-admin-super-admin-menu-region-design.md`
- Modify: `docs/后端接口全覆盖测试与数据库校验实施跟踪.md`
- Modify: `docs/P0-实际验证记录.md`
- Test: `backend/scripts/migration_20260429_user_scope_menu_code.sql`

- [ ] **Step 1: 按割接顺序执行上线前检查**
- [ ] **Step 2: 执行迁移与测试账号准备**
- [ ] **Step 3: 执行四类冒烟（超管/运营/菜单/区域）**
- [ ] **Step 4: 记录接口与数据库前后快照**
- [ ] **Step 5: 更新文档留痕**

Run: `git status`  
Expected: 变更包含代码、SQL、文档，且验证记录完整。

---

## Definition of Done

- 超级管理员：全菜单、全区域、全部数据可见。
- 运营管理人员：仅授权菜单 code 可见，仅授权区域数据可见。
- 菜单权限仅作用于前端可见性，不做接口级 menu-code 鉴权。
- 用户管理页支持运营多区域与菜单授权。
- 迁移 SQL、测试数据 SQL、验证记录文档齐全。