优化结构

docs/system-structure-audit.md

@@ -0,0 +1,57 @@
+# `app/system/internal` 目录结构优化结论
+
+参考 Go Kratos 的分层方式，顶层保留 `app`、`biz`、`conf`、`data`、
+`initialize`、`integration`、`security`、`server`、`service`、`worker` 十个
+稳定职责。目录不是越少越好：同一技术角色文件较多时，应在所属层下分组，避免
+一个目录堆积几十个文件。
+
+## 当前结构
+
+```text
+internal/
+  app/                 # 组合根、模块 catalog 和 definition
+  biz/                 # DO、usecase、repo interface
+  conf/                # 配置 proto/runtime
+  data/                # PO、repo、数据库和迁移
+  initialize/          # 首次安装和配置编排
+  integration/         # 外部 I/O provider
+  security/            # JWT 和安全实现
+  server/
+    handler/           # Gin handler，按资源命名
+    middleware/        # 认证、审计、限流、恢复等中间件
+    router/            # 各资源路由及 Routes 聚合
+    httpx/             # system HTTP 响应和 cookie 适配
+  service/
+    dto/               # HTTP 请求、响应和查询 DTO，按模块命名
+  worker/              # 任务运行时
+```
+
+## 本次调整
+
+- DTO 从 `service` 根目录归档到 `service/dto`。
+- handler、middleware、router、HTTP helper 分别归档到 `server` 子包。
+- 子目录内文件直接使用资源名，例如 `handler/payment.go`、
+  `router/payment.go`、`dto/payment.go`，不保留重复角色前缀。
+- Wire 直接装配 `handler.ProviderSet` 和 `router.ProviderSet`，server 根目录只
+  负责 Gin/Swagger 生命周期。
+- `security/adminauth/token.go` 合并为 `security/token.go`；单文件子包没有
+  独立边界时不继续拆分。
+- 删除只转发 `pkg/protoutil` 的 `utils/configutil`。
+
+## `internal/app` 为什么只有两个文件
+
+`app/catalog.go` 和 `app/definition.go` 是有意保留的组合根。`catalog.go` 负责
+组装模块、任务注册与运行时；`definition.go` 声明 system 提供的迁移、管理面
+和默认定时任务。它们依赖多个层，只能位于应用组合边界，不能并入 `biz`、
+`service` 或 `data`。
+
+## 其他目录审查
+
+- `data` 与 `integration` 已按仓储或 provider 分类，边界和生命周期明确。
+- `biz`、`service` 根目录采用一资源一文件；进一步拆成资源子包会改变 Go 包
+  边界并容易引入循环依赖，本次不做纯视觉拆分。
+- `security` 当前只有一个文件，但安全实现是明确的依赖边界，后续认证机制也会
+  在此扩展，因此保留顶层包。
+
+新增目录应至少满足独立依赖方向、状态生命周期或稳定技术角色之一。不要回到
+一文件一目录，也不要为了减少目录数量把大量不同角色重新铺平。