# 00 总览：后台管理系统 Vue 化与 Flask 移除

## 1. 文档目的

本目录是后台管理系统 Vue 化、Java 收敛和 Flask 管理能力移除的唯一设计输入，供后续 step-2 按功能点拆分任务。

本次范围不是客户端前端重构。客户端工程 `frontend-vue/` 及其 `new_web_source/` 不属于本项目的后台前端产物。

## 2. 已确认决策

| 主题 | 决策 |
|---|---|
| 前端工程 | 独立 `admin-frontend-vue/` |
| UI | Vue 3 + TypeScript + Element Plus |
| 状态 | Pinia 只保存用户、菜单和全局应用状态；页面数据局部管理 |
| 路由 | Vue Router History；生产基准路径 `/admin-vue/` |
| 菜单 | Java 后端返回树形菜单；前端不写死菜单分组 |
| 权限粒度 | 仅菜单/页面级；不做按钮级权限 |
| 权限存储 | 继续复用 `columns` 和 `user_column_permission` |
| 权限 key 与 URL | 分离；`column_key` 是稳定权限标识，`route_path` 是 Vue 页面路径 |
| API | 保持 `/api/admin/*`；不新建 v2 API |
| 认证 | 复用现有同源 Cookie/Session；不引入 JWT |
| 后端 | Java 成为后台管理唯一后端；Flask 管理能力完全移除 |
| 版本接口 | Java 提供 `/api/version`、`/api/version/latest`，路径和字段不变 |
| 静态资源 | Nginx 独立目录托管，不打进 Java JAR |
| 入口 | `/admin` 重定向 `/admin-vue/` |
| 旧链接 | 不兼容旧 `#tab=xxx` 和旧后台路径 |
| 菜单迁移 | 通过 Flyway 正式迁移 |
| 首批 | 后台壳层、用户、菜单、数据权限分组 |
| 视觉 | 深色侧边栏 + 浅色内容区 |

## 3. 当前实现基线

### 3.1 旧后台前端

- 页面：`backend/web_source/admin.html`，包含 17 个面板、26 个弹窗和全部页面样式。
- 业务脚本：`backend/static/admin.js`，将请求、状态、DOM 渲染、权限和轮询集中在单个 IIFE。
- 横切交互：`backend/static/admin-interactions.js`，负责 loading、toast、confirm、键盘和按钮增强。
- Java 静态副本：`backend-java/src/main/resources/static/admin.html` 及 `static/admin.js`。

### 3.2 现有后台 API

- Flask 管理蓝图：`backend/blueprints/admin_api.py`。
- Java 管理控制器：`backend-java/src/main/java/com/nanri/aiimage/modules/admin/controller/AdminUserController.java`、`AdminConsoleController.java`。
- Java 权限控制器：`backend-java/src/main/java/com/nanri/aiimage/modules/permission/controller/PermissionMenuController.java`。
- 版本管理：`backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/controller/SoftwareVersionAdminController.java`。

### 3.3 已有权限数据模型

- `columns`：菜单、分组和页面节点。
- `user_column_permission`：用户到菜单节点的直接授权。
- `PermissionMenuService`：负责有效权限展开、父子菜单和授权边界。

## 4. 目标架构

```text
Browser
  │
  ├── /admin
  │       └── 302 → /admin-vue/
  │
  └── /admin-vue/*
          │
          ▼
      Nginx/OpenResty
          ├── /admin-vue/assets/* → 独立静态资源
          ├── /admin-vue/<route>  → History fallback 到 index.html
          └── /api/*             → Java
                                      │
                                      ├── Session/Auth
                                      ├── Admin APIs
                                      ├── Menu Tree API
                                      ├── Version Admin API
                                      └── Public Version API
```

```text
admin-frontend-vue/
  ├── src/layout/              # AdminLayout、侧边栏、顶栏
  ├── src/router/              # History 路由和菜单守卫
  ├── src/stores/              # Pinia 用户/菜单状态
  ├── src/api/                 # 后台 API 适配
  ├── src/pages/account/       # 首批账号权限模块
  ├── src/pages/asin/          # ASIN 数据中心
  ├── src/pages/shop/          # 店铺中心
  ├── src/pages/tasks/         # 任务和重复分析
  ├── src/pages/records/       # 历史、版本
  └── dist/                    # Nginx 发布目录
```

## 5. 精确依赖图：现状符号到目标符号

