API 文档
给插件、桌面端与测试同学直接查阅：正式接口、授权模型、多语言示例与联调路径。
推荐调研路径
先准备 projectKey，再按 activate → status → consume 联调，最后用后台日志和 smoke 脚本回证。
- 01
先确认项目与授权模型
在项目管理里确认当前插件对应的 projectKey，并区分是时间型还是次数型激活码。
结果：避免把错误项目的激活码带入联调，也能提前判断是否需要 requestId。
- 02
先调 activate 绑定设备
用户首次输入激活码时调用 /api/license/activate，让系统先绑定 machineId。
结果：时间型会从此刻开始计算有效期；次数型只绑定设备，不会立即扣次。
- 03
再调 status 观察返回字段
拿同一组 code + machineId 调用 /api/license/status，确认 expiresAt / remainingCount / valid 等字段。
结果：可以快速验证当前激活码是否处于正确状态，便于插件前端显示授权信息。
- 04
真实业务再调 consume
只有发生真实业务动作时才调用 /api/license/consume，并且推荐始终带上 requestId。
结果：同一 requestId 会幂等返回，不会因为客户端重试或网络抖动重复扣次。
- 05
去后台消费日志按 requestId 反查
联调时把 requestId、machineId 带到“消费日志”页搜索，核对每次扣次是否正确落库。
结果：可以把接口行为与后台日志一一对应，快速定位重复请求、错误设备或项目混用问题。
- 06
最后跑 smoke 脚本做回归
本地启动后执行 smoke:license-api，让项目自动走完登录、建项目、生成卡、激活、状态、幂等扣次。
结果：把接口调研从人工验证升级为可重复的联调回归流程。
授权模型
同一套正式接口同时支持时间型、次数型，并按 projectKey 隔离多产品授权空间。
时间型激活码
适合按天/月/年计费的授权模式，首次激活后开始计算有效期。
- 首次 activate 时写入 usedBy / usedAt / expiresAt。
- 后续 status / consume 只做有效性校验，不扣减次数。
- 插件展示剩余有效期时，优先使用 expiresAt / expires_at。
次数型激活码
适合浏览器插件、桌面工具等按次数消耗的场景。
- activate 只绑定设备，不扣减 remainingCount。
- consume 每次成功调用扣减 1 次，且支持 requestId 幂等。
- status 可用于展示剩余次数、是否已激活与当前是否仍有效。
多项目隔离
同一个服务端可同时给多个产品、插件或客户提供独立授权空间。
- 每张激活码都归属于某个 projectKey。
- 同一台设备可以在不同 projectKey 下分别绑定激活码。
- 项目停用后，正式接口会直接返回“项目已停用”。
字段约定
正式接口支持 camelCase / snake_case 双写法；响应会同时返回两套字段名，便于不同语言接入。
请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| projectKey / project_key | string | 否 | 项目标识；不传时默认走 default 项目。 |
| code | string | 是 | 激活码正文。 |
| machineId / machine_id | string | 是 | 设备唯一标识，建议插件本地持久化一个稳定 UUID。 |
| requestId / request_id | string | 仅 consume 推荐 | 请求幂等键；同一 requestId 的 consume 只会成功扣减一次。 |
响应字段
| 字段 | 类型 | 返回时机 | 说明 |
|---|---|---|---|
| success | boolean | 总是返回 | 业务层是否成功。 |
| message | string | 总是返回 | 提示信息或失败原因。 |
| licenseMode / license_mode | TIME | COUNT | null | 按场景返回 | 授权类型。 |
| expiresAt / expires_at | string | null | 时间型常用 | 时间型过期时间。 |
| remainingCount / remaining_count | number | null | 次数型常用 | 次数型剩余次数。 |
| isActivated / is_activated | boolean | null | 按场景返回 | 当前激活码是否已绑定到设备。 |
| valid | boolean | null | 按场景返回 | 当前是否仍有效。 |
| idempotent | boolean | null | consume 常用 | 本次是否命中了 requestId 幂等重放。 |