# AGENTS.md — Wavelet AI 助手工作操作手册 本文件面向 AI 开发助手，定义其职责与操作规范。 ## Git 提交规范 遵循 Conventional Commits：`(): `（例：`feat(auth): support email login`）。 ## 务必阅读匹配的 Skill | Skill | 何时使用 | | :--- | :--- | | `new-api` | 添加或修改自定义业务 API、Handler、服务层逻辑、自定义路由注册 | | `new-async-task` | 添加或修改 Asynq 任务、定时任务、TaskHandler、任务元数据 | | `new-setting` | 添加或修改系统/业务/公开设置、`/admin/system` 参数或 `/admin/settings` 图形化设置 | | `database-migration` | 数据库表结构变更、goose SQL 迁移（PG/SQLite/ClickHouse）、seed 数据 | | `clickhouse-batchwriter` | ClickHouse 批量写入、`internal/infra/persistence/batchwriter` 接入、分析表异步 flush、背压与写入路径改造 | | `file-upload` | 业务上传文件、Worker 程序化摄取、`upload.Ingest` 策略选型、文件访问与 `w_uploads` / 统计排查 | | `cache-framework` | 新增或修改业务缓存（RAM/Redis/DB 三层读路径）、缓存失效、多节点 pub/sub 同步、评估高频读是否应接入缓存 | | `push-notification` | 系统通知推送事件、统一触发器投递、带消息推送的业务功能 | | `release-guide` | 根据自上一正式版本 Tag 以来的提交整理 Version Bump 提交信息以触发双语 Release | | `shadcn` | 添加、修改或组合 shadcn/ui 组件 | ## 严格遵循事项 (Guardrails) - 切勿删除 `frontend/node_modules`。 - 保持 `internal/util/` 绝对纯净，禁止导入 Gin、GORM、sessions 等 Web/数据库框架包。 - 测试用例禁止硬编码相对路径创建临时目录，统一使用 Go 内置 `t.TempDir()`。 - 所有 HTTP 路由仅在 `internal/router/router.go` 中作为高层分发注册。 - 修改 API Handler 后运行 `make swagger`，完成代码开发后必须依次运行 `make code-check` 与 `make format`。 - 业务模块必须复用平台缓存/文件服务：文件摄取统一用 `upload.Ingest`，删除用 `upload.Remove`/`upload.RemoveOwned`；禁止直接写 `w_uploads` 或绕过 upload 域直接操作 `infra/objectstore`。 - 禁止在 `init()` 中注册跨模块集成（任务 Handler、推送事件、域事件监听器等），统一在 `internal/platform/bootstrap` 显式装配并在 `internal/cmd` 入口调用。 - 核心业务模块（`oauth`、`user`）禁止直接 import `push` 或 `custom_events` 触发通知，须通过 `internal/listener` 发射域事件。 - API 错误响应必须通过 `response.Abort*` 中断请求，由 `ErrorHandlerMiddleware` 统一写出 JSON 并记录 Trace；禁止在 Handler/中间件中直接 `c.JSON(status, response.Err(...))` 或 `200` 返回 `error_msg`。 ## 技术栈与项目目录结构 ### 技术栈 - **后端**：Go 1.25+、Gin、GORM、PostgreSQL、ClickHouse、Redis、Asynq、Cobra、Viper、Swaggo、OpenTelemetry、Zap、AWS SDK v2。 - **前端**：Next.js (App Router)、TypeScript、Tailwind CSS、pnpm、shadcn/ui。 ### 顶层目录 - `main.go`：程序入口，委派给 `internal/cmd`。 - `config.example.yaml` / `config.yaml`：配置文件模板与本地配置。 - `docker/`：容器化部署 Dockerfile。 - `docs/`：自动生成的 Swagger 文档（请勿手动编辑）。 - `frontend/`：Next.js 前端应用。 - `internal/`：后端核心私有代码。 - `pkg/`：公共通用 Go 工具库（不包含具体业务）。 - `scripts/`：本地开发与 CI 脚本。 - `support-files/`：部署与 SQL/环境辅助文件。 - `bin/` / `data/` / `uploads/`：编译二进制产物、本地数据文件与上传存储目录。 ### 后端目录 (`internal/`) - `internal/cmd/`：Cobra CLI 命令入口（API/Worker/Scheduler）。 - `internal/platform/`：进程与跨模块装配。 - `bootstrap/`：应用装配根，集中注册 Task、推送订阅、域事件监听器及进程级初始化。 - `lifecycle/`：进程 shutdown hook。 - `internal/infra/`：接入外部世界与 Wavelet 运行时配置的实现（非业务用例）。 - `config/`：Viper 启动配置加载与映射结构体。 - `persistence/`：PostgreSQL/Redis/ClickHouse 连接池、goose 迁移（`migrator/goose/`）、batchwriter、idgen（Go 包名仍为 `db`）。 - `objectstore/`：对象存储多后端适配（Local/S3/R2/OSS/WebDAV；原 `internal/storage`）。 - `diskcache/`：读 system_config 的磁盘缓存包装（引擎在 `pkg/cache/disk`）。 - `task/`：Asynq 运行时、worker/scheduler、任务元数据。 - `internal/shared/`：跨层无 IO 约定（`response` envelope、通用错误文案等）。 - `internal/router/`：全局唯一 HTTP 路由注册点。 - `internal/apps/`：按功能（Feature-based）划分模块的 Handler 与业务逻辑（管理端位于 `admin/`）。 - `internal/apps/upload/`：文件上传服务、访问控制与 WebP 压缩。 - `internal/model/`：GORM 数据模型定义与模型层方法。 - `internal/repository/`：数据访问（过渡期包级函数；后续接口化）。 - `internal/util/`：纯底层无框架依赖工具函数。 - `internal/listener/`：域事件分发层（解耦业务域与运维/推送模块；过渡）。 - `internal/testhelper/`：后端测试共享 Helper。 - `internal/buildinfo/`：编译与构建元数据。 新增技术能力默认放进 `infra/` 或 `platform/` 子树，禁止再在 `internal/` 顶层平铺杂散包。 ### 公共底层包 (`pkg/`) - `pkg/cache/disk/`：纯底层磁盘缓存引擎。 - `pkg/cap/`：通用验证码库。 - `pkg/httppool/`：带 OTel 链路追踪的共享 HTTP 客户端连接池。 - `pkg/logger/`：Zap / OTel 结构化日志工具。 - `pkg/push/`：推送渠道 SDK 集成（Lark / Telegram / Email）。 - `pkg/mail/`：邮件发送客户端。 - `pkg/trace/`：OpenTelemetry 链路配置。 - `pkg/util/`：无副作用系统工具（Crypto / Password / UUID 等）。 ### 前端目录 (`frontend/`) - `frontend/app/`：Next.js App Router 路由与页面。 - `frontend/components/ui/`：shadcn/ui 基础通用组件。 - `frontend/components/common/`：跨页面的业务通用组件。 - `frontend/components/layout/`：Header / Sidebar / Footer 页面框架组件。 - `frontend/components//`：特定业务域的 UI 组件（如 `auth/`、`home/`）。 - `frontend/lib/services/`：基于 `BaseService` 继承的类型化前端 API 服务。 - `frontend/contexts/` / `hooks/` / `lib/` / `types/` / `public/`：全局状态、Hook、客户端工具、TS 类型定义与静态资源。 ## 后端开发规范 ### API 响应规范 - **统一信封**：`{ "error_msg": "", "data": ... }` - **成功**：HTTP 200，写出 `c.JSON(http.StatusOK, response.OK(data))` 或 `response.OKNil()`。 - **失败**：使用 `internal/shared/response` 的 `Abort*` 系列函数（如 `AbortBadRequest`、`AbortUnauthorized`、`AbortNotFound`、`AbortInternal`）中断请求。 - **错误文案**：使用模块内 `errs.go` 中的 camelCase 字符串常量（如 `errBindParamsFailed`），禁止暴露底层数据库/系统错误细节给客户端。 - **Logics 分工**：`logics.go` 只接受 `context.Context`，返回 `(result, error)`，严禁依赖 `*gin.Context` 或调用 `c.JSON`/`Abort*`。 - **错误日志**：底层错误在 Handler/Logic 边界用 `pkg/logger` 打印日志，禁止使用 `_ = ...` 静默吞掉关键错误。 ### 数据库操作 - 管理员代码推荐使用 `db.DB(ctx)`（`internal/infra/persistence`，包名 `db`）保证 Trace 链路透传。 - 禁止在 Handler 写复杂 SQL；迁移文件位于 `internal/infra/persistence/migrator/goose/`（禁止 GORM AutoMigrate）。 - 不创建物理外键（显式建索引）；Go 模型零值需与数据库默认值匹配。 ## 前端开发规范 - 新特性开发前参考 Next.js 文档与 `frontend/app/(main)/admin/demo` 示例代码。 - **页面容器与标题栏**： - 页面根容器统一使用全宽 `w-full`，最外层统一用 `py-6` 或 `py-6 px-1` 对齐边距。 - 标题容器统一 `flex items-center gap-2`（带操作按钮用 `justify-between`）。 - 图标直接使用 Lucide 组件（`size-5 text-primary`），禁止包裹背景小卡片或装饰边框。 - 标题文字统一使用 `

`。 - **组件拆分与维护**： - 物理路由页面 `page.tsx` 仅维护高级骨架与布局。 - 单文件超过 600 行或含多 Tab/大复杂区块时，必须按就近原则拆分为子组件存放在路由同级的 `components/` 局部目录中（参考 `/admin/database` 的模块化拆分结构）。 - **样式与服务**： - 优先使用 shadcn/ui 的 `variant` 和全局 CSS 变量，不要在业务代码中硬编码颜色/背景。 - 前端请求统一在 `frontend/lib/services//` 中继承 `BaseService` 编写并在 `index.ts` 注册。