| 当前文件与符号 | 当前依赖 | 目标替代/消费者 |
|---|---|---|
| `backend/blueprints/main.py:admin_page` | `blueprints.admin_api._load_current_backend_menu_items`、`utils.render.render_html`、`web_source/admin.html` | 删除 Flask 页面职责；`AdminConsoleController.adminPage` 重定向 `/admin-vue/` |
| `backend/blueprints/main.py:serve_static` | `backend/static/*` | 删除后台静态托管职责；Nginx 托管 `admin-frontend-vue/dist` |
| `backend/blueprints/admin_api.py:get_admin_current_user` | Flask Session、当前用户查询 | `AdminConsoleController.currentUser` |
| `backend/blueprints/admin_api.py:get_admin_current_user_menus` | `_load_current_backend_menu_items`、Java 权限代理 | `AdminConsoleController.currentUserMenus` + `PermissionMenuService.getUserColumnPermissions` + 树构造器 |
| `backend/blueprints/admin_api.py:list_users` | Flask DB/Java 代理、`_ensure_backend_menu_access` | `AdminUserController.listUsers` + `AdminUserService.listUsers` |
| `backend/blueprints/admin_api.py:create_user/update_user/delete_user` | Flask 管理用户逻辑 | `AdminUserController.createUser/updateUser/deleteUser` |
| `backend/blueprints/admin_api.py` 的菜单 CRUD 路由 | Flask 权限代理 | `PermissionMenuController.listMenus/createMenu/updateMenu/deleteMenu/reorderColumns` |
| `backend/blueprints/version.py:api_version` | `APP_VERSION`、`APP_UPDATE_URL` | `PublicVersionController.currentVersion` |
| `backend/blueprints/version.py:api_version_latest` | `utils.db.get_db`、`web_config` | `PublicVersionController.latestVersion` + `SoftwareVersionService.latestSoftwareVersion` |
| `backend/web_source/admin.html` 的 `panel-users` | `admin.js:loadUsers`、DOM ID 约定 | `pages/account/UsersPage.vue` |
| `backend/web_source/admin.html` 的 `panel-columns` | `admin.js:loadColumns`、拖拽排序 | `pages/account/MenusPage.vue` + 菜单 API |
| `backend/web_source/admin.html` 的 `panel-group-manage` | `admin.js:loadShopManageGroups`、分组弹窗 | `pages/account/GroupsPage.vue` |
| `backend/static/admin.js:loadAdminCurrentUser` | `/api/admin/current-user` | `api/session.ts:fetchCurrentUser` + `stores/admin-session.ts:initialize` |
| `backend/static/admin.js:loadAdminMenus` | `/api/admin/current-user/menus`、`renderAdminTabs` | `api/session.ts:fetchAdminMenuTree` + `AdminLayout.vue` |
| `backend/static/admin.js:activateAdminTab` | `hideAllAdminPanels`、`runTabLoader` | `router/index.ts` + 路由级异步页面组件 |
| `backend/static/admin-interactions.js:showToast` | `adminToastRegion` | Element Plus `ElMessage` |
| `backend/static/admin-interactions.js:openConfirm` | `adminConfirmModal` | Element Plus `ElMessageBox` |
| `backend-java/.../AdminConsoleController.currentUser` | `AdminAuthSupport.requireAdminOrInternal` | 保留，作为 Vue Session 初始化接口 |
| `backend-java/.../AdminConsoleController.currentUserMenus` | `PermissionMenuService.getUserColumnPermissions` | 保留调用，增加树形组装；输出 `key/name/route/children` |
| `backend-java/.../PermissionMenuService.getUserColumnPermissions` | `columns`、`user_column_permission`、父子展开 | 保留为菜单权限唯一来源 |
| `backend-java/.../AdminUserController.listUsers` | `AdminUserService.listUsers` | Vue `UsersPage` API 适配层 |
| `backend-java/.../PermissionMenuController.listMenus` | `PermissionMenuService.list` | Vue `MenusPage` API 适配层 |
| `backend-java/.../SoftwareVersionAdminController` | `SoftwareVersionService`、`web_config` | Vue Records/Version 页面 |
| `frontend-vue/*` | 客户端 Vite 多页面工程 | 不依赖、不修改、不作为后台工程入口 |

## 6. 目标菜单数据契约

接口：`GET /api/admin/current-user/menus`。

目标响应的 `items` 是树形数组。页面节点至少包含：

