签入版本

2026-10-20 21:19:44 +08:00
commit 7e70ed6942
2943 changed files with 498573 additions and 0 deletions
@@ -0,0 +1,89 @@
+# 3.11 常见问题与排错
+
+:::tip 概述
+本节收录模块开发阶段的高频问题，按「路由/编译/数据/权限/生成器」分组。更多通用排障见 [附录 A](../appendix/faq)。
+:::
+
+## 路由与注册
+
+### Q：新增接口 404
+
+排查顺序：
+
+```text
+1. router.go 是否有 Bind(s, new(controller.CXxx)) 注册行（生成器会自动写）
+2. 请求结构体是否内嵌 gmeta.Meta 且 method/path 标签正确
+3. 控制器方法签名是否为 (ctx, *v1.XxxReq) (*v1.XxxRes, error)——签名不符静默跳过
+4. 路径是否误带 /v1（本项目 URL 无版本段）
+```
+
+验证：`curl http://127.0.0.1:8000/api.json | grep "xxx"`——gmeta 会补注册进 OpenAPI。
+
+### Q：取用 service panic `implement not found`
+
+logic 的 `init()` 未调用 `service.RegisterXxx`，或接口文件的取用函数名与注册函数名不匹配。检查三件套（接口/取用/注册）拼写一致。
+
+## 编译与结构
+
+### Q：`go build` 报 logic 循环引用
+
+logic 是单包，跨模块直接调用包级函数即可，不要在 logic 内 import 其他会 import logic 的包。依赖红线：`task → logic` 单向允许；`logic → task` 禁止；middleware 经 wire.go 函数变量接线（不 import 业务包）。
+
+### Q：改动 logic 方法签名后编译通过但运行 403/空响应
+
+service 接口是手工维护的——签名变更必须同步 `internal/service/{模块}.go`，否则 controller 调用的是旧接口（编译期不报错的场景是接口方法恰好同签名但语义变化）。
+
+### Q：新增了字段但接口返回里没有
+
+三处都要检查：entity 是否刷新（`gf gen dao`）→ Req/Res 结构体是否含该字段 → ToData 是否映射（写侧）。读侧展示字段在 Item/DetailRes 声明即可（Struct 自动映射）。
+
+## 数据与隔离
+
+### Q：新增数据 tenant_id 为 0 或报错
+
+租户级表必须把表名加入 `internal/model/hooks/hooks.go` 的 `tenantTables` 清单（生成器不自动维护）。插入行为：租户用户零值自动填自身；超管未指定填 `tenant.defaultId`；显式 0 建平台共享行。
+
+### Q：查询结果包含已删除数据
+
+是否绕过了 `dao.{X}.Ctx(ctx)` 直连 `g.DB()`？红线：唯一查询入口是 dao.Ctx，它自动注入 `del_flag=0`。
+
+### Q：唯一校验漏报 1062 或跨租户误报
+
+`UniqueFields` 的 `Group` 范围必须等于唯一索引范围：索引含 tenant_id 时必须 `Group:"tenant_id"`。手写检查（如 user 的 username/mobile）按"被改行现租户"校验。
+
+### Q：删除报"存在下级或关联"
+
+模块 BeforeDelete 守卫（如 dept 有子级/用户、user 关联清理 user_role）。这是业务保护，需要先处理关联数据。
+
+## 权限与日志
+
+### Q：新接口一直 403
+
+```text
+1. gmeta permission 标签是否声明（空则仅需登录）
+2. 菜单里权限节点是否存在（sys:{module小驼峰}:{action}）
+3. 角色是否勾选该节点并保存（保存会清身份缓存）
+4. 测试账号是否重新登录（身份缓存 300s；可 DEL easygoadmin:user:identity:{uid}）
+```
+
+### Q：操作日志没记录
+
+检查：gmeta `log` 标签是否为空（空不记录）；`logType:"query"` 且 `operationLog.logQuery: false` 时查询类跳过；`operationLog.enable` 总开关；通道满会丢弃（每丢 100 条告警一次）。
+
+## 生成器
+
+### Q：生成器不创建字典
+
+枚举注释格式不对——须为 `字段名：1-正常 2-禁用` 形式（`-`/`—`/`＝`/`=` 分隔）。非 MySQL 库内省不到注释，建议在 MySQL 上生成。
+
+### Q：生成的前端页面路由 404
+
+菜单由生成器创建（path `/{domain}/{moduleCamel}`），但角色未勾选新菜单；或 component 路径与实际文件不符（domain 归属由 genDomainMap 决定）。
+
+### Q：重复生成会覆盖我的手工修改吗
+
+默认不会——`generator.overwrite: false` 时已存在文件跳过（计入 Skipped）。`overwrite: true` 时全部覆盖（计入 Overwritten），批量覆盖前务必备份或临时改回 false。
+
+### Q：租户级新表生成后数据不隔离
+
+生成器不维护 `tenantTables` 清单，需手工把表名加入 `internal/model/hooks/hooks.go` 后重启。