craftlabs-authorization-sdk/docs/bitanswer-callbacks-endpoints-assessment.md

比特安索方案：工作区走查 — 地址与「回调」评估

范围：本仓库内与比特安索（Bitanswer）相关的 URL、回调概念及受影响系统能力。
日期：2026-04-06
关联：授权制度与规则 · 客户端 API 纲要 · 创飞侧平台与对接能力评估

---

1. 结论摘要

类别	是否在本仓库配置	典型形态	涉及系统功能
bitanswer.url（授权服务地址）	是（JSON 配置 + Schema）	https://… 云/E3、bit://ip:port 集团、lic://… 本地等	登录、在线激活/升级、会话与心跳、特征项校验等与 Bitanswer 运行时 直连的能力
控制台「规则」HTTP Callback	否（官方控制台配置）	业务系统提供的 https://… Webhook + x-bitanswer-token	订单/资产/审计：激活前后、设备绑定、云保保会话失效等事件的异步通知与集成
SDK 属性里的函数指针回调	未在本 SDK 封装层暴露	C 侧 SetAttr + ATTR_HB_*_CALLBACK 等	进程内心跳失败/停止、集团排队等待等 UI 或重连策略，非 HTTP
selfhosted.baseUrl	是（另一 provider）	自研授权 HTTP 根地址	与比特方案并行；本仓库仅 selfhosted_http_ping 等占位，非 Bitanswer 官方回调

本 SDK 当前 BitAnswerProvider 仅委托 native，未实现规则 Webhook 接收端；若产品要在比特控制台配规则回调，需在 独立后端服务 实现 POST 接口与鉴权。

---

2. 本仓库中出现的「地址」清单

2.1 配置项：bitanswer.url

• 定义：BitanswerConfigSection 字段 url。
• 校验：AuthConfigs 在 provider=bitanswer 时要求非空。
• Schema：schemas/craftlabs-auth-config.schema.json 描述为 Bit_Login szURL（云 http(s)://、集团 bit://、本地 lic:// 等）。
• 示例：
  • examples/config/floating.bitanswer.json、school.bitanswer.json：https://cloud.bitanswer.example/e3（占位云地址）。
  • examples/config/wharf.bitanswer.json：bit://license.example.com:8273（集团服务）。

功能映射（客户端 → 比特侧）：

• 登录与会话：Bit_Login / Bit_LoginEx 连到该 URL 所指云中心或集团服务；决定云/集团/混合行为还与 loginMode、环境变量等有关（见 docs/bitanswer-client-api-overview.md §2–3）。
• 在线激活与升级：同类 URL 会传给 Bit_UpdateOnline、Bit_GetUpdateInfo 等（官方 API 表见 docs/bitanswer-client-api-overview.md §5）。
• 可选 rootPath：配置项中有 rootPath，对应 Bit_SetRootPath，影响本地授权文件查找根目录（与 URL 形态 root:// 语义相关，见 docs/c.md）。

2.2 文档中的规则 Callback URL（非本仓库代码配置）

• 出处：docs/bitanswer-licensing-design-and-rules.md §5.5，对应官方 规则 文档。
• 形态：JSON 动作数组中的 callback.url，请求头可含 x-bitanswer-token。
• 触发事件（与业务系统相关）：sn:pre_activate / sn:post_activate、device:pre_activate / device:post_activate、yunbaobao:session_logout 等。

功能映射（贵司后端若承接回调）：

事件	建议评估的系统能力
sn:pre_activate	激活前风控：黑名单、订单状态、SN 与合同是否一致；可配合异步拒绝策略（以实现为准）
sn:post_activate	开通交付、CRM 状态更新、用量计费起点、通知客户
device:pre_activate / post_activate	设备台账、换机策略、终端数/浮动策略与内部资产系统对账
yunbaobao:session_logout	会话吊销联动：踢下线、清理服务端会话、安全审计

注意：官方说明回调为 异步 POST，响应体可被忽略；接收方应 幂等、校验 x-bitanswer-token、限流与防重放。

2.3 SDK 文档中的「回调」= C 函数指针（非 URL）

• 出处：docs/c.md 中 Bit_SetAttr 相关常量，例如：
  • ATTR_HB_STOPED_CALLBACK / ATTR_HB_STOPED_CALLBACK_EX：心跳停止
  • ATTR_HB_RETRY_FAILED_CALLBACK / ATTR_HB_RETRY_CALLBACK_EX / EX2：心跳重试失败/重试
  • ATTR_HB_RETRY_SUCCESS_CALLBACK：心跳重试成功
  • ATTR_QUEUE_WAIT_CALLBACK：集团排队等待（与 BIT_QUERY_WAIT 等配合）

功能映射：在 同一进程内 由 Bitanswer 客户端库调用开发商注册的函数，用于 监控与授权服务的连接质量、排队 UX、自动重连。
本仓库：BitAnswerProvider 未暴露 setAttr/这些回调；若需使用，要在 native 层或后续 JNI 扩展。

2.4 其它：selfhosted.baseUrl

• 定义：SelfhostedConfigSection。
• 代码：native/src/selfhosted/http_client.h 中 selfhosted_http_ping(base_url)。
• 说明：属于 自研授权 provider，与比特控制台规则 Callback 无直接对应；评估部署时不要与 bitanswer.url 混淆。

---

3. 对实现与运维的检查项建议

1. bitanswer.url：区分环境（云/E3 生产、测试集团 bit://、纯本地 lic://）；与 产品识别码 applicationData、SN 一并纳入密钥与配置管理。
2. 规则 Callback URL：在架构图中单独标注为 比特云 → 贵司公网/内网穿透 HTTPS；明确 谁生成 x-bitanswer-token、轮换与日志脱敏（含 sn、mid、IP）。
3. 函数指针回调：若未来在 native 启用，明确线程模型与 不得在回调中执行阻塞 IO 等约束（以官方 bitanswer.h 为准）。
4. 文档与代码一致性：当前 native/src/bitanswer/bitanswer_adapter.h 仍为占位；真正接入 Bit_Login 等后，应同步更新本文 §2.1 的实现引用。

---

4. 修订记录

日期	说明
2026-04-06	初版：基于工作区 grep 与核心配置/Java/native 文件走查。