签入版本

EasyGoAdmin_GoFrame_NaiveVue/zh/architecture/backend-layer.md

@@ -0,0 +1,98 @@
+# 4.3 后端分层架构
+
+:::tip 概述
+后端五层：api / controller / service / logic / dao。分层不是形式主义——每层有明确的"允许/禁止"清单，组合起来构成依赖红线体系。本节逐层说明职责与边界。
+:::
+
+## 分层与调用关系
+
+```text
+api/v1（契约层）
+   ▲ 依赖
+controller（HTTP 薄层）
+   ▲ 依赖接口
+service（接口层，手维护）
+   ▲ 实现
+logic（业务层，ModuleSpec 基座 + 钩子 + 手写逃生舱）
+   ▲ 唯一入口
+dao（数据访问层，红线条件 + 全局钩子）
+   ▲
+model/entity · model/hooks · gdb
+```
+
+侧路能力（横向复用）：`utility/{cache,captcha,crypto,excel,ip2layer,jwt,response,ua,upload}` 与 `consts`（错误码/缓存键/上下文键/日志类型）。
+
+## 各层职责与边界
+
+### api/v1（契约层）
+
++ 全部 Req/Res 结构体，**单包 v1**，每模块一文件（snake_case）
++ gmeta 注解声明 method/path/summary/permission/log/logType/public
++ gvalid 标签声明校验规则；`dc` 标签供 OpenAPI 文档
++ **禁止**：业务逻辑、数据库引用
+
+### controller（HTTP 薄层）
+
++ 一行透传 `return service.Xxx().Method(ctx, req)`
++ **禁止**：业务 if/for、import dao、手写响应信封、手写参数解析
+
+### service（接口层，手维护）
+
++ 每模块一文件：接口 `IXxx` + 实例变量 + 取用函数 `Xxx()` + 注册函数 `RegisterXxx()`
++ 未注册时取用 panic（启动即暴露接线错误）
++ **禁止**：整体运行 `gf gen service`（会覆盖手工重组结构）
+
+### logic（业务层）
+
++ 每模块一文件：`sXxx` 实现 + `xxxSpec` 声明 + `init()` 注册 + 标准委托 + 扩展手写
++ 共享能力经 `base.go`（15 个导出上限）与 `module_spec.go` 基座
++ 跨模块复用走同包包级函数（ResolveCityNames / LoadIdentity / ApplyDataScope / DictGetText…）
++ **禁止**：反向 import task；绕过 dao；在钩子里做 HTTP/文件 IO
+
+### dao（数据访问层）
+
++ 自定义模板产出：构造时挂 `hooks.Handler()`；`Ctx` 覆写注入红线条件
++ **禁止**：绕过直连 `g.DB()`；手写 del_flag/tenant_id 条件；手改 dao/internal/
+
+## 上下文键（consts/context_key.go）
+
+JWT 中间件写入身份，全链路 `consts.GetXxx(ctx)` 读取：
+
+| 写入方 | 键 |
+|--------|-----|
+| JWT 中间件 | UserID / TenantID / Username / Realname / TokenJTI / TokenExpire / Roles / Perms / DataScope / DeptID |
+| Response 中间件 | ClientIP / UserAgent / ReqMethod / ReqURL |
+
+::: warning 两套租户读法（易错点）
+`CtxTenantID(ctx)` —— 原始值（0=平台），仅供租户设施（hooks/中间件）使用
+`GetTenantID(ctx)` —— 业务归属值（租户返回自身，超管返回 tenant.defaultId），**新增/导入/唯一校验统一用它**
+:::
+
+数据范围读法：`GetDataScope(ctx)` 档位（1-全部；未注入回退全部）；`GetDeptID(ctx)` 部门 ID（0=未分配）。
+
+## 响应与错误码
+
+统一信封（utility/response）：
+
+```text
+成功：{"code":0, "ok":true, "msg":"操作成功", "data":{...}}
+失败：{"code":1, "ok":false, "msg":"...", "data":{}}
+未认证：HTTP 401 + {"code":401,...}
+```
+
+Fail 映射规则：gerror 码 == 401 原样保留；其余一律降级 code=1（前端 ResultEnum.ERROR 才弹 msg）。consts 中的细分错误码（1001 用户不存在…）主要用于日志与语义区分。
+
+分页契约：`PageData[T]` = `{records, total, size, current, pages}`，records 为空输出 `[]` 而非 null；pageNo 默认 1，pageSize 默认 10 上限 500。
+
+## 横切约定速查
+
+```text
+* 主键：int 数据库自增；新增后 result.LastInsertId() 回读
+* 软删：del_flag 0 正常 / 1 删除；删除接口全部软删
+* 表前缀：goframe_；文件命名 snake_case 对齐 dao（前端文件仍驼峰）
+* 入参/出参 json 驼峰；唯一例外：登录/令牌接口返回
+  access_token/refresh_token/expires_in/token_type（OAuth2 惯例，勿改）
+* 缓存键统一前缀 easygoadmin:
+* 权限码 sys:{module小驼峰}:{action}；超管 ROLE_SUPER_ADMIN；前端通配 *:*:*
+* 审计列：id/create_user/create_time/update_user/update_time/del_flag（租户表另有 tenant_id）
+```