101 lines
4.1 KiB
Markdown
101 lines
4.1 KiB
Markdown
# AGENTS.md — opsx-licence 开发约定
|
||
|
||
本文件供 AI 协作助手（Claude / ZCode 等）参考，确保产出代码与项目既有风格一致。
|
||
|
||
## 语言与签名
|
||
|
||
- **所有交互、注释、文档一律使用中文。**
|
||
- 每次新增或修改代码注释时，在注释末尾追加 `// Logan.Li` 签名。
|
||
- 函数必须有文档注释（以函数名开头）。
|
||
|
||
## 后端约定
|
||
|
||
### 分层架构（4 层）
|
||
|
||
```
|
||
internal/controller/<domain>/ HTTP 处理层（gin.Context）
|
||
↓
|
||
internal/service/<domain>/ 业务逻辑层（持有 *gorm.DB + *config.Config）
|
||
↓
|
||
internal/dto/ 请求/响应结构体（扁平包，按域分文件）
|
||
internal/model/ GORM 模型（扁平包，按域分文件）
|
||
↓
|
||
GORM
|
||
```
|
||
|
||
### 硬性约束
|
||
|
||
- **Controller 方法 ≤ 80 行**：只做参数校验 + 响应格式化；复杂逻辑下沉到 Service。
|
||
- **Service 承载所有业务逻辑**：DB 操作、业务规则、跨表事务。
|
||
- **单文件 ≤ 300 行**：超出则按子域拆分。
|
||
- **标准 CRUD 方法名**：`List / Get / Create / Update / Delete`。
|
||
- Controller 持有 `service` 与 `db`；Service 持有 `db` 与 `cfg`。
|
||
|
||
### 响应格式
|
||
|
||
统一使用 `dto.Response{Code, Message, Data}`，`code:0` 表示成功。
|
||
|
||
分页响应结构：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"count": 100,
|
||
"total_pages": 10,
|
||
"current_page": 1,
|
||
"page_size": 10,
|
||
"next": "...",
|
||
"previous": "...",
|
||
"results": []
|
||
}
|
||
}
|
||
```
|
||
|
||
### 新增业务域步骤（示例：product）
|
||
|
||
1. `internal/model/product.go` —— GORM 模型
|
||
2. `internal/dto/product.go` —— 请求/响应 DTO
|
||
3. `internal/service/product/product_service.go` —— 业务逻辑
|
||
4. `internal/controller/product/product_controller.go` —— HTTP handler
|
||
5. 在 `router/router.go` 的 protected 组注册路由
|
||
|
||
### 路由规范
|
||
|
||
- 统一 `/api` 前缀，集中注册于 `router/router.go`。
|
||
- 公开接口（登录、客户端验证等）放公开组；管理接口放 JWT 保护组。
|
||
|
||
## 前端约定
|
||
|
||
- **Vue 3 Composition API + `<script setup>`**。
|
||
- **Element Plus**：`el-checkbox` / `el-radio` 的选项用 `value` 而非 `label`。
|
||
- **减少打扰**：常规操作不发成功 toast；仅错误用 `ElMessage.error`；危险操作用确认弹窗。
|
||
- **命名**：组件 PascalCase（`UserList.vue`），工具 camelCase（`request.js`），目录 kebab-case。
|
||
- 接口封装在 `src/api/`，每个业务域一个文件，统一基于 `@/utils/request` 或 `@/api/request` 的 axios 实例。
|
||
|
||
## 认证体系
|
||
|
||
- 单 Admin 表（无 RBAC 多角色）。
|
||
- JWT 单 token，HS256，24h 过期。
|
||
- 中间件 `AuthMiddleware` 校验 `Authorization: Bearer <token>`，写入 `user_id` 到上下文。
|
||
|
||
## 安全
|
||
|
||
- 生产环境（`release` 模式）必须设置 `JWT_SECRET`，否则启动失败。
|
||
- CORS 使用显式白名单，禁止 `*`。
|
||
- 默认账号 `admin/admin` 必须在部署后修改。
|
||
|
||
## 服务器环境（已验证可连）
|
||
|
||
三台机器均可用本机 SSH 密钥登录，部署路径统一为 `/srv/opsx-licence`（容器 9001 端口，`GIN_MODE=release`）。
|
||
|
||
| 机器 | SSH | 角色 |
|
||
|---|---|---|
|
||
| 42.193.242.65（opsx-core） | `ssh root@42.193.242.65`（22 端口） | 应用服务器，域名 `https://licence.rlwj.cn`，容器绑 `127.0.0.1:9001` |
|
||
| 47.243.95.12（pub-monitor） | `ssh root@47.243.95.12 -p 1022`（**注意非标端口**） | 应用服务器，内网 IP `192.168.14.7`，容器绑 `0.0.0.0:9001` |
|
||
| 47.243.187.100（test-hk-web，香港） | `ssh root@47.243.187.100`（22 端口） | nginx 反代，`l123.91ai.io` → `proxy_pass http://192.168.14.7:9001` |
|
||
|
||
- 两个管理后台地址：`https://licence.rlwj.cn` 与 `https://l123.91ai.io`，登录账号 **admin**（密码不写入仓库，向 Logan 索取或查密码管理器；泄露或遗忘时可在服务器容器内重置）。
|
||
- 管理后台登录接口：`POST /api/auth/login`（IP 限流 + 账号级锁定，勿频繁请求）。
|
||
- 两套环境 `JWT_SECRET` 各自独立，互不通用。
|
||
- 47.243.95.12 的 SSH 端口 22 不通，只有 1022；外网仅开放必要端口，由云安全组控制。
|