diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..b2f3fb11 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,254 @@ +## 项目概述 + +AcePanel 是基于 Go 语言开发的新一代 Linux 服务器运维管理面板。项目采用前后端分离架构: +- 后端:Go 1.25 + go-chi 路由 + GORM + Wire 依赖注入 +- 前端:Vue 3 + Vite + Naive UI + pnpm + +**重要提示:** 项目目前正在进行 v3 版本重构,主要包括重构网站/备份/计划任务模块等。 + +## 语言和编码规范 + +**所有代码注释、文档和回复必须使用简体中文。** + +## 构建和测试 + +### 后端构建 + +构建主程序: +```bash +go build -o ace ./cmd/ace +``` + +构建 CLI 工具: +```bash +go build -o cli ./cmd/cli +``` + +构建时注入版本信息: +```bash +VERSION="1.0.0" +BUILD_TIME="$(date -u '+%F %T UTC')" +COMMIT_HASH="$(git rev-parse --short HEAD)" +GO_VERSION="$(go version | cut -d' ' -f3)" + +LDFLAGS="-s -w --extldflags '-static'" +LDFLAGS="${LDFLAGS} -X 'github.com/acepanel/panel/internal/app.Version=${VERSION}'" +LDFLAGS="${LDFLAGS} -X 'github.com/acepanel/panel/internal/app.BuildTime=${BUILD_TIME}'" +LDFLAGS="${LDFLAGS} -X 'github.com/acepanel/panel/internal/app.CommitHash=${COMMIT_HASH}'" +LDFLAGS="${LDFLAGS} -X 'github.com/acepanel/panel/internal/app.GoVersion=${GO_VERSION}'" + +go build -trimpath -buildvcs=false -ldflags "${LDFLAGS}" -o ace ./cmd/ace +``` + +### 运行测试 + +运行所有测试: +```bash +go test -v ./... +``` + +运行测试并生成覆盖率报告: +```bash +go test -v -coverprofile="coverage.out" ./... +``` + +运行单个测试: +```bash +go test -v -run TestFunctionName ./path/to/package +``` + +### 前端开发 + +进入前端目录: +```bash +cd web +``` + +安装依赖: +```bash +pnpm install +``` + +开发模式(带热重载): +```bash +pnpm dev +``` + +类型检查: +```bash +pnpm type-check +``` + +代码检查: +```bash +pnpm lint +``` + +构建生产版本: +```bash +pnpm build +``` + +## 代码架构 + +项目采用类 DDD 分层架构,依赖关系为:route -> service -> biz <- data + +### 核心目录结构 + +- **`cmd/`**: 程序入口 + - `ace/`: 面板主程序 + - `cli/`: 命令行工具 + +- **`internal/app/`**: 应用入口和配置 + +- **`internal/route/`**: HTTP 路由定义 + - 定义路由规则 + - 注入所需的 service 依赖 + +- **`internal/service/`**: 服务层(类似 DDD 的 application 层) + - 处理 HTTP 请求/响应 + - DTO 到 DO 的转换 + - 协调多个 biz 接口完成业务流程 + - **不应处理复杂业务逻辑** + +- **`internal/biz/`**: 业务逻辑层(类似 DDD 的 domain 层) + - 定义业务接口(Repository 模式) + - 定义领域模型和数据结构 + - 使用依赖倒置原则:biz 定义接口,data 实现接口 + +- **`internal/data/`**: 数据访问层(类似 DDD 的 repository 层) + - 实现 biz 中定义的业务接口 + - 封装数据库、缓存等操作 + - 处理数据持久化逻辑 + +- **`internal/http/`**: HTTP 相关 + - `middleware/`: 自定义中间件 + - `request/`: 请求结构体定义 + - `rule/`: 自定义验证规则 + +- **`internal/apps/`**: 面板子应用实现 + +- **`internal/bootstrap/`**: 各模块启动引导 + +- **`internal/migration/`**: 数据库迁移 + +- **`internal/job/`**: 后台任务 + +- **`internal/queuejob/`**: 任务队列 + +- **`pkg/`**: 工具函数和通用包 + - 包含各种独立的工具模块 + - 可被项目任何部分引用 + +- **`web/`**: Vue 3 前端项目 + +## 开发新功能的标准流程 + +1. **在 `internal/route/` 中添加路由** + - 参考已有路由文件(如 `http.go`) + - 注入需要的 service 依赖 + - 定义路由规则和 handler 映射 + +2. **在 `internal/service/` 中实现服务方法** + - **先阅读已有的类似服务**以了解代码风格 + - 处理请求验证和响应格式化 + - 使用 `Success()` 返回成功响应 + - 使用 `Error()` 返回错误响应 + - 使用 `ErrorSystem()` 返回系统严重错误 + - 调用 biz 层接口完成业务逻辑 + +3. **在 `internal/biz/` 中定义业务接口** + - **先阅读已有的类似接口定义** + - 定义 Repository 接口(如 `WebsiteRepo`) + - 定义领域模型结构体(如 `Website`) + - 保持接口简洁明确 + +4. **在 `internal/data/` 中实现 biz 接口** + - **先阅读已有的类似实现** + - 创建 repo 结构体(如 `websiteRepo`) + - 实现构造函数(如 `NewWebsiteRepo`) + - 实现所有接口方法 + - 处理数据库操作和缓存逻辑 + +5. **使用 Wire 进行依赖注入** + - 在对应的 wire.go 文件中添加 provider + - 运行 `go generate` 生成依赖注入代码 + +## 技术栈特定注意事项 + +### Go 语言规范 + +- 使用 Go 1.25 稳定版本 +- 遵循 Go 标准库和习惯用法 +- 日志使用标准库的 `slog` 包 +- 使用 `github.com/samber/lo` 进行函数式编程辅助 + +### 当前框架 + +- 路由:`github.com/go-chi/chi/v5` +- ORM:`gorm.io/gorm` +- 依赖注入:`github.com/google/wire` +- 验证:`github.com/gookit/validate` + +### 助手函数(service 层) + +在 service 层使用以下助手函数: +- `Success(w, data)`: 返回成功响应 +- `Error(w, statusCode, format, args...)`: 返回错误响应 +- `ErrorSystem(w, format, args...)`: 返回系统严重错误(500) +- `Bind[T](r)`: 绑定请求参数到泛型类型 T +- `Paginate[T](...)`: 构建分页响应 + +### 数据库 + +- 使用 SQLite(`github.com/ncruces/go-sqlite3`) +- 使用 GORM 进行数据库迁移和操作 + +### 安全性 + +- 实现认证/授权(JWT) +- 防止 SQL 注入(使用 GORM 参数化查询) +- 防止 XSS 和 CSRF 攻击 +- 实现速率限制(`github.com/sethvargo/go-limiter`) + +## 代码风格 + +- 所有代码注释必须使用简体中文 +- 遵循 Go 官方代码风格 +- 使用 `gofmt` 格式化代码 +- 复杂逻辑添加注释说明 +- 导出的函数和类型必须有注释 + +## Wire 依赖注入 + +项目使用 Wire 进行依赖注入。当添加新的依赖时: + +1. 在 `cmd/ace/wire.go` 或 `cmd/cli/wire.go` 中添加 provider +2. 运行生成命令: +```bash +go generate ./... +``` + +## 前端开发注意事项 + +- 使用 Vue 3 Composition API +- UI 框架:Naive UI +- 状态管理:Pinia +- HTTP 请求:Alova +- 图标:@iconify/vue +- 终端:xterm.js +- 遵循项目已有的组件结构和编码风格 + +## 配置文件 + +开发时需要准备配置文件: +```bash +cp config.example.yml config.yml +``` + +前端开发配置: +```bash +cd web +cp .env.production .env +cp settings/proxy-config.example.ts settings/proxy-config.ts +``` diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 38218e83..00000000 --- a/AGENTS.md +++ /dev/null @@ -1,53 +0,0 @@ -# AGENTS 指南 - -## 基本要求 -- 所有回复、文档、代码注释必须使用简体中文。 -- 项目处于 v3 重构期(网站/备份/计划任务等模块),保持现有架构和风格,避免随意改动。 - -## 项目概览与分层 -- 技术栈:后端 Go 1.25 + go-chi + GORM + Wire;前端 Vue 3 + Vite + UnoCSS + Naive UI + pnpm(Node 24)。 -- 分层:route -> service -> biz <- data,服务层只做编排/DTO 转换,业务逻辑放在 biz,数据访问在 data。 -- 目录:`cmd/ace`/`cmd/cli` 入口;`internal/app` 配置/启动;`internal/route|service|biz|data|http|apps|bootstrap|migration|job|queuejob` 按职责拆分;`pkg/` 通用库与内嵌资源;`web/` 前端;`mocks/` 为 Mockery 生成的仓库接口;构建后的前端复制到 `pkg/embed/frontend`;多语言在 `pkg/embed/locales` 与 `web/src/locales`。 -- 配置示例:`config.example.yml`;CI 脚本见 `.github/workflows/`。 - -## 开发约束 -- 禁止在本地直接运行主程序,只允许在远程 Linux 服务器运行。 -- 开发前准备:`cp config.example.yml config.yml`;前端开发可复制 `.env.development`(或按需 `.env.production`)为 `.env`,必要时复制 `settings/proxy-config.example.ts` 为 `settings/proxy-config.ts`。 - -## 构建与测试 -- 后端: - ```bash - go test ./... - go build ./cmd/ace - go build ./cmd/cli - # 如需注入版本信息可使用 go build -ldflags 方案,保持 -trimpath/-buildvcs=false 一致 - ``` -- 前端: - ```bash - cd web - pnpm install - pnpm type-check - pnpm lint - pnpm dev - pnpm build # 产物输出 dist 并自动复制到 ../pkg/embed/frontend - ``` -- 后端单元测试仅覆盖 `pkg/` 公共包,`internal/` 无需测试;前端不写单元测试,依赖 TS 类型检查与 ESLint。 - -## 开发流程 -1. 在 `internal/route/` 添加路由,注入所需 service。 -2. 在 `internal/service/` 实现编排:参数校验、DTO 处理,返回 `Success`/`Error`/`ErrorSystem`。 -3. 在 `internal/biz/` 定义接口与领域模型,保持精简,接口由 data 实现。 -4. 在 `internal/data/` 用 GORM/缓存等实现仓库逻辑,遵循依赖倒置。 -5. 更新对应 `wire.go` 并运行 `go generate ./...` 完成依赖注入。 - -## 编码规范 -- Go:使用 `gofmt` 与 `golangci-lint`;导出符号需中文注释;错误返回统一使用 `error` 并添加上下文;避免循环依赖,包名短小;日志使用标准库 `slog`,可用 `samber/lo` 辅助;文件按领域拆分(如 `container_*`)。 -- 前端:TypeScript + Vue SFC(组合式 API);样式使用 UnoCSS/Naive UI 主题;状态集中在 `store/`(Pinia);请求使用 Alova;命名采用帕斯卡组件名;Prettier 2 空格 + ESLint 规则。 - -## 数据与安全 -- 默认数据库 SQLite(`github.com/ncruces/go-sqlite3`),通过 GORM 迁移与访问。 -- 需要关注认证/授权(JWT)、SQL 注入防护、XSS/CSRF 防护、速率限制(`github.com/sethvargo/go-limiter`)。 - -## 提交与 PR -- 提交信息遵循惯例式格式(如 `chore(deps): ...`、`feat: ...`、`fix: ...`),一次提交聚焦单一主题。 -- PR 应包含:变更摘要、关联 Issue/需求、测试命令与结果、前端可视化改动的截图;确保 CI(lint/test/build)在干净环境可复现。