| 字段 | 来源 | 语义 |
|---|---|---|
| `key` | `columns.column_key` | 稳定菜单权限标识 |
| `name` | `columns.name` | 展示名称 |
| `route` | `columns.route_path` | Vue Router 页面路径，不包含 `/admin-vue` 基准前缀 |
| `children` | `columns.parent_id` | 子菜单；叶子页面可省略或为空数组 |
| `sort` | `columns.sort_order` | 仅用于后端排序，是否输出由最终 DTO 决定 |

不输出按钮级 `actions`，不新增操作权限表。

## 7. 实现顺序

1. 固化 Java 版本接口契约和菜单树 DTO。
2. 完成 Flyway 后台 route_path 迁移。
3. 完成后台前端壳层、Session、菜单守卫。
4. 完成账号与权限首批页面。
5. 完成版本/历史和低风险数据页面。
6. 完成 ASIN、店铺、任务、重复检查页面。
7. 做 Java API 对照、权限回归、客户端版本更新回归。
8. Nginx 发布 `/admin-vue/`，将 `/admin` 重定向到 Vue。
9. 删除 Flask 管理蓝图、旧 admin 模板和旧管理脚本。
10. 删除旧菜单响应、旧静态资源和迁移期间兼容代码。

## 8. 迁移边界

本次必须保留：

- `/api/version`。
- `/api/version/latest`。
- `/api/admin/*` 的业务 API 路径和业务响应语义。
- Cookie/Session 登录态。
- `columns`、`user_column_permission` 的数据库模型。

本次最终删除：

- Flask 管理页面路由。
- Flask 管理 API 蓝图。
- Flask 管理后台静态资源。
- 旧 `admin.html`、`admin.js`、`admin-interactions.js`。
- 客户端请求不到的 Flask 版本蓝图（版本能力已迁移 Java）。

## 10. 模块职责

本总览模块负责定义后台前端、Java API、权限存储、公开版本接口、静态部署和 Flask 删除之间的边界；不直接实现业务页面。

## 11. 依赖关系

所有模块依赖 `00-overview.md` 的技术选型和发布边界；页面模块依赖壳层与 Session 菜单模块；Java 菜单、版本和部署模块是最终切换的后端前置条件。

## 12. 核心接口

核心外部接口包括 `/admin`、`/admin-vue/`、`/api/admin/current-user`、`/api/admin/current-user/menus`、`/api/version`、`/api/version/latest`；各接口的原实现到目标实现映射见第 5 节和对应独立 spec。

## 13. 内部结构

总体系由独立后台前端、Java 管理 API、权限数据库、公开版本服务和 Nginx 发布层组成，结构图见第 4 节。

## 14. 类型映射

总体系的关键类型映射为：`column_key → menu key`、`route_path → Vue route`、`PermissionMenuItemVo[] → AdminMenuNode[]`、`web_config version/file_url → PublicVersionResponse`。

## 15. 迁移/实现注意事项

本总览约束所有子 spec 不得引入客户端前端依赖、按钮级权限、JWT、旧 hash 兼容或 Flask 管理长期兼容分支；未在本总览批准的跨模块变更必须先更新决策和对应 spec。
## 9. 主要风险与验收标准

### P0：客户端更新接口中断

证据：Flask `version.py` 当前提供 `/api/version/latest`，客户端已有固定调用。

验收：Java 接口在 Flask 停止后仍返回同路径、同字段、同空数据语义；至少完成真实 HTTP 回归。

### P0：菜单权限树错误导致后台不可用或越权展示

证据：当前权限展开依赖 `PermissionMenuService` 和 `user_column_permission`。

验收：超级管理员、管理员、普通账号、无菜单权限账号分别验证菜单树和路由守卫；页面 API 仍由后端鉴权。

### P1：History 刷新 404

证据：Vue Router 使用 History，生产由 Nginx fallback。

验收：直接访问并刷新 `/admin-vue/account/users`、`/admin-vue/account/menus`；不存在的静态资源必须返回 404 而不是 HTML。

### P1：路由迁移破坏权限关系

证据：现有后端大量使用旧 `column_key`，而新版 URL 需要重组。

验收：Flyway 只改变 `route_path`，旧 `column_key` 授权关系保持可解析；菜单 key 与 route 独立测试。

### P2：前端首屏包过大

证据：Element Plus 和后台所有模块会产生较大 bundle。

验收：页面组件按路由异步加载；首批页面不得把所有业务模块静态导入首屏。