kra-oa/docs/audit/structure-optimization-plan.md

Kra 分层与结构优化计划

1. 目标与约束

本轮优化以现有 Kratos 分层契约为准，不改变 GVA 兼容接口的请求、响应、 事务和错误语义。目标是收紧 DTO/DO/PO 边界、降低单文件职责密度，并删除 确认未接入的代码；不按业务资源重建整套子包，也不创建泛化 utils。

结构决策遵循以下规则：

1. DTO 及 JSON/form/binding tag 只放在 internal/service/dto。
2. DO、usecase、repo interface 和领域上下文保留在 internal/biz。
3. PO、GORM/Casbin/缓存/文件存储等实现保留在 internal/data。
4. HTTP 绑定、路由和中间件保留在 internal/server；DTO -> DO 转换交给 service。
5. 只有无业务状态、至少有两个稳定消费者的能力才建立专用 internal/<name> 包。
6. 同包拆文件优先于新建 Go 子包，避免扩大导出面和破坏 Wire/事务协作。

2. 总体结论

静态依赖扫描未发现四层之间的硬性反向 import：biz 不依赖 data/service/server， data 不依赖 service/server/DTO，service 不依赖 data/server，server 不依赖 data。当前架构无需推倒重建，重点应放在文件职责和边界收紧。

不建议新增 pkg/utils。现有 pkg/adminauth、pkg/logging 已有清晰复用价值； 其他应用专属能力应留在 internal，防止把内部实现误扩成公共 API。

3. 按模块审查与执行计划

模块	当前判断	本轮动作	后续动作
登录与会话	LoginResult 是传输响应，却位于 service 根包	移入 service/dto	TokenAuthentication/AuthClaims 仍跨到 middleware，待专门设计 service 视图后再收口
用户	handler 构造导出的 service.UserInput，边界不够明确	将输入模型私有化，新增 DTO request 方法	data/user.go 按 read/write/relations 同包拆分
API/Casbin	data/api.go 混合目录 CRUD、策略和同步	同包拆为 api.go、api_policy.go、api_sync.go	继续保留 casbin.go 作为共享持久化辅助，不建 data 子包
初始化	DatabaseInit 带 binding tag，却位于 service 根包	移入 service/dto	初始化事务和 seed 保持在 data，不拆独立 package
路由目录/Swagger	路由分组表由 service 和 server 共同使用	抽到无状态的 internal/routeinfo	后续评估与 operation-audit 路由目录合并，避免一次性大改
字典	handler 直接构造 biz.DictionaryDetailFilter	增加 service request 转换入口	DTO 文件可在自然增长时再按资源拆分
媒体	handler 直接构造 biz.MediaFilter	增加 service request 转换入口	MediaConfig 的 biz 类型暴露可在配置 DTO 整理时一并处理
审计/导出	page、IDsFromQuery 放在 audit.go，但被多个 handler 使用	移到 handler/query.go，删除未引用 queryUintValue	审计错误映射保留在 handler，它属于 HTTP 展示语义
权限/组织	data 文件较大，但 PO、事务和权限检查高度协作	本轮保持行为不动	authority.go 同包拆 CRUD/relations/data-scope；system.go 改为更明确的 identity model/constructor 文件
配置/热更新	compat、merge、store、watch、bootstrap 已形成职责组	保持现状	仅在单文件继续增长时同包拆分，不创建 internal/data/config 子包
系统指标	service 直接调用 gopsutil，属于基础设施实现	本轮不动，避免扩大改动面	建立 biz provider interface，由 data 实现指标采集，service 只转 DTO
定时任务	biz 中存在全局可变 registry，worker 负责具体注册	本轮不动	中期改为向 TaskUsecase 注入方法目录；仍不放入 pkg
公共包	pkg/validate 无任何调用，未接入 Gin/Kratos 链路	删除 pkg/validate	biz/pagination.go 按仓库分层契约保留，不因当前调用少而删除

4. data 层拆分边界

已执行：API/Casbin

• api.go：repo 构造、PO、转换、API CRUD 与列表。
• api_policy.go：角色关联、授权判断、policy path 查询与替换。
• api_sync.go：ignore API 与 API registry 同步。
• casbin.go：继续保存跨 repo 使用的 Casbin rule 和数据库辅助函数。

这些文件仍为同一个 package data，PO 和事务辅助无需导出。

后续：身份与权限

建议在后续单独变更中完成，避免与接口兼容整改混在一起：

• user.go 拆为读取/装载、写入、用户关系三个文件；
• authority.go 拆为角色 CRUD/用户关系和 strict-auth/data-scope；
• system.go 中共享 PO 与 repo 构造器改用能表达 identity 职责的文件名；
• 不把 user/authority/menu PO 移到公共 model 包。

5. 测试文件处理

本轮不按文件数量删除测试。现有测试主要保护 GVA 兼容语义、事务原子性、 Casbin/数据权限、安全、迁移、路由契约、日志路径和调度器行为，删除收益小于 回归风险。

可以在后续纯测试整理中做两类无损合并：

• 将少量 service 转换测试合并为按资源命名的 conversion 测试文件；
• 先用覆盖率确认部门树重复断言，再删除真正被更完整用例覆盖的函数。

transactions_test.go、gin_test.go、认证/安全、策略/数据权限、日志文件、 任务执行器和初始化 ignore 测试必须保留。

6. 验收

1. gofmt 覆盖全部修改的 Go 文件。
2. go test ./... 使用仓库内可写 GOCACHE 执行。
3. 结构调整后重新扫描层间 import 和已删除符号引用。
4. 任何全量测试失败都区分为本轮回归或已有环境/资源清理问题。
5. 不修改生成文件，不改变 Wire provider、路由数量或外部 JSON 字段。