kra-oa/docs/ADMIN_BACKEND_MIGRATION.md

GVA 管理后端迁移清单

基线与范围

• 参考基线：工作区 gva/server，Git 02f37833。
• 目标：保留 GVA Vue 管理端使用的 HTTP 路径、方法、请求字段、统一响应结构和核心业务语义，同时按 Kratos 的 service -> biz -> data 分层落地。
• 明确排除：代码生成、代码生成历史、插件打包/安装、AI/LLM、MCP、Skills，以及测试文件。
• 公告与邮件位于 gva/server/plugin；两者均已按 Kratos 分层迁移，不保留 GVA 的插件式全局变量结构。
• 推荐范围包含 177 个 GVA HTTP 路由，目标端全部覆盖；另增加 GET /health，目标实际注册路由总数为 178。

模块契约矩阵

模块	路由数	迁移内容
初始化、登录、用户、个人中心	17	初始化、验证码、登录、JWT、用户 CRUD、多角色、个人资料、密码、菜单、注销
角色	9	角色树、创建、复制、更新、删除、用户关联、数据范围
菜单	10	菜单树、CRUD、角色菜单、菜单角色、菜单按钮
API 与 Casbin	19	API CRUD/同步/忽略、角色 API、Casbin 策略、按钮权限
组织	16	部门树、岗位、用户关联、自定义数据范围
字典与参数	24	字典/字典项 CRUD、树、路径、导入导出、系统参数
安全、系统配置、API Token	9	安全策略热更新、限流、锁定、密码策略、配置、服务器信息、Token 签发/作废
Excel 导入导出	12	模板 CRUD、SQL 预览、一次性下载令牌、Excel 导入导出
版本管理	7	菜单/API/字典版本打包、记录、下载和导入
审计与日志	20	操作、登录、数据访问、错误日志以及安全的文件日志查看
定时任务与 SSE	9	Cron CRUD/启停/触发、HTTP/本地执行器、执行日志、失败告警 SSE
媒体	15	文件库、附件分类、本地存储枚举、普通上传、秒传与分片续传
公告	8	公告 CRUD、批量删除、分页、发布者数据源和公开接口
邮件	2	SMTP 测试、主动发送，以及失败请求邮件告警中间件

分层映射

Kratos 层	职责
internal/server	Gin 路由、鉴权/审计中间件、HTTP 请求绑定与响应写出、Kratos transport 生命周期
internal/service	HTTP DTO 与领域数据的适配、用例编排
internal/biz	用户、权限、设置、审计、任务、媒体等领域对象、仓储接口与业务规则
internal/data	GORM PO、MySQL 仓储、Redis/内存缓存、本地文件存储
cmd/kratos-admin	Wire 依赖注入与 Kratos 应用组装

兼容性说明

• HTTP 响应保持 {code, data, msg}，成功码为 0。
• JWT 继续接受 x-token Header 和同名 Cookie；角色切换返回 new-token、new-expires-at。
• 初始化会自动迁移表、写入管理员与菜单，并从 Gin 实际路由同步 API 表。
• 超级管理员角色 888 保留全权限旁路；其他角色由 Casbin 策略控制。
• 代码中的 *-gva 字符串仅是原 Vue 图标库的图标标识，为页面显示兼容而保留；Go 文件、类型、变量和方法均使用实际职责命名。
• 当前首先实现 MySQL、Redis（不可用时退化为进程缓存）和本地文件存储；云 OSS 驱动没有混入领域层。
• SMTP 参数位于 admin.email；未配置服务器、发件人或密钥时错误告警保持关闭，邮件接口会返回明确的配置错误。

验证命令

go generate ./cmd/kratos-admin
go test ./...
go vet ./...
go build ./...
git diff --check