# Internal Modules

参考 Kratos beer-shop 的垂直业务拆分方式，业务代码按模块组织在
`internal/modules/<name>` 下。当前项目是模块化单体，因此共享一个进程和组合根，
但每个模块仍独立拥有 `biz`、`data`、`service`、`transport` 和初始化贡献。

## 当前模块

`system` 是模板自带的后台管理模块，包含用户、权限、菜单、API、公告、部门、
字典、文件、审计、定时任务、支付和系统初始化等现有表与逻辑。

## 新增业务模块

新增业务请创建 `internal/modules/<business>`，不要把领域模型、仓储或 HTTP
处理器继续添加到 `internal/biz`、`internal/data`、`internal/service` 等根目录。
数据库表和迁移由业务模块自己的 `data` 包负责；只有数据库连接生命周期和通用
迁移执行器属于 `internal/platform/database`。

模块通过 `internal/app/catalog.go` 接入组合根：

- `module.Definition.Migrations`：模块自己的表结构迁移
- `module.Definition.Surface`：菜单和 API 元数据，首次初始化时统一写入系统表
- `module.Definition.TimedTasks`：模块默认定时任务记录
- `module.Definition.Tasks`：无状态的进程内任务方法
- `module.RouteRegistrar`：需要依赖 Handler 的路由注册器，在 `app.Runtime` 中组合

无依赖的任务方法可以放进 `Definition.Tasks`。需要仓储或用例依赖的任务方法由
模块实现 `task.Contributor`，再由 `internal/app` 激活。新增模块只修改应用组合根，
不修改 `system` 的初始化、worker、路由或数据层。

`integration` 是外部系统适配器，不是通用工具；只有实现了稳定跨模块协议的能力
才上移到 `platform`。`utils` 仅保留无状态、无业务语义且确实被本模块复用的函数。