tcjlj/OpenFlare

Fork 0

mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-09-29 05:56:38 +08:00

Files

T

ryan e3ef6c9d27 修改路径

2026-06-08 20:38:17 +08:00

25 KiB

Raw Blame History

项目开发规范

本文档面向 AI 代理（Agent）和开发者，描述项目的目录结构、模块职责与开发规范。

一、技术栈

后端

技术	用途
Go (1.25+)	主语言
Gin	HTTP 框架
GORM	ORM，主库 PostgreSQL，可选 ClickHouse
Redis	缓存 / Session / 队列
Asynq	异步任务队列（基于 Redis）
Cobra + Viper	CLI 入口 + 配置加载
Swaggo	Swagger 文档生成
OpenTelemetry	链路追踪
Zap	结构化日志
AWS SDK v2	S3 兼容文件存储
Snowflake	分布式 ID 生成

前端

技术	用途
Next.js (App Router)	前端框架
TypeScript	主语言
Tailwind CSS	样式
pnpm	包管理
shadcn/ui	组件库

二、顶层目录结构

以下是项目的顶层目录结构及其职责, 如果有新增目录或文件，请务必在此处同步更新：

wavelet/                           # 项目根目录（模块名: github.com/Rain-kl/Wavelet）
├── main.go                        # 程序入口，调用 internal/cmd
├── go.mod / go.sum                # Go 模块依赖
├── config.yaml                    # 运行时配置（不提交到 Git）
├── config.example.yaml            # 配置模板（需提交）
├── DEPLOYMENT_zh.md               # 部署说明文档（中文版）
├── Makefile                       # 常用命令（swagger/tidy/license）
├── docker/                        # Docker 镜像构建文件（集成/前端/后端）
│   ├── Dockerfile                 # 标准集成镜像（前端静态导出嵌入后端）
│   ├── Dockerfile.frontend        # 仅前端镜像（Next.js）
│   └── Dockerfile.backend         # 仅后端镜像（Go API/Worker/Scheduler）
├── docker-compose.yml             # 本地依赖服务（PostgreSQL / Redis / ClickHouse）
├── .editorconfig                  # 编辑器格式规范
├── .gitignore
├── docs/                          # Swagger 自动生成文档（不要手动编辑）
├── frontend/                      # Next.js 前端项目
├── internal/                      # 后端核心代码（Go private，不对外暴露）
├── scripts/                       # CI/本地工具脚本
└── support-files/                 # 辅助文件（如 nginx 配置等）

三、后端 `internal/` 目录结构

以下是 internal/ 目录的结构及其职责, 如果有新增目录或文件，请务必在此处同步更新：

