opsx-licence/AGENTS.md

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 表示成功。

分页响应结构：

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