From a869540d9c63165b3fdadb4b4ab18d418900c854 Mon Sep 17 00:00:00 2001
From: Rogee <rogee@ipao.vip>
Date: Mon, 22 Dec 2025 21:54:39 +0800
Subject: [PATCH] update llm.txt

---
 backend/llm.txt | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/backend/llm.txt b/backend/llm.txt
index 5349200..e872473 100644
--- a/backend/llm.txt
+++ b/backend/llm.txt
@@ -192,6 +192,36 @@ In this case:
 - Add a short Chinese comment explaining why, and that `atomctl gen model` should be run when DB is reachable.
 - Avoid spreading this pattern: keep it localized to one function.
 
+---
+
+## Async Jobs（River）
+
+本项目使用 River（`github.com/riverqueue/river`）作为异步任务系统，并通过 `atomctl new job <name> [--cron]` 生成 `backend/app/jobs/*.go`。
+
+- MUST：任务入队（调用 `job.Add(...)` / `client.Insert(...)`）只能在 `service` / `controller` / `event` 层编写；其它位置（例如 `middlewares` / `database` / `models` / `providers` / `jobs` 的 worker 实现等）禁止写入任务，避免耦合与隐式副作用。
+
+### Job（一次性任务）
+
+- `Kind() string`：任务类型标识（job kind）；改名会导致“新旧任务类型不一致”。
+- `InsertOpts() river.InsertOpts`：默认入队参数（队列、优先级、最大重试、唯一任务策略等）。
+- `UniqueID() string`（项目约定）：周期任务 handle 的稳定 key；通常 `return Kind()`。
+
+### Worker（执行器）
+
+- `Work(ctx, job)`：执行入口；返回 `nil` 成功；返回 `error` 失败并按 River 策略重试。
+- `river.JobSnooze(d)`：延后再跑一次，且 **不递增 attempt**；适合等待外部依赖就绪/限流等。
+- `river.JobCancel(err)`：永久取消并记录原因；适合业务上永远不可能成功的情况（参数非法/语义过期等）。
+- `NextRetry(job)`（可选）：自定义该任务类型的重试节奏。
+
+### CronJob（周期任务）
+
+- `Prepare() error`：注册周期任务前做初始化/校验（避免重活/长阻塞）。
+- `Args() []contracts.CronJobArg`：声明周期任务（间隔、是否启动即跑、入队的 JobArgs）。
+
+### 业务侧如何入队
+
+- 在业务结构体中注入 `*job.Job`（见 `backend/providers/job`），然后调用 `obj.job.Add(jobs.XXXJob{...})` 入队。
+
 ### 2.2 Enum strategy
 
 - DO NOT use native DB ENUM.