Kami 接口调用说明 单入口管理端
这份说明用于快速接入当前部署版本。客户端授权接口保持独立；管理端接口统一走
POST /api/v1/admin，通过 action 分发。
1. 基础信息
- Base URL:
__BASE_URL__ - 客户端接口：
/api/v1/activate、/api/v1/verify、/api/v1/heartbeat、/api/v1/change-device、/api/v1/runtime - 管理端接口：
/api/v1/admin（统一入口） - 管理端登录使用
HttpOnly Cookie维持会话 - 计时型卡密从“首次激活”开始计算有效期（不是创建时间）
2. 管理端 action 列表
| 分类 | action | 说明 |
|---|---|---|
| 认证 | auth.login | 账号密码登录 |
| 认证 | auth.logout | 退出登录 |
| 认证 | auth.me | 获取当前登录用户 |
| 认证 | auth.change-password | 修改密码 |
| 软件 | products.list/create/update | 软件管理 |
| 软件 | products.delete | 删除软件（仅无卡密记录可删） |
| 代理 | agents.list/create/update | 代理管理 |
| 范围 | scopes.list/assign | 代理软件范围 |
| 卡密 | licenses.list/create/disable | 卡密列表/生成/禁用 |
| 卡密 | licenses.delete | 删除单条卡密 |
| 卡密 | licenses.delete-batch | 批量删除卡密 |
| 升级 | releases.get/upsert | 每软件独立升级策略 |
| 通知 | notices.list/create/update-status/delete | 通知管理 |
| 日志 | logs.list | 审计日志列表 |
| 统计 | stats.get | 仪表盘统计 |
3. 调用示例（curl）
3.1 登录
curl -X POST "__BASE_URL__/api/v1/admin" \
-H "Content-Type: application/json" \
-d '{"action":"auth.login","username":"admin","password":"你的密码"}'3.2 获取会话用户（登录后）
curl -X POST "__BASE_URL__/api/v1/admin" \
-H "Content-Type: application/json" \
-d '{"action":"auth.me"}'3.3 创建软件（超管）
curl -X POST "__BASE_URL__/api/v1/admin" \
-H "Content-Type: application/json" \
-d '{"action":"products.create","code":"DEMO_APP","name":"Demo App","enabled":true}'3.4 生成卡密（超管/代理受权限限制）
curl -X POST "__BASE_URL__/api/v1/admin" \
-H "Content-Type: application/json" \
-d '{"action":"licenses.create","productId":"软件ID","planCode":"trial","cardType":"test","prefix":"T","quantity":1}'4. 客户端调用示例
激活：
POST /api/v1/activate
{
"licenseKey": "T-XXXXX-XXXXX-XXXXX",
"productCode": "DEMO_APP",
"deviceFingerprint": "device-001",
"clientVersion": "1.0.0"
}校验：
POST /api/v1/verify
{
"token": "登录后返回的token",
"deviceFingerprint": "device-001"
}启动拉取升级策略和通知：
curl -X POST "__BASE_URL__/api/v1/runtime" \
-H "Content-Type: application/json" \
-d '{"action":"bootstrap","productCode":"DEMO_APP","clientVersion":"1.2.10","deviceFingerprint":"device-001"}'通知已读回执：
curl -X POST "__BASE_URL__/api/v1/runtime" \
-H "Content-Type: application/json" \
-d '{"action":"notice.ack","productCode":"DEMO_APP","noticeId":"通知ID","deviceFingerprint":"device-001"}'5. 排错建议
- 卡密列表按权限显示明文：超管可查看全部，代理仅可查看自己创建的卡密。
- 历史数据如果未保存可解密明文，仍会显示掩码。
- 卡密列表默认展示软件名称（含编码），便于运营查看。
- 卡密列表包含激活状态（已激活/未激活）与首次激活时间，便于运营识别是否已被使用。
- 卡密筛选支持：软件、状态、类型、激活状态。
- 返回
ADMIN_AUTH_REQUIRED：会话失效，重新执行auth.login。 - 前端看起来还在登录层：强刷页面（
Ctrl + F5）并确认样式已更新。 - Vercel Hobby 报函数超限：请保持管理端单入口，不要拆回多个
/admin/*函数文件。