mirror of
https://github.com/acepanel/panel.git
synced 2026-02-04 17:17:13 +08:00
54 lines
3.2 KiB
Markdown
54 lines
3.2 KiB
Markdown
# 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）在干净环境可复现。
|