internal/
├── cmd/                           # CLI 命令入口（Cobra）
│   ├── root.go                    # 根命令，加载配置、初始化依赖
│   ├── api.go                     # 启动 HTTP API 服务器子命令
│   ├── scheduler.go               # 启动定时任务调度器子命令
│   └── worker.go                  # 启动 Asynq Worker 子命令
│
├── config/                        # 配置加载与结构定义
│   ├── model.go                   # 所有配置结构体（AppConfig / DB / Redis 等）
│   └── config.go                  # Viper 加载逻辑，暴露全局 config.Config
│
├── router/                        # HTTP 路由注册（唯一路由注册点）
│   ├── router.go                  # 路由总入口，注册所有分组路由、中间件、启动 HTTP Server
│   └── middlewares.go             # 全局中间件（如请求日志）
│
├── apps/                          # 业务功能模块（按功能域划分）
│   ├── oauth/                     # OAuth / OIDC 登录、会话、用户信息
│   ├── user/                      # 用户密码登录、注册、登出
│   ├── upload/                    # 文件上传、文件服务、清理任务
│   ├── health/                    # 健康检查端点
│   ├── config/                    # 公开配置接口（前端读取）
│   └── admin/                     # 管理后台功能（需 Admin 权限）
│       ├── middlewares.go          # Admin 鉴权中间件
│       ├── errs.go                 # Admin 错误常量
│       ├── auth_source/           # 认证源管理（CRUD）
│       ├── system_config/         # 系统配置管理（CRUD）
│       ├── task/                  # 任务手动调度接口
│       └── user/                  # 用户管理（列表、状态）
│
├── model/                         # 数据模型（GORM 实体 + 业务方法）
│   ├── users.go                   # User 实体、OAuthUserInfo、查询/更新方法
│   ├── auth_source.go             # AuthSource 实体（OAuth 接入源）
│   ├── system_configs.go          # SystemConfig 实体（KV 系统配置）
│   ├── uploads.go                 # Upload 实体（上传文件记录）
│   └── task_execution.go          # TaskExecution 实体（异步任务执行记录 + CRUD）
│
├── db/                            # 数据库连接与基础设施
│   ├── postgres.go                # PostgreSQL 初始化、读写分离、GORM 配置
│   ├── redis.go                   # Redis 初始化（单机/哨兵/集群）
│   ├── clickhouse.go              # ClickHouse 初始化（可选）
│   ├── postgres_logger.go         # 自定义 GORM 日志（对接 Zap）
│   ├── idgen/                     # Snowflake 分布式 ID 生成器
│   └── migrator/                  # 数据库迁移（AutoMigrate）
│
├── storage/                       # 文件存储抽象层
│   ├── s3.go                      # S3 兼容存储（上传/下载/URL 生成）
│   ├── cache.go                   # 本地磁盘缓存（S3 内容缓存）
│   └── errs.go                    # 存储层错误常量
│
├── task/                          # 异步任务定义与调度
│   ├── constants.go               # 任务类型名称常量（TaskType）、队列名、TaskMeta（含 Retryable）
│   ├── handler.go                 # TaskHandler 接口定义 + TaskResult 结构体
│   ├── executor.go                # 核心运行机制：RegisterHandler / DispatchTask / ProcessTask / RetryTask / AppendLog
│   ├── utils.go                   # 任务工具函数（RedisOpt、AsynqClient）
│   ├── scheduler/                 # Asynq 定时任务调度器（Cron 注册）
│   └── worker/                    # Asynq Worker 服务端（任务处理器注册）
│       ├── worker.go              # StartWorker 入口，注册 Handler
│       └── middlewares.go         # Worker 中间件
│
├── service/                       # 复杂业务逻辑服务层（当前占位，待填充）
│
├── common/                        # 跨模块共享代码
│   ├── constants.go               # 全局常量（错误消息字符串等）
│   ├── errs.go                    # 通用错误定义
│   ├── bind/                      # 请求参数绑定封装（统一处理错误响应）
│   └── response/                  # 统一 HTTP 响应格式封装
│
├── util/                          # 无业务依赖的纯工具函数
│   ├── crypto.go                  # 加密/签名工具
│   ├── password.go                # 密码 Hash（bcrypt）
│   ├── http_clients.go            # HTTP 客户端封装
│   ├── context.go                 # Context 存取工具
│   ├── response.go                # ResponseAny 等响应结构体
│   ├── session.go                 # Session 选项构建
│   ├── uuid.go                    # UUID / 唯一 ID 生成
│   ├── strings.go                 # 字符串工具
│   ├── validate.go                # 参数校验工具
│   └── custom_types.go            # 自定义类型
│
├── logger/                        # 日志封装（基于 Zap + OTel）
│   ├── logger.go                  # 全局 Logger 初始化
│   └── utils.go                   # InfoF / WarnF / ErrorF 快捷函数
│
├── listener/                      # 事件监听器（Webhook / 消息消费）
│
└── otel_trace/                    # OpenTelemetry 链路追踪封装
    └── ...                        # Span 创建、Exporter 配置

四、`apps/` 模块内部文件规范

每个业务模块（apps/<module>/）内部按照以下约定组织文件：

