diff --git a/DEV_GUIDE.md b/DEV_GUIDE.md new file mode 100644 index 00000000..541bf1fa --- /dev/null +++ b/DEV_GUIDE.md @@ -0,0 +1,323 @@ +# sub2api 项目开发指南 + +> 本文档记录项目环境配置、常见坑点和注意事项，供 Claude Code 和团队成员参考。 + +## 一、项目基本信息 + +| 项目 | 说明 | +|------|------| +| **上游仓库** | Wei-Shaw/sub2api | +| **Fork 仓库** | bayma888/sub2api-bmai | +| **技术栈** | Go 后端 (Ent ORM + Gin) + Vue3 前端 (pnpm) | +| **数据库** | PostgreSQL 16 + Redis | +| **包管理** | 后端: go modules, 前端: **pnpm**（不是 npm） | + +## 二、本地环境配置 + +### PostgreSQL 16 (Windows 服务) + +| 配置项 | 值 | +|--------|-----| +| 端口 | 5432 | +| psql 路径 | `C:\Program Files\PostgreSQL\16\bin\psql.exe` | +| pg_hba.conf | `C:\Program Files\PostgreSQL\16\data\pg_hba.conf` | +| 数据库凭据 | user=`sub2api`, password=`sub2api`, dbname=`sub2api` | +| 超级用户 | user=`postgres`, password=`postgres` | + +### Redis + +| 配置项 | 值 | +|--------|-----| +| 端口 | 6379 | +| 密码 | 无 | + +### 开发工具 + +```bash +# golangci-lint v2.7 +go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.7 + +# pnpm (前端包管理) +npm install -g pnpm +``` + +## 三、CI/CD 流水线 + +### GitHub Actions Workflows + +| Workflow | 触发条件 | 检查内容 | +|----------|----------|----------| +| **backend-ci.yml** | push, pull_request | 单元测试 + 集成测试 + golangci-lint v2.7 | +| **security-scan.yml** | push, pull_request, 每周一 | govulncheck + gosec + pnpm audit | +| **release.yml** | tag `v*` | 构建发布（PR 不触发） | + +### CI 要求 + +- Go 版本必须是 **1.25.7** +- 前端使用 `pnpm install --frozen-lockfile`，必须提交 `pnpm-lock.yaml` + +### 本地测试命令 + +```bash +# 后端单元测试 +cd backend && go test -tags=unit ./... + +# 后端集成测试 +cd backend && go test -tags=integration ./... + +# 代码质量检查 +cd backend && golangci-lint run ./... + +# 前端依赖安装（必须用 pnpm） +cd frontend && pnpm install +``` + +## 四、常见坑点 & 解决方案 + +### 坑 1：pnpm-lock.yaml 必须同步提交 + +**问题**：`package.json` 新增依赖后，CI 的 `pnpm install --frozen-lockfile` 失败。 + +**原因**：上游 CI 使用 pnpm，lock 文件不同步会报错。 + +**解决**： +```bash +cd frontend +pnpm install # 更新 pnpm-lock.yaml +git add pnpm-lock.yaml +git commit -m "chore: update pnpm-lock.yaml" +``` + +--- + +### 坑 2：npm 和 pnpm 的 node_modules 冲突 + +**问题**：之前用 npm 装过 `node_modules`，pnpm install 报 `EPERM` 错误。 + +**解决**： +```bash +cd frontend +rm -rf node_modules # 或 PowerShell: Remove-Item -Recurse -Force node_modules +pnpm install +``` + +--- + +### 坑 3：PowerShell 中 bcrypt hash 的 `$` 被转义 + +**问题**：bcrypt hash 格式如 `$2a$10$xxx...`，PowerShell 把 `$2a` 当变量解析，导致数据丢失。 + +**解决**：将 SQL 写入文件，用 `psql -f` 执行： +```bash +# 错误示范（PowerShell 会吃掉 $） +psql -c "INSERT INTO users ... VALUES ('$2a$10$...')" + +# 正确做法 +echo "INSERT INTO users ... VALUES ('\$2a\$10\$...')" > temp.sql +psql -U sub2api -h 127.0.0.1 -d sub2api -f temp.sql +``` + +--- + +### 坑 4：psql 不支持中文路径 + +**问题**：`psql -f "D:\中文路径\file.sql"` 报错找不到文件。 + +**解决**：复制到纯英文路径再执行： +```bash +cp "D:\中文路径\file.sql" "C:\temp.sql" +psql -f "C:\temp.sql" +``` + +--- + +### 坑 5：PostgreSQL 密码重置流程 + +**场景**：忘记 PostgreSQL 密码。 + +**步骤**： +1. 修改 `C:\Program Files\PostgreSQL\16\data\pg_hba.conf` + ``` + # 将 scram-sha-256 改为 trust + host all all 127.0.0.1/32 trust + ``` +2. 重启 PostgreSQL 服务 + ```powershell + Restart-Service postgresql-x64-16 + ``` +3. 无密码登录并重置 + ```bash + psql -U postgres -h 127.0.0.1 + ALTER USER sub2api WITH PASSWORD 'sub2api'; + ALTER USER postgres WITH PASSWORD 'postgres'; + ``` +4. 改回 `scram-sha-256` 并重启 + +--- + +### 坑 6：Go interface 新增方法后 test stub 必须补全 + +**问题**：给 interface 新增方法后，编译报错 `does not implement interface (missing method XXX)`。 + +**原因**：所有测试文件中实现该 interface 的 stub/mock 都必须补上新方法。 + +**解决**： +```bash +# 搜索所有实现该 interface 的 struct +cd backend +grep -r "type.*Stub.*struct" internal/ +grep -r "type.*Mock.*struct" internal/ + +# 逐一补全新方法 +``` + +--- + +### 坑 7：Windows 上 psql 连 localhost 的 IPv6 问题 + +**问题**：psql 连 `localhost` 先尝试 IPv6 (::1)，可能报错后再回退 IPv4。 + +**建议**：直接用 `127.0.0.1` 代替 `localhost`。 + +--- + +### 坑 8：Windows 没有 make 命令 + +**问题**：CI 里用 `make test-unit`，本地 Windows 没有 make。 + +**解决**：直接用 Makefile 里的原始命令： +```bash +# 代替 make test-unit +go test -tags=unit ./... + +# 代替 make test-integration +go test -tags=integration ./... +``` + +--- + +### 坑 9：Ent Schema 修改后必须重新生成 + +**问题**：修改 `ent/schema/*.go` 后，代码不生效。 + +**解决**： +```bash +cd backend +go generate ./ent # 重新生成 ent 代码 +git add ent/ # 生成的文件也要提交 +``` + +--- + +### 坑 10：PR 提交前检查清单 + +提交 PR 前务必本地验证： + +- [ ] `go test -tags=unit ./...` 通过 +- [ ] `go test -tags=integration ./...` 通过 +- [ ] `golangci-lint run ./...` 无新增问题 +- [ ] `pnpm-lock.yaml` 已同步（如果改了 package.json） +- [ ] 所有 test stub 补全新接口方法（如果改了 interface） +- [ ] Ent 生成的代码已提交（如果改了 schema） + +## 五、常用命令速查 + +### 数据库操作 + +```bash +# 连接数据库 +psql -U sub2api -h 127.0.0.1 -d sub2api + +# 查看所有用户 +psql -U postgres -h 127.0.0.1 -c "\du" + +# 查看所有数据库 +psql -U postgres -h 127.0.0.1 -c "\l" + +# 执行 SQL 文件 +psql -U sub2api -h 127.0.0.1 -d sub2api -f migration.sql +``` + +### Git 操作 + +```bash +# 同步上游 +git fetch upstream +git checkout main +git merge upstream/main +git push origin main + +# 创建功能分支 +git checkout -b feature/xxx + +# Rebase 到最新 main +git fetch upstream +git rebase upstream/main +``` + +### 前端操作 + +```bash +# 安装依赖（必须用 pnpm） +cd frontend +pnpm install + +# 开发服务器 +pnpm dev + +# 构建 +pnpm build +``` + +### 后端操作 + +```bash +# 运行服务器 +cd backend +go run ./cmd/server/ + +# 生成 Ent 代码 +go generate ./ent + +# 运行测试 +go test -tags=unit ./... +go test -tags=integration ./... + +# Lint 检查 +golangci-lint run ./... +``` + +## 六、项目结构速览 + +``` +sub2api-bmai/ +├── backend/ +│ ├── cmd/server/ # 主程序入口 +│ ├── ent/ # Ent ORM 生成代码 +│ │ └── schema/ # 数据库 Schema 定义 +│ ├── internal/ +│ │ ├── handler/ # HTTP 处理器 +│ │ ├── service/ # 业务逻辑 +│ │ ├── repository/ # 数据访问层 +│ │ └── server/ # 服务器配置 +│ ├── migrations/ # 数据库迁移脚本 +│ └── config.yaml # 配置文件 +├── frontend/ +│ ├── src/ +│ │ ├── api/ # API 调用 +│ │ ├── components/ # Vue 组件 +│ │ ├── views/ # 页面视图 +│ │ ├── types/ # TypeScript 类型 +│ │ └── i18n/ # 国际化 +│ ├── package.json # 依赖配置 +│ └── pnpm-lock.yaml # pnpm 锁文件（必须提交） +└── .claude/ + └── CLAUDE.md # 本文档 +``` + +## 七、参考资源 + +- [上游仓库](https://github.com/Wei-Shaw/sub2api) +- [Ent 文档](https://entgo.io/docs/getting-started) +- [Vue3 文档](https://vuejs.org/) +- [pnpm 文档](https://pnpm.io/)