Logan.Li
4ae318335c
基于 opsx-web-lite 框架（Go+Gin+Vue3+Element Plus）构建许可证管理服务器，
业务域参考 Licence 服务器 Web 版。
【后端 - 4层架构】
- 认证：单 Admin 表 + JWT（HS256）
- 核心授权域：Product / Customer / License / Activation
· License 生成/验证/激活/机器绑定/心跳/续期/吊销
· 客户端契约接口：/api/v1/license/{verify,activate,deactivate,heartbeat}
- 定价订单：Plan / Order / 支付网关配置
- 防重复购买：CustomerEntitlement + 幂等支付 webhook + 手动发放
- 分析审计：Dashboard 统计 / Analytics / AuditLog / Setting 管理
【前端】
- Dashboard（ECharts 图表）、产品、客户、License、计划、订单、权益、日志、设置
- 9 个完整 CRUD 业务页面 + 登录/布局
【部署】
- SQLite + 单二进制（//go:embed 嵌入前端）
- 开发：./run.sh start（前端5181/后端9001）
- 生产：./run.sh build && ./run.sh binary start
- 默认账号：admin/admin
Author: Logan.Li
86 lines
2.9 KiB
Markdown
86 lines
2.9 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` 必须在部署后修改。
|