crawler-plugin/docs/specs/11-flask-removal-cutover.md

11 Flask 管理能力移除与入口切换

状态（task-283 已执行阶段 5/6）：Flask 管理蓝图（admin_api/auth/main）、web_source/、backend/static/admin.*、Java classpath 旧 admin.html/login.html 副本均已删除；backend/app.py 现仅保留版本公开 API 蓝图。Java 侧 /、/admin、/admin.html → /admin-vue/，/login、/login.html → /admin-vue/login（SPA 登录页）。Flask 进程（15124）仍保留 /api/version*，桌面客户端 app_client 的更新检查仍以它为 base_url，切换至 Java 前勿下线。工作区 scripts/deploy.py 的 pyfiles 动作已同步清理主机上的旧后台文件。

模块职责

定义从 Flask 管理后台到 Java + Vue 的最终切换、删除清单、回滚边界和依赖清理。版本公开接口不属于删除范围，因为已经迁移到 Java 后由客户端继续使用。

依赖关系

前置：

• 所有后台页面完成 Vue 迁移。
• Java /api/admin/* API 回归通过。
• Java /api/version、/api/version/latest 回归通过。
• Nginx /admin-vue/ 正常服务。
• Flyway 菜单 route_path 迁移完成。

被删除的 Flask 文件/符号：

• backend/blueprints/main.py:admin_page。
• backend/blueprints/admin_api.py 的管理 API 路由和权限代理辅助函数。
• backend/web_source/admin.html。
• backend/static/admin.js。
• backend/static/admin-interactions.js。
• Java classpath 中同步旧后台的 admin.html、旧管理脚本副本。

保留并迁移后的能力：

• Flask version.py:api_version → Java PublicVersionController.currentVersion。
• Flask version.py:api_version_latest → Java PublicVersionController.latestVersion。

核心接口：原实现 → 目标实现

迁移项	原实现	目标实现
/admin	Flask/Java 旧 admin.html	Java/Nginx → /admin-vue/
管理页面	Jinja + DOM	Nginx + Vue
管理 API	Flask admin_api 或 Java 兼容 API	Java 唯一实现
公开版本检查	Flask version.py	Java公开版本控制器
管理权限	Flask 代理/本地判断 + Java	Java PermissionMenuService
静态资源	Flask/Java 双份	Nginx 单份 dist

内部结构

切换阶段：

阶段 1：Java API + Vue /admin-vue 并行开发
阶段 2：Nginx 先发布 /admin-vue，不立即删除旧源文件
阶段 3：/admin → /admin-vue/，开始真实用户回归
阶段 4：确认版本接口和全部后台页面稳定
阶段 5：删除 Flask 管理蓝图和旧后台资源
阶段 6：清理旧权限响应、旧复制脚本、旧文档和部署配置

类型映射\n\nFlask admin_page 映射为 Java /admin redirect；Flask admin_api 管理路由映射为 Java /api/admin/*；Flask version.py 映射为 Java /api/version*；旧 admin.html 映射为 Nginx /admin-vue/index.html。\n\n## 删除/保留清单

必须删除

• Flask 管理页面入口和管理 API。
• 旧 admin HTML/JS/CSS 中只服务后台的代码。
• Java static 中旧 admin 页面副本。
• admin.js 依赖的旧 DOM ID 和旧 toast/confirm 容器。
• 旧菜单扁平响应适配分支。

必须保留

• Java /api/admin/* 业务 API。
• Java 登录态和后台鉴权。
• web_config 版本表。
• Java /api/version、/api/version/latest。
• 客户端所需公开下载 URL。

迁移/实现注意事项

1. 删除 Flask 前必须确认生产 Nginx/API 流量不再指向 Python 管理接口。
2. 删除旧页面前先保存一次前后端 API/权限快照，用于回归对比。
3. 不因为后台删除而删除 web_config 或版本上传逻辑。
4. Flask 进程如果还承担其他非管理插件能力，必须按部署文档单独确认；本 spec 只要求移除 Flask 的后台管理职责和版本查询职责，不能误删其他客户端插件 API。
5. 若 Flask 进程承载不可迁移的其他 API，最终部署可以分离进程，但后台请求不得再依赖它；是否完全停止 Python 进程需以其他服务清单为前置验收。
6. 切换失败时回滚的是 Nginx current 目录和 Java /admin 重定向，不回滚数据库已执行的 Flyway 版本；数据库迁移必须设计前向兼容。