refactor: 标准化项目结构 frontend/ + backend/ + SQLite + run.sh

- 目录重构: app/ -> frontend/，与 backend/ 并列 - 数据库: 默认 SQLite（零配置），修复 DSN() bug - run.sh: 一键启动前后端，支持 start/stop/restart/status - Makefile: install/dev/build/lint/clean 快捷命令 - vite.config.ts: 配置 dev server 端口 5173 + API 代理到 8080 - config.yaml: SQLite 默认配置，开箱即用 - docs/: 完整开发文档（项目结构/API/数据库/规范/部署） - 修复: GORM foreign key 关联声明 - 修复: go get gorm.io/driver/sqlite 依赖
2026-06-13 23:34:23 +08:00
1 parent 7d6674bddd
commit 97c4207ff8
@@ -0,0 +1,188 @@
+# 开发规范
+
+## Git 工作流
+
+### 分支策略
+
+| 分支 | 说明 |
+|------|------|
+| `main` / `master` | 生产分支，保护分支 |
+| `dev` | 开发集成分支 |
+| `feature/*` | 功能分支 |
+| `fix/*` | 修复分支 |
+| `hotfix/*` | 紧急修复 |
+
+### 提交规范
+
+```
+<type>: <description>
+
+- 变更点 1
+- 变更点 2
+```
+
+Type 列表：
+- `feat`: 新功能
+- `fix`: Bug 修复
+- `refactor`: 重构
+- `docs`: 文档
+- `style`: 样式
+- `test`: 测试
+- `chore`: 构建/工具
+
+示例：
+```
+feat: 添加服务器批量导入功能
+
+- 支持 Excel 导入
+- 支持云平台同步
+```
+
+## 后端规范（Go）
+
+### 目录职责
+
+| 目录 | 职责 |
+|------|------|
+| `cmd/` | 应用入口 |
+| `internal/handlers/` | HTTP 请求处理（参数校验、响应） |
+| `internal/models/` | 数据模型定义 |
+| `internal/config/` | 配置管理 |
+| `internal/middleware/` | 中间件 |
+| `internal/routes/` | 路由注册 |
+| `pkg/database/` | 数据库连接 |
+| `pkg/logger/` | 日志工具 |
+
+### 命名规范
+
+- 文件名：`snake_case.go`
+- 类型/方法：`PascalCase`
+- 变量：`camelCase`
+- 常量：`PascalCase` 或 `ALL_CAPS`
+
+### 统一响应格式
+
+```go
+// 成功响应
+c.JSON(http.StatusOK, models.Response{
+    Code:    200,
+    Message: "success",
+    Data:    result,
+})
+
+// 分页响应
+c.JSON(http.StatusOK, models.Response{
+    Code:    200,
+    Message: "success",
+    Data: models.ListResponse{
+        List:  items,
+        Total: total,
+    },
+})
+
+// 错误响应
+c.JSON(http.StatusBadRequest, models.Response{
+    Code:    400,
+    Message: "参数错误: " + err.Error(),
+})
+```
+
+### Handler 模板
+
+```go
+func (h *ServerHandler) CreateServer(c *gin.Context) {
+    // 1. 参数绑定
+    var req models.ServerRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.JSON(http.StatusBadRequest, models.Response{Code: 400, Message: err.Error()})
+        return
+    }
+
+    // 2. 业务逻辑
+    server := models.Server{
+        Name: req.Name,
+        IP:   req.IP,
+    }
+    if err := h.db.Create(&server).Error; err != nil {
+        c.JSON(http.StatusInternalServerError, models.Response{Code: 500, Message: "创建失败"})
+        return
+    }
+
+    // 3. 返回结果
+    c.JSON(http.StatusOK, models.Response{Code: 200, Message: "创建成功", Data: server})
+}
+```
+
+### 注意事项
+
+- GORM `First()` 连续查询会带上次 ID，用 `Take()` 代替
+- Go 编译前设置 `GOPROXY=https://goproxy.cn,direct`
+- SQLite 需要 `CGO_ENABLED=1`
+- JWT 使用 `golang-jwt/jwt/v5`，`jwt.TimeFunc()` 已移除，用 `time.Now()`
+
+## 前端规范（React + TypeScript）
+
+### 目录职责
+
+| 目录 | 职责 |
+|------|------|
+| `src/components/*/` | 业务组件 |
+| `src/components/ui/` | shadcn/ui 基础组件 |
+| `src/hooks/` | 自定义 Hooks |
+| `src/lib/` | 工具函数 |
+| `src/services/` | API 封装 |
+| `src/store/` | Zustand 状态管理 |
+| `src/types/` | TypeScript 类型 |
+| `src/mocks/` | Mock 数据 |
+
+### 命名规范
+
+- 组件文件：`PascalCase.tsx`（如 `ServerManager.tsx`）
+- 工具文件：`camelCase.ts`（如 `formatDate.ts`）
+- 组件名：`PascalCase`
+
+### UI 设计原则
+
+- 能去掉的装饰都去掉（无边框、无多余分隔线）
+- 选中态用 `bg-surface-active`，不用彩色高亮
+- 页面打开即用，不需要额外的"新建"按钮跳转
+- 操作成功不弹 toast，仅在失败时提示
+
+### API 调用
+
+前端通过 Vite 代理访问后端 API：
+
+```typescript
+// 开发环境请求会被代理到 http://localhost:8080
+fetch('/api/v1/servers')
+```
+
+## 测试
+
+### 后端测试
+
+```bash
+cd backend
+go test -v ./...
+```
+
+### 前端构建测试
+
+```bash
+cd app
+npm run build  # TypeScript 编译 + Vite 构建
+```
+
+## 日志
+
+| 级别 | 使用场景 |
+|------|---------|
+| Info | 服务启动、正常操作 |
+| Warn | 配置缺失、降级处理 |
+| Error | 操作失败、异常 |
+| Fatal | 启动失败、不可恢复 |
+
+```go
+log.Info("server started", zap.String("port", cfg.Port))
+log.Error("database error", zap.Error(err))
+```