go_backend_frame 代码规范
目的
在 go_backend_frame（后端 server_api + 前端 admin_client）中新增或修改代码时，保证目录结构、分层方式、命名风格、响应格式与权限边界与现有工程一致。
使用场景
- 新增/修改后端接口（controller、logic、param、resp、model、路由、中间件）。
- 新增/修改前端页面、接口封装、类型、枚举、组件。
- 评审代码是否符合本项目约定。
- 新增数据库表或配置字段时确定脚本与配置落点。
工作流程
1. 确定改动端与落点
- 后端改动先判断属于管理端（
internal/admin）还是用户端（internal/api），两端共用的能力放internal/common/<功能>，无业务归属的工具放pkg/<功能>。 - 前端改动按模块定位到
src/api/<module>.ts、src/types/<module>.ts、src/views/<模块>/<页面>/index.vue。
2. 后端改动按分层落地（顺序）
internal/common/model/定义或复用 GORM 模型（表结构脚本放sql/）。internal/<端>/param/新增请求结构体（按功能分文件，字段带json/form、binding、validate、comment）；Controller 通过pkg/validate统一绑定与返回语义化错误。internal/<端>/resp/新增响应结构体（列表用list+total；树用data+children）。internal/<端>/logic/写业务规则，方法统一接收*gin.Context。internal/<端>/controller/只做绑定与响应。router/admin.go或router/api.go注册路由，挂到正确的中间件组。
详细模板与禁止事项见 references/backend-go.md。
3. 前端改动按模块落地
src/types/<module>.ts定义请求与响应类型（复用BaseEntity、PageQuery、PageResult、TreeNode）。src/api/<module>.ts用request<T>()封装，禁止直接使用 axios。src/enums/<module>.ts定义枚举（数值与后端一致，从 1 开始）。src/views/<模块>/<页面>/index.vue使用<script setup lang="ts">与箭头函数。- 列表操作列统一使用 Element Plus 图标按钮，复用
.table-operations/.op-icon，每个图标必须提供el-tooltip、对应的v-perm权限指令和明确的危险色；禁止在操作列直接展示“编辑”“删除”等文字链接。
详细约定见 references/frontend-vue.md。
4. 收尾检查
- 后端：
gofmt -l .无输出、go vet ./...、go build ./...通过。 - 前端：
pnpm exec vue-tsc --noEmit、pnpm build通过。 - 接口变更同步
go_basic_frame_wiki/public/openapi/admin_openapi.yaml与 Apifox 文档。 - 配置新增同步
config/config.go、config.example.yaml与 README 配置表。 - 未提交
config.yaml、.env*、证书、密钥、构建产物。 - 开发版本以实际
config.yaml的version为唯一来源；SQL、更新说明和 Wiki 放入该版本目录，不得自行提升版本。正式发版时再同步config.example.yaml。
速查规则
| 主题 | 规则 |
|---|---|
| 响应 | 一律 response.OK/Fail，HTTP 200，业务码 0/400/401/403/500/503 |
| 上下文 | controller 必须把 *gin.Context 传入 logic |
| 参数 | 请求结构体放 param 且按功能分文件，禁止合并为 param.go |
| 权限 | 按钮权限格式 METHOD:/path；免鉴权接口登记 enums.SkipPermissionApis |
| 缓存 | 菜单/角色/用户权限变更后必须清 perm:<user_id> 或全量权限缓存 |
| 密钥 | 响应结构不返回私钥/公钥/Secret；配置模板用占位符 |
| 上传 | 业务只存 relative_path，地址按默认存储动态生成，单文件 ≤50MB |
| 枚举 | 集中在 common/enums，数值从 1 开始，前端 src/enums 保持一致 |
| 数据库 | 禁止 AutoMigrate，变更提供 sql/ 脚本 |
| 前端请求 | 统一 request<T>()，baseURL 来自 VITE_ADMIN_API_BASE_URL |
| 前端时间 | 用 formatDateTime 格式化到秒 |
| 前端权限 | 按钮用 v-perm="'POST:/admin/user/add'" |
| 列表操作 | 行操作只使用带 el-tooltip 的图标按钮，复用 .table-operations / .op-icon，并保留 v-perm 与删除确认 |
参考文件
../CODE_STYLE.md：完整规范说明（人工阅读版）。references/backend-go.md：后端目录结构、分层职责、代码模板、常见禁止事项。references/frontend-vue.md：前端目录结构、接口/类型/页面模板、样式与提交检查。