mirror of
https://github.com/hpd840321/craftlabs-authorization-sdk.git
synced 2026-06-09 10:00:30 +08:00
huangping
76ff98db87
Add PARALLEL_ITERATION_INDEX, workspace layout, system architecture, three-track execution packs, BPM/product references, and planned service manifests. Supports I1 alignment across backend, web, and SDK. Made-with: Cursor
189 lines
11 KiB
Markdown
189 lines
11 KiB
Markdown
# 比特授权云：授权制度设计与规则机制（实现依据）
|
||
|
||
> **文档来源**（官方）：
|
||
>
|
||
> - [授权设计与创建](https://doc.bitanswer.cn/docs/function/licensing-design-creation/)
|
||
> - [规则](https://doc.bitanswer.cn/docs/function/rule/)
|
||
>
|
||
> **用途**：作为本仓库及相关功能**设计、实现、联调**时的领域依据；与更宽范围的机制总览见 `[bitanswer-authorization-overview.md](./bitanswer-authorization-overview.md)`。
|
||
> **整理日期**：2026-04-06
|
||
> **对接落地**：创飞侧平台、交付物与能力评估见 [chuangfei-bitanswer-integration-platform.md](./chuangfei-bitanswer-integration-platform.md)。
|
||
|
||
---
|
||
|
||
## 1. 授权制度：四层对象
|
||
|
||
授权由四层对象叠加定义「卖什么、怎么卖、发什么」。
|
||
|
||
|
||
| 层级 | 作用 |
|
||
| -------------------- | ------------------------------------------------------------------------------- |
|
||
| **产品 (Product)** | 定义被授权对象：一套软件或组合；承载**授权功能模块的集合**。含唯一产品名、**特征项**（功能/加密点）、**配置项**（应用与用户小数据）。 |
|
||
| **模版 (Template)** | 产品特征项的**子集**，限定某次授权里**可用模块及版本**，常对应一个**发行版本**。 |
|
||
| **业务 (Business)** | 定义**销售/授权商业模式**：云授权、集团授权、单机授权等；在此配置各类**授权属性组合**。 |
|
||
| **授权 (Entitlement)** | 实际发给用户的授权：**从模版继承模块**；**从业务继承授权类型**，但可**改写**业务允许的授权属性。由全球唯一 **16 位字母数字 SN** 标识。 |
|
||
|
||
|
||
### 1.1 授权内容更新与同步
|
||
|
||
- 授权内容更新后，客户端可用对应 **SN** 升级授权内容。
|
||
- **云授权**：更新可较快反映到客户端，应用**无需重启**。
|
||
- **集团授权、单机授权**：更新在客户端**下次连接服务器**时同步。
|
||
- **单机**：带**智能连接**的会在联网时自动同步；带**强制认证**的需定期连服务器；其它情况多在授权失效时才尝试连服务器。
|
||
- 开发商也可选择**手动**更新客户端本地授权内容。
|
||
|
||
---
|
||
|
||
## 2. 业务侧授权属性（约束维度）
|
||
|
||
在业务中可配置的约束项（不同授权类型下可用组合不同），官方文档列出的包括：
|
||
|
||
|
||
| 属性 | 说明 |
|
||
| --------------- | ----------------------------------- |
|
||
| **连接类型**（单机） | 离线，或可自动进行后台验证的**智能连接**。 |
|
||
| **强制认证** | 客户端**最大离线时间**；超过后须与服务器再次验证才能继续使用。 |
|
||
| **安装限制** | 客户端允许**激活次数**；单机授权下由**所有客户端共享**该次数。 |
|
||
| **有效期** | 从激活起算的最长使用时间。 |
|
||
| **用户数** | 集团授权：集团服务器可支持的**最大并发访问用户数**。 |
|
||
| **起始日期 / 结束日期** | 授权生效、失效的**绝对时间**。 |
|
||
| **使用次数** | 客户端能成功执行 **Login** 的次数上限。 |
|
||
| **终端限制** | 单机授权允许在多少台客户端上被激活。 |
|
||
|
||
|
||
通过不同业务（例如演示业务、永久有效单机正式版业务）组合上述属性，对齐销售与交付形态。
|
||
|
||
---
|
||
|
||
## 3. 特征项 (Feature)：授权在代码中的语义
|
||
|
||
- **标识**：特征 **ID**（整数，API 调用用）+ **名称**（界面展示）；在产品内唯一。
|
||
- **产品级**：数量、名称、类型、是否**可覆盖**、特征组等**仅能在产品特征项界面**完成。
|
||
- **模版 / 授权码级**：只能**选择**特征项、设置特征项的**授权属性**，或修改带「可覆盖」的特征项**值**。
|
||
|
||
### 3.1 特征项在产品上的基本属性
|
||
|
||
- **ID**：系统分配，用于客户端 API 指定特征项。
|
||
- **名称**：用途说明；在集团授权管理界面等对用户可见。
|
||
- **类型**：决定可进行的操作（见下表）。
|
||
- **可覆盖**：是否允许在模版或授权码中**重写该特征项的值**（不同用户/模版需要不同特征值时应开启）。
|
||
- **值**：影响特征项 API 行为。
|
||
|
||
### 3.2 授权码上的特征项授权属性
|
||
|
||
在授权码中可设置/修改（且同时受**整条授权**的授权属性约束）：
|
||
|
||
- **有效期**：自所在授权码激活起算，单位**天**。
|
||
- **结束日期**：可用到结束日当天 24 点。
|
||
- **用户数**：仅**集团授权**类型 SN 可设，为该特征项的可用用户数。
|
||
|
||
### 3.3 特征项类型与 API
|
||
|
||
|
||
| 类型 | 含义 | 主要 API |
|
||
| ------ | ----------- | --------------------------------- |
|
||
| **只读** | 只读数据，客户端不可写 | `ReadFeature` |
|
||
| **读写** | 可读可写 | `ReadFeature`、`WriteFeature` |
|
||
| **算法** | 算法因子，不可直接读写 | `ConvertFeature`（单向转换） |
|
||
| **密钥** | AES 密钥因子 | `EncryptFeature`、`DecryptFeature` |
|
||
|
||
|
||
所有类型均支持 `**QueryFeature`**、`**ReleaseFeature**`：检查是否存在及是否有效。
|
||
**集团授权**：`QueryFeature` 会占用模块用户数，`ReleaseFeature` 释放；文档要求二者在代码中**成对**出现。
|
||
|
||
### 3.4 特征组
|
||
|
||
- 用于管理与勾选；默认有 **「所有」** 组包含全部特征项。
|
||
- 可新建组并向组内添加特征项；**新特征项默认不会**进入除「所有」外的组，需手工维护。
|
||
|
||
### 3.5 实现与安全注意
|
||
|
||
- 典型用法：每需单独授权的模块分配**主特征项**做 `QueryFeature` / `ReleaseFeature`；辅以加密类特征项；模块退出前释放占用（集团场景尤其重要）。
|
||
- 避免**过于频繁**调用特征项 API，以免影响性能。
|
||
- **DRM 产品**：特征项类型不可设置，且不可选「可覆盖」（用于内容加密密钥）。
|
||
- **密钥 / 算法**类型：操作员仅读权限时特征值不可见，显示为 `**`**。
|
||
|
||
---
|
||
|
||
## 4. 配置项 (Data)：非安全存储
|
||
|
||
- **用途**：`Name` / `Value` 字符串对，存应用配置或少量运行时数据；**不应**代替特征项做安全控制。
|
||
- **与特征项区别**：特征项侧重功能点/加密点；配置项侧重应用与用户数据。
|
||
- **覆盖**：模版或授权码中可创建**产品中未预先定义**的配置项名；若与产品配置项同名则运行时取得**覆盖后**的值。
|
||
- **删除**：可删除授权码中的配置项；**删除产品或模版中定义的配置项会返回错误**。
|
||
- **枚举**：`GetDataNum`、`GetDataName` 等。
|
||
- **可靠性**：客户端库可能**缓存**配置项；异常断电等情况下**近期更新可能丢失**，应用需容错。存储为 **UTF-8**，含中文时客户端需注意编码处理。
|
||
|
||
---
|
||
|
||
## 5. 规则 (Rule)：云端可编程扩展
|
||
|
||
与静态「产品—模版—业务—授权」模型并列，**规则**用于在特定**事件**上注入 **JavaScript 判断 + 动作**，扩展业务逻辑。
|
||
|
||
### 5.1 结构
|
||
|
||
|
||
| 组成部分 | 说明 |
|
||
| ------- | ------------------------------------------- |
|
||
| **事件** | 规则入口；向触发器提供 `event` 对象（不同事件字段不同）。 |
|
||
| **触发器** | JavaScript 编写的条件；返回 **布尔**；`true` 时执行动作。 |
|
||
| **动作** | 触发后执行的操作（如回调）；一条规则可有多个动作，**执行顺序不严格保证**；可为空。 |
|
||
|
||
|
||
**约束**：一条规则**仅对应一个事件**；创建后需在列表中**启动**方会在下次事件发生时生效。
|
||
|
||
### 5.2 已定义事件（文档列表）
|
||
|
||
|
||
| ID | 代码 | 名称 |
|
||
| ------ | -------------------------- | -------------------------- |
|
||
| 0x0001 | `yunbaobao:session_logout` | 云保保客户端会话失效（登出、踢出、过期） |
|
||
| 0x0101 | `sn:pre_activate` | 授权码**首次**激活**前** |
|
||
| 0x0102 | `sn:post_activate` | 授权码**首次**激活**后** |
|
||
| 0x0301 | `device:pre_activate` | 设备激活**前**（设备**重新激活**时也会执行） |
|
||
| 0x0302 | `device:post_activate` | 设备激活**后** |
|
||
|
||
|
||
### 5.3 事件载荷要点（实现联调参考）
|
||
|
||
- 多类事件含 `**snInfo`**：`sn`、`type`（如 FLOAT）、`volumeNumber`（终端限制）、`activeDate`、`startDate`、`endDate`（文档说明为与 `expirationDays` 合计相关）、`expirationDays`、`userNumber`、`transferVolume`、`transferNumber`、`status`、`customInfo`、`ip` 等。
|
||
- `**sn:post_activate**`、`**device:post_activate**` 等还含 `**device**`：`regDate`、`mid`（设备指纹）、`status`、`deviceCount`（已激活设备总数）等。
|
||
- `**yunbaobao:session_logout**`：`sn`、`sid`、`type`（LOGOUT / EXPIRED / CLEAR / OTHER）、`logout_time` 等。
|
||
|
||
详细字段以官方文档各事件小节为准。
|
||
|
||
### 5.4 触发器运行环境
|
||
|
||
- 语言：**ECMAScript 5.1**；**禁止使用 `const`、`let`**。
|
||
- **无**任意 IO；**无** `console.log`；**无** `window`、`document`、`location` 等。
|
||
- 保存前应用控制台**调试功能**验证脚本。
|
||
|
||
### 5.5 动作：回调 (Callback)
|
||
|
||
- 配置为 **JSON 数组**；元素示例形态包含 `callback.url`、`callback.headers`（如 `x-bitanswer-token` 用于认证）。
|
||
- **异步**执行；服务端响应**可被忽略**。
|
||
- 使用 **POST**，**JSON** body；内容包含 `event`、`rule`、`data`（含对应事件的 `snInfo` / `device` / `ip` 等）。
|
||
|
||
---
|
||
|
||
## 6. 与实现工作的对应关系（摘要）
|
||
|
||
|
||
| 领域概念 | 实现侧通常对应 |
|
||
| ----------------- | ------------------------------------------ |
|
||
| 产品 / 模版 / 业务 / SN | 控制台配置与发放流程；SDK 登录对象与产品绑定 |
|
||
| 业务授权属性 | 期限、终端、离线、次数、用户并发等策略的建模与校验 |
|
||
| 特征项类型与 API | 功能开关、加密点、集团用户数占用与释放 |
|
||
| 配置项 | 非敏感 K/V 同步；注意缓存与持久化边界 |
|
||
| 规则 | Webhook/内部服务对接激活与设备生命周期；ES5.1 脚本与回调幂等、安全校验 |
|
||
|
||
|
||
---
|
||
|
||
## 7. 修订记录
|
||
|
||
|
||
| 日期 | 说明 |
|
||
| ---------- | ------------------------- |
|
||
| 2026-04-06 | 初版：依据「授权设计与创建」「规则」两篇整理入库。 |
|