文件名	职责
`routers.go`	HTTP Handler 函数（业务逻辑入口，对应 Controller 层）
`controllers.go`	可选，当 Handler 较多时拆分（同 `routers.go` 职责）
`middlewares.go`	本模块专属中间件（如 `LoginRequired`、`LoginAdminRequired`）
`errs.go`	本模块专属错误消息字符串常量（`const`）
`constants.go`	本模块专属业务常量（非错误）

规则：

路由不在模块内部注册，统一在 internal/router/router.go 中注册。

errs.go 只定义字符串常量，不定义 error 类型值，错误通过 response.RespondFailure(c, errMsg) 输出。

`admin/` 子模块结构示例

apps/admin/
├── middlewares.go          # LoginAdminRequired 中间件
├── errs.go                 # admin 级别错误常量
├── auth_source/            # 认证源 CRUD
│   └── routers.go
├── system_config/          # 系统 KV 配置 CRUD
│   └── routers.go
├── task/                   # 任务调度接口
│   └── routers.go
├── user/                   # 用户管理
│   ├── routers.go
│   └── errs.go
└── user_pay_config/        # 用户支付配置
    └── routers.go

五、前端 `frontend/` 目录结构

以下是前端 frontend/ 目录的结构, 如果需要调整请在此处同步更改：

frontend/
├── app/                           # Next.js App Router 页面目录
│   ├── layout.tsx                 # 根布局（全局 Provider、字体、meta）
│   ├── globals.css                # 全局样式
│   ├── page.tsx                   # 首页重定向
│   ├── (auth)/                    # 认证相关页面组（登录/注册/OAuth 回调）
│   ├── (main)/                    # 主应用页面组（用户界面）
│   └── (docs)/                    # 文档类页面组
│
├── components/                    # 可复用 React 组件
│   ├── ui/                        # shadcn/ui 基础组件（Button/Input/Dialog 等）
│   ├── common/                    # 通用业务组件（跨页面复用），详见下方说明
│   ├── layout/                    # 布局组件（Header / Sidebar / Footer）
│   ├── auth/                      # 认证相关组件
│   ├── home/                      # 首页专属组件
│   ├── animate-ui/                # 动画 UI 组件
│   └── providers/                 # Context Provider 组件
│
├── contexts/                      # React Context（全局状态）
├── hooks/                         # 自定义 React Hooks
├── lib/                           # 前端工具函数、API 客户端封装
├── types/                         # TypeScript 类型定义
├── public/                        # 静态资源
├── proxy.ts                       # 开发环境代理配置
├── next.config.ts                 # Next.js 配置
├── package.json
├── tsconfig.json
├── .env                           # 环境变量（不提交）
└── .env.example                   # 环境变量模板（需提交）

5.1 前端 `components/common/` 通用业务组件详解

common/ 目录存放跨页面复用的业务组件，按功能域分为五个子目录。以下是每个文件的职责说明：

