tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-10-06 23:56:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

test(bootstrap): fix review findings and sync architecture docs

Browse Source 
- Register tasks in admin/task test setup after init() removal
- Strengthen bootstrap test: RegisterPushDomainEvents before Init
- Add admin_login auth→push listener integration test
- Update AGENTS.md and push/new-async-task/new-api skills for
  bootstrap composition root, listener domain events, and explicit
  test wiring conventions introduced since 50c45db5
This commit is contained in:
ryan
2026-06-18 10:50:45 +08:00
parent dac1c979d1
commit 13f823e5e3
7 changed files with 281 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agent/skills/new-api/SKILL.md
+2 -1
View File
@@ -119,8 +119,9 @@ internal/
### 步骤 2：在模块内实现业务逻辑 (`logics.go` / `service.go`)
业务逻辑逻辑应当实现于 `internal/apps/custom/` 目录下：
- **优先使用纯函数（`logics.go`）**：定义接收 `context.Context` 且不依赖 `*gin.Context` 的函数，易于单元测试。
- **优先使用纯函数（`logics.go`）**：定义接收 `context.Context` 且不依赖 `*gin.Context` 的函数，易于单元测试与 Worker 复用。参考 `internal/apps/user/logics.go`。
- **有状态服务（`service.go`）**：若需注入依赖（如 DB 连接、外部客户端等），可定义 Service 结构体和构造函数。
- **跨模块副作用（推送、任务监听等）**：核心业务代码通过 `internal/listener` 发射域事件，禁止直接 `import` push 模块；装配在 `internal/bootstrap` 完成（参见 `push-notification` skill）。
### 步骤 3：编写 HTTP Handler (`routers.go`)
在 `internal/apps/custom/routers.go` 中编写 Handler：
.agent/skills/new-async-task/SKILL.md
+21 -2
View File
@@ -13,8 +13,9 @@ description: "Wavelet 项目专用：新增或修改 Asynq 异步任务、后台
- `internal/task/handler.go`：`TaskHandler`、`TaskResult`、`PayloadValidator`
- `internal/task/meta.go`：`TaskMeta`、`TaskParam`
- `internal/task/executor.go`：下发、执行、日志、重试
- `internal/task/handlers/register.go`：Handler 和元数据注册
- `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/apps/admin/task/routers.go`：Admin 任务 API
@@ -48,6 +49,24 @@ description: "Wavelet 项目专用：新增或修改 Asynq 异步任务、后台
- 在 `internal/task/handlers/register.go` 同时注册 Handler 和 `TaskMeta`。
- 不要在其他位置单独注册任务。
- **禁止**在业务包 `routers.go` 或 `init()` 中调用 `task.RegisterHandler`；统一由 `bootstrap.RegisterTasks()` → `taskhandlers.Register()` 在进程启动时装配。
- 任务完成钩子（如 push 通知）通过 `task.OnTaskCompleted` 注册，在 `bootstrap.RegisterTaskListeners()` 中装配（Worker/`all` 进程）。
### 进程装配分工
| 进程 | 注册入口 |
| :--- | :--- |
| `api` | `cmd/api.go` → `bootstrap.RegisterAPI()`（含 `RegisterTasks`） |
| `worker` | `worker.StartWorker()` → `bootstrap.RegisterWorker()`（含 `RegisterTasks` + `RegisterTaskListeners`） |
| `scheduler` | `scheduler.StartScheduler()` → `bootstrap.RegisterScheduler()` |
| `all` | `cmd/all.go` → `bootstrap.RegisterAll()` |
所有 `Register*` 使用 `sync.Once`，重复调用安全。
### 测试
- 依赖已注册任务类型或 Handler 的测试（如 `internal/apps/admin/task/routers_test.go`），必须在 setup 中显式调用 `bootstrap.RegisterTasks()`。
- 不得依赖 `init()` 副作用或 import 链触发注册。
## 日志要求
.agent/skills/push-notification/SKILL.md
+49 -39
View File
@@ -17,7 +17,9 @@ Wavelet 的消息推送机制采用了**元数据驱动 + 统一触发器 + 异
| :--- | :--- | :--- |
| **`pkg/push/`** | 推送基础设施层 | 静态定义、不依赖系统数据库和任何框架。定义了统一接口 `Pusher`、单例 `PusherPool` 和多实现（Lark, Webhook, Email 等），提供配置验证及发送功能。 |
| **`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/`** | 自定义通知事件包 | 自定义的事件定义和触发函数单独放到此包下，**一个 Go 文件代表一个事件**。例如：<br>[admin_login.go](file:///Users/ryan/DEV/Go/Wavelet/internal/apps/admin/push/custom_events/admin_login.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` 将内置事件元数据同步到数据库。 |
| **数据库审计表** | 状态与历史审计 | `w_push_events` 存放每个通知事件的启用状态、启用渠道、发送目标和自定义渲染模板。<br>`w_push_histories` 存放消息发送记录用于审计。 |
---
@@ -26,8 +28,8 @@ Wavelet 的消息推送机制采用了**元数据驱动 + 统一触发器 + 异
如果某个新业务（如“新用户注册”或“订单创建”）需要带有消息推送功能，请严格按照以下步骤开发：
### 步骤 1：在 `custom_events/` 中以一个文件声明事件元数据
在 `internal/apps/admin/push/custom_events/` 下新建一个 Go 文件（如 `user_registered.go`），声明其事件元数据并利用 `init()` 动态注册。
### 步骤 1：在 `custom_events/` 中声明事件元数据与处理函数
在 `internal/apps/admin/push/custom_events/` 下新建一个 Go 文件（如 `user_registered.go`），声明 `EventMetadata` 和 push 侧处理函数（组装 body 并调用 `DefaultTrigger.Trigger`）。
```go
package custom_events
@@ -37,10 +39,9 @@ import (
"time"
"github.com/Rain-kl/Wavelet/internal/apps/admin/push"
"github.com/Rain-kl/Wavelet/internal/model"
"github.com/Rain-kl/Wavelet/internal/listener"
)
// NewUserRegistered is the metadata definition for the user registered event.
var NewUserRegistered = push.EventMetadata{
Key: "user_registered",
Name: "新用户注册提醒",
@@ -52,58 +53,58 @@ var NewUserRegistered = push.EventMetadata{
Description: "当系统有新用户注册成功时，向管理员或指定目标发送通知",
}
func init() {
push.RegisterBuiltInEvent(NewUserRegistered)
}
```
### 步骤 2：在该事件文件中编写触发封装函数 (Wrapper)
为了使业务层调用方便且类型安全，在同一个事件 Go 文件中为该事件定义一个封装函数。
> [!NOTE]
> - 底层框架 `EventTrigger.Trigger` 本身已经内置了**异步 Goroutine 执行**以及 **`context.WithoutCancel(ctx)` 衍生上下文转换**逻辑。
> - 开发者只需在封装函数中组装数据，并直接调用 `DefaultTrigger.Trigger` 即可，无需在外部手动写 `go func()` 也不需要处理上下文防取消问题，从而通过框架底层强制约束了异步投递行为。
```go
// TriggerNewUserRegisteredEvent triggers the user registration notification event.
func TriggerNewUserRegisteredEvent(ctx context.Context, user *model.User) {
if user == nil {
func handleUserRegistered(ctx context.Context, event listener.UserRegistered) {
if event.User == nil {
return
}
body := map[string]any{
"user": user,
"user": event.User,
"time": time.Now().Format("2006-01-02 15:04:05"),
}
push.DefaultTrigger.Trigger(ctx, NewUserRegistered, body)
}
```
### 步骤 3：在业务代码中调用触发函数
在业务逻辑完成处（例如 `internal/apps/user/routers.go` 的注册 Handler 中）导入 `custom_events` 并调用该函数。
> `EventTrigger.Trigger` 已内置异步 Goroutine 与 `context.WithoutCancel`；处理函数内直接调用即可，无需外层 `go func()`。
### 步骤 2：在 `listener/` 定义域事件并在 `register.go` 装配
1. 在 `internal/listener/` 新增域事件类型、`Emit*` 与 `On*` 注册函数（参考 [admin_login.go](file:///Users/ryan/DEV/Go/Wavelet/internal/listener/admin_login.go)）。
2. 在 [register.go](file:///Users/ryan/DEV/Go/Wavelet/internal/apps/admin/push/custom_events/register.go) 中注册元数据并订阅域事件：
```go
import (
"github.com/Rain-kl/Wavelet/internal/apps/admin/push/custom_events"
)
func Register(c *gin.Context) {
// ... 注册成功逻辑 ...
// 异步触发通知推送事件
custom_events.TriggerNewUserRegisteredEvent(ctx, user)
func Register() {
push.RegisterBuiltInEvent(NewUserRegistered)
listener.OnUserRegistered(handleUserRegistered)
}
```
### 步骤 4：在主路由器或初始化模块进行匿名导入以确保注册
由于事件是在 `custom_events` 的 `init()` 中注册到 `push` 包的，所以应用程序的执行路径（例如 [router.go](file:///Users/ryan/DEV/Go/Wavelet/internal/router/router.go)）必须匿名导入 `custom_events` 包，以确保其在程序启动时被加载和初始化。
**禁止**在 `custom_events` 或 `router` 中使用 `init()` 注册；**禁止**在 `router.go` 空白导入 `custom_events`。
### 步骤 3：在业务代码中发射域事件（不 import push）
在业务逻辑完成处（如 `internal/apps/user/routers.go`）仅 import `internal/listener` 并发射事件：
```go
import (
_ "github.com/Rain-kl/Wavelet/internal/apps/admin/push/custom_events"
)
import "github.com/Rain-kl/Wavelet/internal/listener"
func Register(c *gin.Context) {
// ... 注册成功逻辑 ...
listener.EmitUserRegistered(ctx, user)
}
```
当程序启动后，系统在初始化阶段的 `SyncEvents` 流程中会自动将新声明的 `user_registered` 事件元数据插入数据库表 `w_push_events` 中。此后，管理员即可直接在管理端前端界面上为该事件配置推送渠道。
### 步骤 4：在 bootstrap / cmd 入口显式装配
新增事件后，确保 `custom_events.Register()` 已被 `bootstrap.RegisterPushDomainEvents()` 调用，且 API/`all` 进程在 `bootstrap.Init` 之前完成注册：
| 进程 | cmd 入口调用 |
| :--- | :--- |
| `api` | `bootstrap.RegisterAPI()` → `bootstrap.Init(ctx, Options{API: true})` |
| `all` | `bootstrap.RegisterAll()` → `bootstrap.Init(ctx, Options{API: true})` |
| `worker` / `scheduler` | 不注册 push 域事件；仅 `bootstrap.Init` + 各自 `RegisterWorker`/`RegisterScheduler` |
`Init` 中的 `SyncEvents` 会将 `user_registered` 元数据同步到 `w_push_events`，管理员即可在前端配置推送渠道。
### 步骤 5：编写集成测试
在 `custom_events/` 或 `listener/` 包内添加测试，验证 `Emit*` → handler → `DefaultTrigger.Trigger` 全链路。测试 setup 须显式调用 `custom_events.Register()`（或 `bootstrap.RegisterPushDomainEvents()`）和 `push.SyncEvents`，参考 [admin_login_test.go](file:///Users/ryan/DEV/Go/Wavelet/internal/apps/admin/push/custom_events/admin_login_test.go)。
---
@@ -159,3 +160,12 @@ import (
### 1. 禁止绕过统一触发器 (Always Use EventTrigger)
- 所有推送请求必须经过 `EventTrigger.Trigger`，以确保进行“事件是否启用”、“目标渠道过滤”、“全局推送配置读取”及“发送日志审计”等流程。
### 2. 禁止业务模块直接依赖 push (Decouple via listener)
- `oauth`、`user` 等核心域 **不得** `import` `internal/apps/admin/push` 或 `custom_events`。
- 跨模块通知必须通过 `internal/listener` 发射域事件；push 在 `custom_events.Register()` 中订阅。
### 3. 禁止 init() 与 router 副作用注册 (Explicit Bootstrap)
- 不得在 `init()` 中调用 `RegisterBuiltInEvent` 或订阅 listener。
- 不得在 `router.go` 空白导入 `custom_events` 触发注册。
- 统一在 `internal/bootstrap` + `internal/cmd` 入口显式装配。