refactor(structure): group platform, infra, and shared packages

Move process wiring, technical adapters, and cross-cutting contracts out of flat internal/ packages so new code has a clear home without changing business layout.
2026-10-04 15:06:37 +08:00 · 2026-07-24 15:28:39 +08:00
parent 290427d5fa
commit fbbb75095f
235 changed files with 434 additions and 429 deletions
@@ -125,7 +125,7 @@ func startThingCacheInvalidationListener() {
 | Auth Source | `repository/auth_source_cache.go` | Otter | Redis JSON | `oauth:auth_source_invalidation` ✅ |
 | OAuth 用户/Token | `apps/oauth/cache.go` | 自研 map | Redis JSON | ❌ 无 pub/sub（历史债） |
 | 推送渠道 | `repository/push_channel.go` | 无 | Redis JSON | ❌ 仅 Redis Del |
-| Storage 驱动 | `internal/storage/storage.go` | RWMutex 快照 | — | `storage:config_invalidation` ✅ |
+| Storage 驱动 | `internal/infra/objectstore/storage.go` | RWMutex 快照 | — | `storage:config_invalidation` ✅ |

 ## 新增缓存工作流

@@ -210,7 +210,7 @@ make code-check
 ## 相关文件

 - L1 引擎：`pkg/cache/ram/cache.go`
- DB/Redis 助手：`internal/db/redis.go`（`GetJSON`, `SetJSON`, `HGetJSON`, `PrefixedKey`）
+- DB/Redis 助手：`internal/infra/persistence/redis.go`（`GetJSON`, `SetJSON`, `HGetJSON`, `PrefixedKey`）
 - 金标准：`internal/repository/system_config_cache.go`
 - 上传元数据：`internal/apps/upload/cache/meta_cache.go`
 - Auth Source：`internal/repository/auth_source_cache.go`
@@ -1,6 +1,6 @@
 ---
 name: "clickhouse-batchwriter"
-description: "Wavelet 项目专用：当新增或修改 ClickHouse 批量写入、接入 internal/db/batchwriter、将业务域异步 flush 到分析表、迁移 risk_control/节点访问日志/可观测时序写入、或评估 async_insert 与背压策略时必须使用。本技能指导分层职责、各域独立 Writer 实例、repository 批量 API 与禁止写法。"
+description: "Wavelet 项目专用：当新增或修改 ClickHouse 批量写入、接入 internal/infra/persistence/batchwriter、将业务域异步 flush 到分析表、迁移 risk_control/节点访问日志/可观测时序写入、或评估 async_insert 与背压策略时必须使用。本技能指导分层职责、各域独立 Writer 实例、repository 批量 API 与禁止写法。"
 ---

 # ClickHouse 批量写入开发
@@ -13,13 +13,13 @@ DDL 与表结构变更见 `database-migration` 技能；本技能只覆盖**运

 | 层级 | 路径 | 职责 |
 | :--- | :--- | :--- |
-| 连接 | `internal/db/clickhouse.go` | `ChConn`（原生批量写）、`ChDB`（GORM 查询）；禁止在业务包直接 `clickhouse.Open` |
-| 批量框架 | `internal/db/batchwriter/` | 泛型队列 + 按条数/时间 flush + 非阻塞入队 + 优雅停机；**各业务域独立实例** |
+| 连接 | `internal/infra/persistence/clickhouse.go` | `ChConn`（原生批量写）、`ChDB`（GORM 查询）；禁止在业务包直接 `clickhouse.Open` |
+| 批量框架 | `internal/infra/persistence/batchwriter/` | 泛型队列 + 按条数/时间 flush + 非阻塞入队 + 优雅停机；**各业务域独立实例** |
 | Model | `internal/model/analytics/` | 列定义、`TableName()`、`BatchInsertSQL()`（及可选 `InsertColumns()`） |
 | Repository | `internal/repository/analytics/` | `BatchInsert*` / `BatchInsertNodeAccessLogs` 等；`PrepareBatch` + 多行 `Append` + 一次 `Send` |
 | Apps | `internal/apps/<domain>/` | 采集、入队、背压；`FlushFunc` 只调 repository，不写 SQL、不 `PrepareBatch` |
-| 装配 | `internal/bootstrap/bootstrap.go` | 进程启动时调用 `Writer.Start`；初始化时需调用 `lifecycle.OnShutdown` 挂载停机钩子 |
-| 生命周期 | `internal/lifecycle/lifecycle.go` | 统一协调全局并发优雅停机，业务包无需在 `bootstrap.go` 中硬编码 `Stop` 逻辑 |
+| 装配 | `internal/platform/bootstrap/bootstrap.go` | 进程启动时调用 `Writer.Start`；初始化时需调用 `lifecycle.OnShutdown` 挂载停机钩子 |
+| 生命周期 | `internal/platform/lifecycle/lifecycle.go` | 统一协调全局并发优雅停机，业务包无需在 `bootstrap.go` 中硬编码 `Stop` 逻辑 |

 **禁止**在 Handler / middleware 内直接 `db.ChConn.PrepareBatch`；**禁止**在 repository 内启动 goroutine 或维护全局 channel（队列生命周期由 apps + bootstrap 或专用 writer 包负责）。

@@ -68,7 +68,7 @@ writer.Stop(stopCtx)      // close 队列 + drain + 最终 flush
 ## 新增 ClickHouse 写入工作流

 1. **Model**：在 `internal/model/analytics/` 定义 struct 与 `BatchInsertSQL()`（列顺序与 goose DDL 一致）。
-2. **Goose DDL**：在 `internal/db/migrator/goose/clickhouse/` 新增迁移（见 `database-migration`）。
+2. **Goose DDL**：在 `internal/infra/persistence/migrator/goose/clickhouse/` 新增迁移（见 `database-migration`）。
 3. **Repository**：实现 `BatchInsertX(ctx, []analyticsmodel.X) error`：
    - `len(items)==0` 直接返回
    - `db.ChConn == nil` 返回明确错误
@@ -78,7 +78,7 @@ writer.Stop(stopCtx)      // close 队列 + drain + 最终 flush
    - 业务路径 `TryEnqueue`；HTTP 背压用 `IsFull()`
 5. **测试**：
    - repository：mock `ChConn` 验证 `BatchInsertSQL` 与 append 列数
-    - batchwriter：`go test ./internal/db/batchwriter`
+    - batchwriter：`go test ./internal/infra/persistence/batchwriter`
 6. 运行 `make code-check`；有 API 变更时 `make swagger`。

 ## 背压与丢弃策略
@@ -110,7 +110,7 @@ var globalChan chan any

 ## async_insert（补充，非主方案）

-可在 `internal/db/clickhouse.go` 的 `Settings` 增加服务端异步写入作为第二层防护：
+可在 `internal/infra/persistence/clickhouse.go` 的 `Settings` 增加服务端异步写入作为第二层防护：

 ```go
 "async_insert": 1,
@@ -122,7 +122,7 @@ var globalChan chan any
 ## Bootstrap 装配示例

 ```go
-// internal/bootstrap/bootstrap.go（示意）
+// internal/platform/bootstrap/bootstrap.go（示意）
 var userAccessLogWriter *batchwriter.Writer[*analytics.UserAccessLog]

 func RegisterAPI(ctx context.Context) {
@@ -141,7 +141,7 @@ func RegisterAPI(ctx context.Context) {
 ## 验证清单

 ```bash
-go test ./internal/db/batchwriter
+go test ./internal/infra/persistence/batchwriter
 go test ./internal/repository/analytics
 make code-check
 ```
@@ -153,11 +153,11 @@ make code-check

 ## 相关文件速查

- 框架：`internal/db/batchwriter/{config,writer,errs}.go`
- 连接：`internal/db/clickhouse.go`
+- 框架：`internal/infra/persistence/batchwriter/{config,writer,errs}.go`
+- 连接：`internal/infra/persistence/clickhouse.go`
 - 审计写入：`internal/apps/risk_control/logics.go`
 - OpenFlare 写入胶水：`internal/apps/openflare/chwriter/writer.go`
 - 节点访问日志 repository：`internal/repository/analytics/node_access_log_writer.go`
 - 可观测 repository：`internal/repository/analytics/node_observability_writer.go`
- 生命周期管理器：`internal/lifecycle/lifecycle.go`
- Bootstrap：`internal/bootstrap/bootstrap.go`
+- 生命周期管理器：`internal/platform/lifecycle/lifecycle.go`
+- Bootstrap：`internal/platform/bootstrap/bootstrap.go`
@@ -1,17 +1,17 @@
 ---
 name: "database-migration"
-description: "Wavelet 项目专用：当新增或修改数据库表结构、索引、初始化数据、系统配置 seed、模板 seed、默认管理员、goose SQL 迁移、internal/db/migrator、ClickHouse 分析库 DDL 或数据库升级流程时必须使用。本技能指导在 internal/db/migrator/goose 下编写 PostgreSQL/SQLite 双方言 SQL 迁移，以及在 goose/clickhouse 下编写 ClickHouse 单方言分析表迁移，并完成验证。"
+description: "Wavelet 项目专用：当新增或修改数据库表结构、索引、初始化数据、系统配置 seed、模板 seed、默认管理员、goose SQL 迁移、internal/infra/persistence/migrator、ClickHouse 分析库 DDL 或数据库升级流程时必须使用。本技能指导在 internal/infra/persistence/migrator/goose 下编写 PostgreSQL/SQLite 双方言 SQL 迁移，以及在 goose/clickhouse 下编写 ClickHouse 单方言分析表迁移，并完成验证。"
 ---

 # Wavelet 数据库升级操作指南

-Wavelet 使用 `github.com/pressly/goose/v3` 执行 SQL 迁移。迁移入口是 `internal/db/migrator.Migrate()`，SQL 文件嵌入在二进制中。
+Wavelet 使用 `github.com/pressly/goose/v3` 执行 SQL 迁移。迁移入口是 `internal/infra/persistence/migrator.Migrate()`，SQL 文件嵌入在二进制中。

 ## 基本规则

 - SQL 迁移文件放在：
-    - `internal/db/migrator/goose/postgres/`
-    - `internal/db/migrator/goose/sqlite/`
+    - `internal/infra/persistence/migrator/goose/postgres/`
+    - `internal/infra/persistence/migrator/goose/sqlite/`
 - PostgreSQL 和 SQLite 必须使用同一个版本号、同一个语义文件名。
 - 迁移文件使用 goose SQL 标记：

@@ -51,7 +51,7 @@ Wavelet 使用 `github.com/pressly/goose/v3` 执行 SQL 迁移。迁移入口是
 7. 至少运行：

 ```bash
-go test ./internal/db/migrator
+go test ./internal/infra/persistence/migrator
 go test ./internal/model ./internal/apps/config ./internal/apps/admin/system_config
 make code-check
 ```
@@ -89,10 +89,10 @@ ClickHouse 是**辅助 OLAP 存储**，与 PostgreSQL/SQLite 主库**完全独

 | 路径 | 职责 |
 | :--- | :--- |
-| `internal/db/migrator/goose/clickhouse/` | **唯一** ClickHouse DDL 来源（goose SQL，嵌入二进制） |
+| `internal/infra/persistence/migrator/goose/clickhouse/` | **唯一** ClickHouse DDL 来源（goose SQL，嵌入二进制） |
 | `internal/model/analytics/` | 分析表 Go model，列名须与 goose DDL 一致 |
 | `internal/repository/analytics/` | 所有 ClickHouse 读写（批量写入、查询、聚合） |
-| `internal/db/clickhouse.go` | 连接初始化（`ChConn` 原生批量、`chDB` GORM 查询） |
+| `internal/infra/persistence/clickhouse.go` | 连接初始化（`ChConn` 原生批量、`chDB` GORM 查询） |

 ### 迁移入口与版本表

@@ -116,16 +116,16 @@ ClickHouse 是**辅助 OLAP 存储**，与 PostgreSQL/SQLite 主库**完全独
 按以下顺序落地，避免列名或类型漂移：

 1. **Model**：在 `internal/model/analytics/` 定义 struct，`gorm:"column:..."` 与 DDL 列名一一对应；实现 `TableName()`，批量写入表可提供 `InsertColumns()` / `BatchInsertSQL()`。
-2. **Goose SQL**：在 `internal/db/migrator/goose/clickhouse/` 新增递增版本文件（格式同主库，如 `YYYYMMDDNNNN_create_xxx.sql`），编写 `-- +goose Up` / `-- +goose Down`。
+2. **Goose SQL**：在 `internal/infra/persistence/migrator/goose/clickhouse/` 新增递增版本文件（格式同主库，如 `YYYYMMDDNNNN_create_xxx.sql`），编写 `-- +goose Up` / `-- +goose Down`。
 3. **Repository**：在 `internal/repository/analytics/` 实现 `BatchInsert*`（`db.ChConn` 一次 `PrepareBatch` + 多行 `Append` + 一次 `Send`）与查询（`db.ChDB`）；连接未初始化时返回明确错误，**不要**在 handler 写 SQL，**不要**在 repository 内维护 channel/goroutine。
-4. **Apps**：在 `internal/apps/<domain>/` 编排采集与入队；高频写入通过 `internal/db/batchwriter` 各域独立实例异步 flush（详见 `clickhouse-batchwriter` 技能），`FlushFunc` 只调 repository `BatchInsert*`；管理端统计 API 只读 repository，不触达 DDL。
+4. **Apps**：在 `internal/apps/<domain>/` 编排采集与入队；高频写入通过 `internal/infra/persistence/batchwriter` 各域独立实例异步 flush（详见 `clickhouse-batchwriter` 技能），`FlushFunc` 只调 repository `BatchInsert*`；管理端统计 API 只读 repository，不触达 DDL。

 ### ClickHouse 验证

 至少运行：

 ```bash
-go test ./internal/db/migrator
+go test ./internal/infra/persistence/migrator
 go test ./internal/repository/analytics
 make code-check
 ```
@@ -15,7 +15,7 @@ Wavelet 将「对象存储」与「上传业务」分为两层，**禁止混用

 | 层级 | 包路径 | 职责 | 业务是否直接调用 |
 | :--- | :--- | :--- | :--- |
-| **对象存储引擎** | `internal/storage` | `Backend` 接口：`Put` / `Get` / `Delete` / `Test`；按配置切换 Local / S3 / R2 / OSS / WebDAV | **禁止**（仅 upload 域内部使用） |
+| **对象存储引擎** | `internal/infra/objectstore` | `Backend` 接口：`Put` / `Get` / `Delete` / `Test`；按配置切换 Local / S3 / R2 / OSS / WebDAV | **禁止**（仅 upload 域内部使用） |
 | **上传域服务** | `internal/apps/upload` | `w_uploads` 记录、权限、秒传、统计、文件服务、`upload.Ingest` | **必须** |
 | **上传 HTTP 入口** | `internal/apps/upload/handler` | `POST /api/v1/upload` 等 multipart 接口 | 前端 / 用户侧上传 |
 | **文件访问** | `internal/apps/upload/filesrv` | `GET /f/:id` 流式响应、访问控制、图片 WebP 压缩 | 展示 / 下载 |
@@ -6,7 +6,7 @@ package references
 import (
 	"net/http"

-	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/Rain-kl/Wavelet/internal/shared/response"
 	"github.com/gin-gonic/gin"
 )

@@ -11,13 +11,13 @@ description: "Wavelet 项目专用：新增或修改 Asynq 异步任务、后台

 按任务范围检查当前实现：

- `internal/task/handler.go`：`TaskHandler`、`TaskResult`、`PayloadValidator`
- `internal/task/meta.go`：`TaskMeta`、`TaskParam`
- `internal/task/executor.go`：下发、执行、日志、重试、`OnTaskCompleted` 订阅
- `internal/task/handlers/register.go`：Handler 和元数据注册（由 bootstrap 调用）
- `internal/bootstrap/bootstrap.go`：任务注册与进程级装配入口
- `internal/task/worker/worker.go`：Worker 路由和队列
- `internal/task/scheduler/scheduler.go`：定时调度
+- `internal/infra/task/handler.go`：`TaskHandler`、`TaskResult`、`PayloadValidator`
+- `internal/infra/task/meta.go`：`TaskMeta`、`TaskParam`
+- `internal/infra/task/executor.go`：下发、执行、日志、重试、`OnTaskCompleted` 订阅
+- `internal/infra/task/handlers/register.go`：Handler 和元数据注册（由 bootstrap 调用）
+- `internal/platform/bootstrap/bootstrap.go`：任务注册与进程级装配入口
+- `internal/infra/task/worker/worker.go`：Worker 路由和队列
+- `internal/infra/task/scheduler/scheduler.go`：定时调度
 - `internal/apps/admin/task/routers.go`：Admin 任务 API
 - `internal/model/task_execution.go`：执行记录和日志持久化

@@ -46,7 +46,7 @@ description: "Wavelet 项目专用：新增或修改 Asynq 异步任务、后台

 ### 注册

- 在 `internal/task/handlers/register.go` 同时注册 Handler 和 `TaskMeta`。
+- 在 `internal/infra/task/handlers/register.go` 同时注册 Handler 和 `TaskMeta`。
 - 不要在其他位置单独注册任务。
 - **禁止**在业务包 `routers.go` 或 `init()` 中调用 `task.RegisterHandler`；统一由 `bootstrap.RegisterTasks()` → `taskhandlers.Register()` 在进程启动时装配。
 - 任务完成钩子（如 push 通知）通过 `task.OnTaskCompleted` 注册，在 `bootstrap.RegisterTaskListeners()` 中装配（Worker/`all` 进程）。
@@ -92,7 +92,7 @@ description: "Wavelet 项目专用：新增或修改 Asynq 异步任务、后台
  - `Retryable=true`
  - `RetryCount < MaxRetry`
 - 修改重试行为时同时检查：
-  - `internal/task/executor.go`
+  - `internal/infra/task/executor.go`
  - `internal/model/task_execution.go`
  - `internal/apps/admin/task/routers.go`
  - 前端任务执行列表
@@ -163,7 +163,7 @@ func (h *SendEmailHandler) Execute(ctx context.Context, payload []byte) (*task.T

 ## 统一注册

-在 `internal/task/handlers/register.go` 注册。Admin dispatch 的 `ValidateAndNormalizePayload` 和 Worker 执行都依赖这里。
+在 `internal/infra/task/handlers/register.go` 注册。Admin dispatch 的 `ValidateAndNormalizePayload` 和 Worker 执行都依赖这里。

 ```go
 package handlers
@@ -184,7 +184,7 @@ func Register() {

 系统默认的定时任务必须通过 Goose SQL 迁移初始化插入到 `schedules` 表。

-在 `internal/db/migrator/goose/postgres` 下的示例：
+在 `internal/infra/persistence/migrator/goose/postgres` 下的示例：

 ```sql
 -- +goose Up
@@ -274,4 +274,4 @@ func TestDispatchTaskValidatesPayload(t *testing.T) {
 }
 ```

-需要 Redis/Asynq 时优先复用项目现有测试模式；没有现成依赖时可用 `miniredis` 初始化 `task.AsynqClient`。不要把 `internal/task` 依赖塞进通用 testhelper 造成 import cycle。
+需要 Redis/Asynq 时优先复用项目现有测试模式；没有现成依赖时可用 `miniredis` 初始化 `task.AsynqClient`。不要把 `internal/infra/task` 依赖塞进通用 testhelper 造成 import cycle。
@@ -31,8 +31,8 @@ Wavelet 当前有两套设置入口：
 修改前快速查看这些文件，确认当前实现没有漂移：

 - `internal/model/system_configs.go`: 配置 key 常量、`SystemConfig` 模型、`GetByKey`、`GetBoolByKey`、`GetIntByKey`、`GetDecimalByKey` 等读取方法。
- `internal/db/migrator/goose/postgres/*.sql` 和 `internal/db/migrator/goose/sqlite/*.sql`: `system_configs` 表结构、初始化 seed、后续升级迁移。
- `internal/db/migrator/migrator.go`: goose 迁移入口和 PostgreSQL/SQLite 方言选择。
+- `internal/infra/persistence/migrator/goose/postgres/*.sql` 和 `internal/infra/persistence/migrator/goose/sqlite/*.sql`: `system_configs` 表结构、初始化 seed、后续升级迁移。
+- `internal/infra/persistence/migrator/migrator.go`: goose 迁移入口和 PostgreSQL/SQLite 方言选择。
 - `internal/testhelper/test_helper.go`: Go 测试用默认系统配置 seed。
 - `internal/apps/admin/system_config/routers.go`: `/api/v1/admin/system-configs` 参数表 API。
 - `internal/apps/config/routers.go`: `/api/v1/config/public` 公共配置响应。
@@ -52,7 +52,7 @@ Wavelet 当前有两套设置入口：
   - 值仍存为字符串；布尔值用 `"true"` / `"false"`，数值用十进制字符串，复杂结构用 JSON 字符串。

 2. 初始化默认配置。
-   - 如果修改初始 schema，必须同步 `internal/db/migrator/goose/postgres/` 和 `internal/db/migrator/goose/sqlite/` 中的 goose SQL。
+   - 如果修改初始 schema，必须同步 `internal/infra/persistence/migrator/goose/postgres/` 和 `internal/infra/persistence/migrator/goose/sqlite/` 中的 goose SQL。
   - 既有库新增配置时，新增一组时间戳递增的双 SQL 迁移文件，分别放在 PostgreSQL 和 SQLite 目录；不要回到 GORM AutoMigrate 或 Go 代码 seed。
   - 新库初始化也需要包含同一个默认 key：当前初始 seed 在 `202606090001_initial_schema.sql` 的 `INSERT INTO system_configs (...) VALUES ... ON CONFLICT (key) DO NOTHING`。
   - 设置正确的 `Type`：只能是 `"system"` 或 `"business"`。
@@ -62,7 +62,7 @@ Wavelet 当前有两套设置入口：

 3. 读取配置。
   - 后端业务代码优先使用 `model.GetBoolByKey`、`model.GetIntByKey`、`model.GetDecimalByKey` 或 `SystemConfig.GetByKey`。
-   - 运行时可热更新的规则不要放进 `config.Config`；启动时设置才走 `internal/config/model.go` 和 `config.example.yaml`。
+   - 运行时可热更新的规则不要放进 `config.Config`；启动时设置才走 `internal/infra/config/model.go` 和 `config.example.yaml`。
   - 不要在 handler 或业务代码里直接读 `os.Getenv()`。

 4. 如果前端需要未登录或全局消费，暴露为公共可见配置。
@@ -89,7 +89,7 @@ Wavelet 当前有两套设置入口：

 只有在配置必须随进程启动确定、不能或不应热更新时，才走启动时设置。

-1. 在 `internal/config/model.go` 添加配置字段。
+1. 在 `internal/infra/config/model.go` 添加配置字段。
 2. 在 `config.example.yaml` 添加示例值和说明。
 3. 确认 Viper 现有加载逻辑能绑定该字段；需要环境变量时沿用当前命名和绑定方式。
 4. 运行时代码从 `config.Config.<Section>.<Field>` 读取。
@@ -19,7 +19,7 @@ Wavelet 的消息推送机制采用了**元数据驱动 + 统一触发器 + 异
 | **`internal/apps/admin/push/`** | 通知服务与后台任务层 | 包含以下核心文件：<br>1. [events.go](file:///Users/ryan/DEV/Go/Wavelet/internal/apps/admin/push/events.go)：定义通知事件的结构模型（`NotificationMessage`, `EventMetadata`）、内置事件的动态注册中心（`BuiltInEvents` 及 `RegisterBuiltInEvent` 函数）以及统一触发器类 `EventTrigger`（包括其底层的派发引擎逻辑）。<br>2. [tasks.go](file:///Users/ryan/DEV/Go/Wavelet/internal/apps/admin/push/tasks.go)：定义 Asynq 后台异步发送任务、处理器 `PushHandler` 及其校验逻辑，并记录推送历史审计。<br>3. [routers.go](file:///Users/ryan/DEV/Go/Wavelet/internal/apps/admin/push/routers.go)：管理端接口，负责获取事件配置列表和更新配置。 |
 | **`internal/apps/admin/push/custom_events/`** | 自定义通知事件包 | 事件元数据定义与 push 侧处理逻辑；**一个 Go 文件代表一个事件**。在 [register.go](file:///Users/ryan/DEV/Go/Wavelet/internal/apps/admin/push/custom_events/register.go) 统一装配，禁止 `init()` 副作用。 |
 | **`internal/listener/`** | 域事件分发层 | 核心域发射事件（如 `EmitAdminLoggedIn`），push 在 bootstrap 阶段通过 `OnAdminLoggedIn` 订阅，避免 auth/user 直接依赖 push。 |
-| **`internal/bootstrap/`** | 应用装配根 | `RegisterPushDomainEvents()` 调用 `custom_events.Register()`；`Init` 中执行 `SyncEvents` 将内置事件元数据同步到数据库。 |
+| **`internal/platform/bootstrap/`** | 应用装配根 | `RegisterPushDomainEvents()` 调用 `custom_events.Register()`；`Init` 中执行 `SyncEvents` 将内置事件元数据同步到数据库。 |
 | **数据库审计表** | 状态与历史审计 | `w_push_events` 存放每个通知事件的启用状态、启用渠道、发送目标和自定义渲染模板。<br>`w_push_histories` 存放消息发送记录用于审计。 |

 ---
@@ -168,4 +168,4 @@ func Register(c *gin.Context) {
 ### 3. 禁止 init() 与 router 副作用注册 (Explicit Bootstrap)
 - 不得在 `init()` 中调用 `RegisterBuiltInEvent` 或订阅 listener。
 - 不得在 `router.go` 空白导入 `custom_events` 触发注册。
- 统一在 `internal/bootstrap` + `internal/cmd` 入口显式装配。
+- 统一在 `internal/platform/bootstrap` + `internal/cmd` 入口显式装配。