crawler-plugin/docs/specs/00-overview.md

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. 目标架构

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

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。

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