craftlabs-authorization-sdk/docs/bitanswer-licensing-design-and-rules.md

比特授权云：授权制度设计与规则机制（实现依据）

文档来源（官方）：

• 授权设计与创建
• 规则

用途：作为本仓库及相关功能设计、实现、联调时的领域依据；与更宽范围的机制总览见 [bitanswer-authorization-overview.md](./bitanswer-authorization-overview.md)。
整理日期：2026-04-06
对接落地：创飞侧平台、交付物与能力评估见 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	初版：依据「授权设计与创建」「规则」两篇整理入库。