系统架构
双端服务
同一套服务端代码提供两个独立进程入口：
| 服务 | 命令 | 默认地址 | 路由前缀 |
|---|---|---|---|
| 管理端 API | go run . service admin | :8001 | /admin |
| 用户端 API | go run . service api | :8002 | /api |
两端共用数据库、Redis、上传与统一响应等基础能力，Controller、Logic、Param、Resp 与路由完全隔离，便于独立迁移与部署。
请求链路
管理端受保护接口的中间件链：
text
Auth → Permission → OperationLog → Controller → Logic- Auth：校验 JWT，并检查 Redis 中
login_id是否仍存在（主动过期）； - Permission：按
METHOD:/path校验接口权限，超级管理员直接放行； - OperationLog：记录方法、路由、参数、响应、IP、UA、耗时与操作人，敏感字段脱敏。
用户端接口的中间件链：
text
Platform → Auth → Controller → Logic- Platform：解析
X-Platform-Source（平台来源，1-4 必填）与X-App-Version（客户端版本号，透传不校验）请求头，写入上下文； - Auth：仅接受会员（
client=api）令牌，管理端令牌与会员令牌不能互调。
分层职责
| 层 | 目录 | 职责 | 禁止 |
|---|---|---|---|
| 路由 | router/ | 注册路由与中间件链，按端分文件 | 写业务逻辑 |
| 控制器 | internal/<端>/controller/ | 绑定参数 → 调 logic → 响应 | 写 SQL、写业务规则 |
| 业务 | internal/<端>/logic/ | 业务规则、事务、缓存维护 | 直接写 HTTP 响应 |
| 参数 | internal/<端>/param/ | 请求结构体（按功能拆分文件） | 与 resp 混写 |
| 响应 | internal/<端>/resp/ | 响应结构体（按功能拆分文件） | 直接返回 Model |
| 模型 | internal/common/model/ | GORM 模型（sys_* 表） | 定义关联对象 |
| 中间件 | common/middleware、admin/middleware | 横切逻辑 | 业务分支 |
| 工具 | pkg/ | 无业务归属的通用能力（response / pagination / password / mask / sms / sn / oss…） | 依赖 internal |
归属判断顺序：两端共用 → internal/common/<功能>；仅一端使用 → internal/<端>/<功能>；无业务语义 → pkg/<功能>。
目录结构
text
go_backend_frame/
├── server_api/ # 后端
│ ├── cmd/ # Cobra 子命令：service admin / api、version、plugin
│ ├── config/ # 配置结构与加载（version 必填）
│ ├── router/ # admin.go（管理端）、api.go（用户端）
│ ├── internal/
│ │ ├── common/ # app / auth / enums / middleware / model / upload / version
│ │ ├── admin/ # 管理端：controller / logic / param / resp / middleware / permission
│ │ ├── api/ # 用户端：controller / logic / param / resp
│ │ └── plugins/ # 编译期注册的插件（register_gen.go 自动生成）
│ ├── pkg/ # response / pagination / password / tree / dberror / oss / mask / sms / sn
│ ├── sql/ # 按版本目录维护的建表与增量脚本
│ └── docs/ # 接口文档、代码规范、版本更新说明
└── admin_client/ # 管理端前端
└── src/
├── api/ types/ enums/ utils/ store/ router/
├── directives/ components/ styles/
├── views/ # 核心页面（路径与菜单 path 对应）
└── plugins/ # 插件页面（/plugin/{id}/{view} 对应）服务生命周期
- 启动：加载配置 → 初始化 MySQL / Redis → 检查核心必需表与初始数据 → 注册编译期插件 → 校验插件版本、迁移与依赖 → 按依赖顺序注册路由并启动后台能力；
- 停止：取消插件 Context → 按相反顺序调用插件
Stop→ 优雅关闭 HTTP → 释放连接。
已启用但未编译进程序、版本不一致、迁移缺失或依赖异常的插件会阻止服务启动并给出明确错误。