components/common/
├── admin/                          # 管理员后台组件
│   ├── tasks.tsx                   # TaskManager — 异步任务调度管理页面，展示所有可用任务类型，
│   │                               #   支持通过弹窗配置参数后立即下发任务到后台队列执行
│   ├── task-executions.tsx         # TaskExecutionsManager — 任务日志页面，展示异步任务执行记录，
│   │                               #   支持状态/类型筛选、分页、详情抽屉查看完整日志与失败任务重试
│   ├── system.tsx                  # SystemConfigs — 系统 KV 配置管理页面，以表格展示系统/业务两类
│   │                               #   配置项，支持在线编辑（布尔类型自动渲染为 Switch）并保存/删除
│   └── users.tsx                   # UsersManager — 用户管理页面，提供分页、搜索、筛选的用户列表表格，
│                                   #   支持在侧边抽屉查看用户详情，以及启用/禁用（封禁/解封）切换
│
├── docs/                           # 文档页面组件,包括法律文档（隐私政策/服务条款）和接口文档
│
├── general/                        # 通用框架组件
│   ├── manage-pannel.tsx           # ManagePage（泛型）— 通用管理页面框架，封装"列表 + 详情面板"布局，
│   │                               #   包含数据加载/错误/空状态处理、表格渲染、选中/悬停交互、
│   │                               #   编辑/保存/删除逻辑；ManageDetailPanel 为带保存按钮的详情面板；
│   │                               #   ManageTable 为配置驱动型表格组件
│   └── password-dialog.tsx         # PasswordDialog — 密码确认弹窗，用于敏感操作前的二次身份验证，
│                                   #   包含 6 位 OTP 输入框，支持 Enter 快捷确认，带加载状态显示
│
├── home/                           # 首页组件
│   └── home-main.tsx               # HomeMain — 系统首页主内容，展示当前用户的快捷导航卡片
│                                   #   （个人资料、开发接口文档、使用文档），管理员额外显示后台管理入口
│
└── settings/                       # 设置页面组件
    ├── access-token.tsx            # AccessTokenMain — 个人访问令牌管理页面，展示用户 API 密钥列表，
    │                               #   支持创建（仅展示一次明文）、轮换、撤销/删除令牌
    ├── appearance.tsx              # AppearanceMain — 外观设置页面，分为主题模式选择
    │                               #   （明亮/黑暗/自动）和界面配色方案（可视化色卡网格切换）
    ├── auth-source-modal.tsx       # AuthSourceModal — OIDC 认证源新增/编辑弹窗，包含标识符、
    │                               #   Client ID/Secret、Discovery URL、Scopes、图标等表单字段
    ├── notifications.tsx           # NotificationsMain — 通知设置页面，控制顶部导航栏
    │                               #   是否显示通知铃铛图标，通过 Context 持久化偏好
    ├── profile.tsx                 # ProfileMain — 个人资料页面，展示用户基本信息，提供第三方
    │                               #   账号绑定管理（查看已绑定 OIDC 账号、解除绑定、绑定新认证源）
    └── security.tsx                # SecurityMain — 系统安全设置页面（管理员专属），包含系统登录与
                                    #   注册控制（密码登录/注册/密码注册/OIDC 登录四个开关）、
                                    #   认证源管理（新增、编辑、启用/禁用、删除 OIDC 认证源）

六、开发规范

6.1 命名规范

对象	规范	示例
Go 包名	小写，下划线分词（单词）	`auth_source`、`system_config`
Go 文件名	小写，下划线分词	`routers.go`、`postgres_logger.go`
Go 导出函数	PascalCase	`ListUsers`、`StartWorker`
Go 未导出函数	camelCase	`buildQueuesFromConfig`
Go 结构体请求/响应	camelCase + 后缀	`listUsersRequest`、`listUsersResponse`
错误常量	camelCase 字符串 `const`	`const userNotFound = "用户不存在"`
任务类型常量	全大写蛇形	`CleanupUnusedUploadsTask`
配置 Key	全小写蛇形（YAML）	`session_cookie_name`、`max_idle_conn`

6.2 HTTP Handler 规范

// Handler 函数命名：动词 + 名词（PascalCase）
func ListUsers(c *gin.Context) {
    // 1. 参数绑定（使用 ShouldBindQuery / ShouldBindJSON）
    var req listUsersRequest
    if err := c.ShouldBindQuery(&req); err != nil {
        c.JSON(http.StatusBadRequest, util.Err(err.Error()))
        return
    }

    // 2. 业务逻辑

    // 3. 统一响应
    c.JSON(http.StatusOK, util.OK(data))
}

响应格式约定：

成功：util.OK(data) 或 util.OKNil()
失败：util.Err(msg) + 对应 HTTP 状态码
通过 response.RespondSuccess / RespondFailure 也可（两套工具共存）

6.4 错误处理规范

模块内错误消息：定义在本模块 errs.go 中，使用 const 字符串。
跨模块错误消息：定义在 internal/common/errs.go 或 common/constants.go。
数据库错误：直接 err.Error() 返回给响应（开发阶段），生产环境应屏蔽详情。
gorm.ErrRecordNotFound：显式判断，返回 404。

6.5 中间件使用规范

