feat: 完成 opsx-licence 许可证管理平台全栈实现

基于 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
This commit is contained in:
Logan.Li committed 2026-08-07 15:02:00 +08:00
commit 4ae318335c
88 files changed
+10562

No files matched your search

+85
View File
@@ -0,0 +1,85 @@
# 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` 必须在部署后修改。