优化结构

docs/system-pkg-audit.md

@@ -18,7 +18,9 @@
 
 ## system 内部保留边界
 
-- `app`：组合根，绑定 system 的迁移、菜单、路由和任务贡献。
+- `app`：组合根，汇总各模块的迁移、菜单、路由和任务贡献。
+- `modules/system`：system 模块的 Definition，声明迁移、管理面和默认任务。
+- `modules/payment`：payment 模块的 Definition，声明支付迁移和支付管理面。
 - `biz`：用户、权限、菜单、审计、任务、支付订单和系统配置等领域模型与用例。
 - `conf`：system 配置 proto、运行时快照和生成代码。
 - `data`：数据库连接、PO、仓储、system 表、支付持久化和配置 watcher。
@@ -36,7 +38,8 @@
 
 ```text
 internal/
-  app/          # 组合根和模块定义
+  app/          # 组合根和 catalog
+  modules/      # 业务模块定义及其模块级贡献
   biz/          # DO、usecase、repo interface
   conf/         # 配置 proto/runtime
   data/         # PO、repo、数据库和迁移

docs/system-structure-audit.md

@@ -1,6 +1,6 @@
 # `internal` 目录结构优化结论
 
-参考 Go Kratos 的分层方式，顶层保留 `app`、`biz`、`conf`、`data`、
+参考 Go Kratos 的分层方式，顶层保留 `app`、`modules`、`biz`、`conf`、`data`、
 `initialize`、`integration`、`security`、`server`、`service`、`worker` 十个
 稳定职责。目录不是越少越好：同一技术角色文件较多时，应在所属层下分组，避免
 一个目录堆积几十个文件。
@@ -9,7 +9,9 @@
 
 ```text
 internal/
-  app/                 # 组合根、模块 catalog 和 definition
+  app/                 # 组合根、模块 catalog 和运行时组合
+  modules/system/      # system 模块定义
+  modules/payment/     # payment 模块定义
   biz/                 # DO、usecase、repo interface
   conf/                # 配置 proto/runtime
   data/                # PO、repo、数据库和迁移
@@ -38,12 +40,15 @@ internal/
   独立边界时不继续拆分。
 - 删除只转发 `pkg/protoutil` 的 `utils/configutil`。
 
-## `internal/app` 为什么只有两个文件
+## `internal/app` 为什么只保留组合代码
 
-`app/catalog.go` 和 `app/definition.go` 是有意保留的组合根。`catalog.go` 负责
-组装模块、任务注册与运行时；`definition.go` 声明 system 提供的迁移、管理面
-和默认定时任务。它们依赖多个层，只能位于应用组合边界，不能并入 `biz`、
-`service` 或 `data`。
+`app/catalog.go` 是有意保留的组合根，负责组装模块、任务注册与运行时。
+system 自身的迁移、管理面和默认定时任务位于
+`modules/system/definition.go`，由模块包声明后再被 catalog 汇总。这样模块
+定义不再和应用组合逻辑混在一起，也不能误并入 `biz`、`service` 或 `data`。
+
+Catalog 只能自动汇总静态模块贡献；新增模块若提供运行时路由或依赖型任务，仍需
+在 cmd/Wire 中显式注册，直到统一的 runtime contribution 协议落地。
 
 ## 其他目录审查