# 项目规范文档 (dsbqj-admin)

本文档旨在概述 `dsbqj-admin` Go 项目的技术栈、结构、规范和可用命令，为开发者提供统一的指引。

## 1. 项目概述

这是一个基于 Go 语言和 Gin 框架构建的后台管理系统。项目采用 Monorepo（单一仓库多项目）的组织形式，包含了多个独立运行的服务。

- **项目名称**: `dsbqj-admin`
- **Go 版本**: `1.24`
- **核心框架**: Gin

## 2. 技术栈

项目采用了一系列成熟的 Go 技术栈，核心技术如下：

- **Web 框架**: `github.com/gin-gonic/gin`
- **数据库**:
  - **MongoDB**: 使用 `go.mongodb.org/mongo-driver` 驱动和 `github.com/kamva/mgm/v3` ORM。
  - **MySQL**: 使用 `github.com/jinzhu/gorm` ORM。
- **缓存**: `github.com/go-redis/redis`
- **配置**: 通过 `github.com/joho/godotenv` 从 `.env` 文件加载环境变量。
- **校验**: `github.com/go-playground/validator/v10`
- **云服务**:
  - **阿里云对象存储 (OSS)**
  - **阿里云短信服务**

## 3. 项目结构

项目遵循了清晰的、按功能划分的目录结构：

```
.
├── app/                  # 应用核心逻辑
│   ├── api/              # API 接口定义 (HTTP Handler)
│   ├── router/           # 路由注册与配置
│   ├── service/          # 业务逻辑层
│   └── task/             # 后台定时任务
├── config/               # 配置文件 (如 .env.local)
├── main-admin/           # 管理后台服务入口
├── main-point/           # "Point" 服务入口
├── main-subscribe/       # "Subscribe" 服务入口
├── middleware/           # Gin 中间件 (JWT, CORS, Logger)
├── model/                # 数据模型 (区分 Mongo 和 MySQL)
│   ├── mongo/
│   └── mysql/
├── pkg/                  # 可重用的公共包 (工具、日志、配置等)
├── .gitignore
├── go.mod                # Go 模块依赖
├── go.sum
└── build.bat             # 全局构建脚本
```

## 4. 编码规范

为了保持代码的一致性和高质量，所有开发者应遵循以下规范：

### 代码格式化

- **强制使用 `gofmt`**: 所有提交的代码都必须使用 `gofmt` 进行格式化。推荐在 IDE 中配置保存时自动格式化。
- **遵循 Go 社区风格**: 编写符合 Go 社区普遍接受的编码风格和模式。

### 静态检查

- **使用 `go vet`**: 在提交代码前，运行 `go vet ./...` 来捕获可疑的构造和潜在错误。
- **Linter (推荐)**: 虽然项目中未包含 `.golangci.yml`，但强烈建议使用 [golangci-lint](https://golangci-lint.run/) 并配置一套合理的规则，以进行更全面的静态分析。

### 命名规范

- **包名**: 使用简短、小写且有意义的名称。
- **变量与函数**: 遵循 Go 的驼峰命名法（`camelCase` 或 `PascalCase`），并根据其导出状态决定首字母大小写。
- **接口**: 单一方法的接口通常以 `-er` 结尾（如 `Reader`, `Writer`）。

## 5. 可用命令

项目的主要操作通过根目录及各 `main-*` 目录下的 `build.bat` 批处理脚本执行。

- **`build.bat` (根目录)**:
  - 用于构建所有或特定的服务。具体用法请查看脚本内容。

- **`main-*/build.bat`**:
  - 用于单独构建和运行对应的服务（`admin`, `point`, `subscribe`）。

- **运行服务 (示例)**:
  ```bash
  # 进入特定服务的目录
  cd main-admin

  # 运行构建脚本 (如果脚本支持) 或直接运行 main.go
  go run main.go
  ```

- **依赖管理**:
  - **安装/更新依赖**: `go mod tidy`
  - **下载依赖**: `go mod download`