OpenFlare/AGENTS.md

AGENTS.md — Wavelet AI 助手工作操作手册

本文件面向 AI 开发助手，定义其职责与操作规范。

Git 提交规范

遵循 Conventional Commits：<type>(<scope>): <subject>（例：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/<feature>/：特定业务域的 UI 组件（如 auth/、home/）。
• frontend/lib/services/：基于 BaseService 继承的类型化前端 API 服务。
• frontend/i18n/：前端国际化配置（locale 解析、cookie、request config）。
• frontend/messages/：i18n 文案目录（zh-CN.json / en.json）。
• 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），禁止包裹背景小卡片或装饰边框。
  • 标题文字统一使用 <h1 className="text-2xl font-semibold tracking-tight">。
• 组件拆分与维护：
  • 物理路由页面 page.tsx 仅维护高级骨架与布局。
  • 单文件超过 600 行或含多 Tab/大复杂区块时，必须按就近原则拆分为子组件存放在路由同级的 components/ 局部目录中（参考 /admin/database 的模块化拆分结构）。
• 样式与服务：
  • 优先使用 shadcn/ui 的 variant 和全局 CSS 变量，不要在业务代码中硬编码颜色/背景。
  • 前端请求统一在 frontend/lib/services/<name>/ 中继承 BaseService 编写并在 index.ts 注册。
• 国际化 (i18n)：
  • 使用 next-intl（无 URL locale 前缀 / non-routing provider 模式），兼容 NEXT_STANDALONE_EXPORT 静态导出。
  • 支持语言：zh-CN、en；默认 zh-CN。
  • 解析优先级：cookie NEXT_LOCALE（用户显式选择）→ 浏览器语言 → 默认 zh-CN。
  • 文案统一放在 frontend/messages/{locale}.json，按命名空间嵌套（common / layout / auth / settings / 业务域）。
  • 组件内用户可见文案必须通过 useTranslations() / getTranslations() 读取；禁止新增中英硬编码 UI 字符串（后端返回的 error_msg、日志、调试信息除外）。
  • key 使用 camelCase 分层（如 auth.login.submit）；完整短语作为 value，禁止在组件内拼接句子。
  • 新增或修改文案时必须同步更新 zh-CN.json 与 en.json，保持 key 树一致。
  • 语言选项展示用自称：中文 / English（不随当前 UI 语言翻译）。
  • 日期/数字格式化使用 locale 感知 helper（如 formatDateTime），禁止写死 'zh-CN' / date-fns 的 zhCN（除非该路径尚未迁移且不在本次改动范围）。
  • 设计说明见 docs/superpowers/specs/2026-07-24-frontend-i18n-design.md。