license-manager/backend/docs/demand/2026.1.21-用户授权管理相关接口.md

用户授权管理相关接口

分组建议：放到“用户端授权码管理”（Customer User / CU）分组，统一前缀：/api/cu

通用约定

• 鉴权：Authorization: Bearer <token>（必填）
• 多语言：Accept-Language header 或 ?lang=zh-CN（可选）
• 成功返回：models.APIResponse
• 失败返回：models.ErrorResponse

参考接口（已实现）

为保持接口风格一致（路径、鉴权、返回结构），本设计参考并沿用以下已实现接口：

• POST /api/cu/authorization-codes/{codeId}/share：用户分享授权码
• POST /api/cu/authorization-codes/product-activation-code：获取产品激活码
• GET /api/v1/authorization-codes：授权码列表（管理端，分页结构可复用）

状态约定

授权码状态沿用系统枚举：

• normal：有效（当前时间未超过 end_date 且未锁定）
• expired：已过期（当前时间超过 end_date）
• locked：已锁定（is_locked=true；是否过期由 end_date 决定）

前端展示“有效/已过期”时，可将 locked 作为“有效但锁定”或单独状态展示（以 UI 为准）。

接口定义

1) 获取用户授权码列表（新增）

GET /api/cu/authorization-codes

Query 参数

• page：页码，默认 1
• page_size：每页数量，默认 10，最大 100
• status：状态筛选（可选）normal / expired / locked
• search：授权码模糊匹配（可选，匹配 code）

响应（200）

{
  "code": "000000",
  "message": "成功",
  "data": {
    "list": [
      {
        "id": "uuid-string",
        "code": "LIC-COMP001-A7B9X2-C8F4",
        "status": "normal",
        "status_display": "正常",
        "max_activations": 10,
        "current_activations": 7,
        "remaining_activations": 3,
        "created_at": "2026-01-21T10:00:00Z",
        "end_date": "2026-12-31T23:59:59Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10,
    "total_pages": 1
  },
  "timestamp": "2026-01-21T10:05:00Z"
}

字段说明

• max_activations：设备总数（可绑定/可激活上限）
• current_activations：已绑定设备数（已激活许可证数量）
• remaining_activations：剩余可绑定设备数（建议字段；也可由前端计算 max_activations - current_activations）
• end_date：到期时间（授权结束时间）

错误码

• 100004：缺少认证信息
• 900001：请求参数无效
• 900004：服务器内部错误

---

2) 用户授权信息统计（新增）

GET /api/cu/authorization-codes/summary

响应（200）

{
  "code": "000000",
  "message": "成功",
  "data": {
    "total_count": 12,
    "expired_count": 3,
    "valid_count": 9,
    "valid_max_activations_sum": 150
  },
  "timestamp": "2026-01-21T10:05:00Z"
}

字段说明

• total_count：总授权码数量
• expired_count：已过期授权码数量
• valid_count：有效授权码数量（建议口径：status=normal，是否包含 locked 由产品定义；若包含请在实现中统一）
• valid_max_activations_sum：有效授权码的 max_activations 之和

错误码

• 100004：缺少认证信息
• 900004：服务器内部错误

---

3) 用户分享授权码（已实现）

POST /api/cu/authorization-codes/{codeId}/share

说明：接口实现与 Swagger 注释已存在于 backend/internal/api/handlers/cu_authorization_handler.go。

---

4) 获取产品激活码（已实现）

POST /api/cu/authorization-codes/product-activation-code

说明：接口实现与 Swagger 注释已存在于 backend/internal/api/handlers/cu_authorization_handler.go。