命名约定

包与文件

• 包名小写无下划线。
• 文件名 xxx_handler.go / xxx_service.go / xxx_repository.go。
• 实体对应表名：SysUser → 表 sys_user。GORM SingularTable:true，表名单数，实体无需 TableName()。

分层命名

层	类型	实例	包级变量
handler	XxxApi struct{}	var XxxApiApp = new(XxxApi)	handler 直接用
service	XxxService struct{}	var XxxSvcApp = new(XxxService)	每次调用现取 repo
repository	XxxRepository struct{ db *gorm.DB }	NewXxxRepository(db) 由 service 取	不缓存成字段

model 子目录

子目录	用途	对应 Java
model/ (entity)	表实体 sys_xxx.go，嵌 repository.LogicDelete / BaseEntity	domain
model/bo/	入参（写入 BO + 查询 BO 分开）	domain.bo
model/vo/	出参 + excel tag	domain.vo
model/dto/	跨模块复用的领域模型（如 LoginUser、RoleDTO）	—

转换器

model/bo/conv.go、model/vo/conv.go 里的 goverter 接口 多数已声明好。缺了才补声明并 go generate ./internal/system/model/...。生成的 conv_gen.go 不要手改。

错误变量

哨兵错误命名 ErrXxxNotFound / ErrXxxKeyExists，文本带层前缀：

var ErrUserNotFound = errors.New("service: 用户不存在")
var ErrXxxNotFound = errors.New("repository: Xxx 不存在")

路由

• 集合根路径用 "" 而非 "/"，后者会注册成 /xxx/。
• 操作日志模块名常量：const xxxLogTitle = "参数管理"。
• 权限码 module:resource:action（如 system:user:list）。