中间件	位置	作用
`gin.Recovery()`	全局	Panic 恢复
`otelgin.Middleware()`	全局	OTel 链路追踪
`loggerMiddleware()`	全局	请求日志
`sessions.Sessions()`	全局	Session 注入
`oauth.LoginRequired()`	路由组	登录校验
`admin.LoginAdminRequired()`	Admin 路由组	管理员校验

6.6 配置访问规范

所有配置通过 config.Config.<Section>.<Field> 访问（全局单例）。
不允许在业务代码中使用 os.Getenv() 读取配置，统一通过 Viper 加载。
新增配置项：先在 config.example.yaml 添加注释模板，再在 internal/config/model.go 添加结构体字段。

6.7 数据库访问规范

直接使用 GORM：model.DB.Where(...).Find(&result)（适合简单查询）。
通过 db.DB(ctx) 获取带链路追踪的 DB 实例（Admin 模块推荐）。
禁止在 Handler 层直接写复杂 SQL，应封装到 model/ 层方法或 service/ 层。
数据库迁移使用 db/migrator/ 中的 AutoMigrate，不允许手动执行 DDL。

6.8 异步任务规范

定义任务：

在 internal/task/constants.go 中定义任务类型常量。
实现 Handler 函数（放在对应 apps/ 模块的 tasks.go 文件中）。
在 internal/task/worker/worker.go 中注册 Handler：mux.HandleFunc(task.XxxTask, handler)。
调度：在 internal/task/scheduler/ 中按 Cron 表达式调度，或通过 Admin API 手动触发。

队列优先级（从高到低）：webhook > whitelist_only > default

6.9 前端组件样式规范

基础组件必须遵循系统的色彩主题系统。 所有基于 shadcn/ui 的基础组件（Button、Dialog、Input 等）应使用组件内置的 variant 属性来控制样式，禁止通过 className 手写颜色或背景等样式。

错误示例（禁止）：

// ❌ 禁止通过 className 手写颜色、背景、阴影等样式
<Button
  type="button"
  size="sm"
  className="bg-indigo-600 hover:bg-indigo-700 text-white shadow-md shadow-indigo-600/10 transition-colors"
>
  <Plus className="mr-1.5 size-3.5" />
  新增认证源
</Button>

正确示例：

// ✅ 使用 variant 属性，让组件遵循系统主题
<Button
  type="button"
  size="sm"
  variant="secondary"
>
  <Plus className="mr-1.5 size-3.5" />
  新增认证源
</Button>

原则：组件的视觉表现由 shadcn/ui 的 variant 系统和全局 CSS 变量统一控制，保持应用内所有页面风格一致。如现有 variant 无法满足需求，应扩展 shadcn/ui 组件的 variant 定义，而非在业务代码中硬编码颜色值。

6.10 严格禁止事项

禁止行为	说明
禁止删除 `node_modules` 目录	`node_modules` 为前端依赖安装目录，删除会导致项目无法运行。如需重新安装依赖，使用 `pnpm install` 覆盖更新即可，严禁执行 `rm -rf node_modules`。
`internal/util/` 下禁止引用框架包	`util/` 及其子包（如 `util/cap`）定位为纯工具层，不得 `import` 任何 HTTP / ORM / 框架包，包括但不限于 `github.com/gin-gonic/gin`、`gorm.io/gorm`、`github.com/gin-contrib/sessions`。违反此约束会导致工具层与框架产生耦合，无法独立测试。详见 6.11 的建议方案。

6.11 `util/` 包依赖约束与建议方案

约束范围

internal/util/ 及其全部子包（如 util/cap、util/crypto 等）只允许引用：

Go 标准库（context、crypto、encoding、net/http 原生包等）
项目内同级别的纯工具包（internal/config、internal/db、internal/model 等无框架依赖的包）
与框架无关的第三方库（如 github.com/redis/go-redis、github.com/shopspring/decimal 等）

严禁引用：github.com/gin-gonic/gin、gorm.io/gorm、github.com/gin-contrib/sessions 及任何 HTTP 框架 / Web 中间件相关包。

