架构说明

本文记录为什么这样设计与不易从代码直接读出的语义。编码规范见根目录 AGENTS.md，标准写法见 app/demo/。

数据权限（DataScope）

PermissionAction() 中间件从数据库取出当前用户的 DataScope 存入 gin.Context； Service 在查询时通过 actions.Permission(tableName, p) 这个 GORM Scope 追加 WHERE。

实现见 common/actions/permission.go:62-79，五档语义：

值	含义	过滤方式
`1` 或其他	全部数据	不追加条件
`2`	本角色关联部门的数据	`create_by` 属于 `sys_role_dept` 关联部门下的用户
`3`	本部门数据	`create_by` 属于同部门用户
`4`	本部门及子部门	按 `sys_dept.dept_path` 前缀匹配
`5`	仅本人	`create_by = 当前用户`

过滤依据是 create_by 字段，因此参与数据权限的表必须内嵌 models.ControlBy。

总开关：config/settings.yml 的 application.enabledp。关闭时 Permission 直接返回原查询，这也意味着关闭开关后所有数据权限配置立即失效，排查问题时先确认此项。

两类任务，配置在 sys_job 表：

自定义函数任务需实现 JobExec 接口（app/jobs/type.go:10）：

type JobExec interface {
    Exec(arg interface{}) error
}

并注册进 app/jobs/examples.go 的 jobList 映射，键名与 sys_job 表中配置的调用目标对应。

任务内需要数据库连接时，通过 sdk.Runtime.GetDbByKey("*") 获取，不要反向 import app/admin/service。

业务自定义配置写在 config/extend.go 中的结构体，对应 settings.yml 的 extend: 节点，代码中通过 config.ExtConfig.Xxx 访问。

配置值支持环境变量占位：在 yml 中写 ${ENV_NAME}，由 go-admin-core 的 config/reader/preprocessor.go 在加载时替换。敏感信息可借此避免写入文件。

WithContextDb 中间件按请求解析出对应的数据库连接放入上下文，Service 通过 e.Orm 取用。不要使用全局 DB 变量 —— 那会绕过多租户隔离。

多库配置见 settings.yml 的 databases 与 registers 节点，后者用于 dbresolver 读写分离。

迁移文件放 cmd/migrate/migration/version-local/，文件名前 13 位为 Unix 毫秒时间戳，框架按文件名升序执行，已执行版本记录在 sys_migration 表。

bash

go run main.go migrate -c config/settings.yml -g   # 生成骨架

已执行过的迁移文件不可修改 —— 版本号已入表，改动不会重跑。需要调整时新建迁移。