# 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` 必须在部署后修改。