常见误区与建议方案

误区	建议方案
在 `util/` 中写 `gin.HandlerFunc` 形式的中间件	将中间件移至对应的 `apps/<module>/middleware.go`，通过函数参数接收 `util/` 层的核心对象（如 `*cap.Manager`）
在 `util/` 中通过 `*gin.Context` 写响应	只在 `util/` 中计算/校验逻辑并返回 `(result, error)`，由 `apps/` 层的 Handler 负责调用 `c.AbortWithStatusJSON` 写响应
在 `util/` 中使用 `gorm.DB` 直接查询	将数据库查询封装在 `internal/model/` 层方法中，`util/` 只接收已查出的数据结构

正确示例

// ✅ internal/util/cap/manager.go — 纯逻辑，无框架依赖
func (m *Manager) VerifyToken(ctx context.Context, token, scope string) (bool, error) {
    // 只依赖 context、标准库、redis client
    ...
}

// ✅ internal/apps/cap/middleware.go — 框架胶水层，持有 gin 依赖
func VerifyMiddleware(mgr *caputil.Manager, scope string, enabledFunc func() bool) gin.HandlerFunc {
    return func(c *gin.Context) {
        valid, err := mgr.VerifyToken(c.Request.Context(), token, scope) // 调用纯逻辑
        if err != nil || !valid {
            c.AbortWithStatusJSON(http.StatusUnauthorized, util.Err("验证码校验失败"))
            return
        }
        c.Next()
    }
}

错误示例（禁止）

// ❌ internal/util/cap/middleware.go — util/ 层不应出现 gin
import "github.com/gin-gonic/gin"

func (m *Manager) VerifyMiddleware(...) gin.HandlerFunc { ... }

七、新增功能开发流程

新增 异步任务 ：使用项目专属 SKILL: new-async-task 进行开发

以新增 管理员功能模块 为例：

1. 在 internal/model/ 中定义/扩展数据模型
2. 在 db/migrator/ 中注册 AutoMigrate
3. 在 internal/apps/admin/<module>/ 中创建：
   - routers.go    （Handler 实现 + Swagger 注释）
   - errs.go       （错误常量，按需）
4. 在 internal/router/router.go 中注册路由
5. 执行 make swagger 更新文档

Handler 文件拆分规则：

逻辑简单的 CRUD 可以全部放在 routers.go 中。但当文件代码行数增长时，必须按以下规则拆分：

条件	拆分方式
文件超过 600 行	必须拆分
包含复杂业务逻辑（如外部调用、多步校验、事务处理）	将业务逻辑拆到 `logic.go` 或 `logics.go`
同一模块有多个独立功能域	按功能域拆分多个文件，如 `user_routers.go`、`role_routers.go`

拆分后的模块文件结构示例：

apps/admin/<module>/
├── routers.go          # 路由注册入口 + 简单 Handler（参数绑定 → 调用逻辑 → 响应）
├── logics.go           # 复杂业务逻辑（外部调用、事务、多步处理）
├── errs.go             # 错误常量
└── constants.go        # 业务常量（按需）

职责边界：

routers.go 只做三件事：参数绑定、调用 logic 函数、返回响应。不包含任何业务判断逻辑。
logics.go 负责所有业务逻辑，接收已校验的参数，返回处理结果和错误。函数以 PascalCase 导出，供 routers.go 调用。

八、前端任务管理页面

任务管理 API 路由（Admin）：

方法	路径	说明
GET	`/api/v1/admin/tasks/types`	获取可调度任务类型列表
POST	`/api/v1/admin/tasks/dispatch`	手动下发任务
GET	`/api/v1/admin/tasks/executions`	分页查询任务执行记录（支持 status / task_type 筛选）
GET	`/api/v1/admin/tasks/executions/:id`	查询单条任务执行详情（含完整 Log）
POST	`/api/v1/admin/tasks/executions/:id/retry`	重试失败任务（校验 Retryable && RetryCount < MaxRetry）

25 KiB Raw Blame History Unescape Escape