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

> **范围**：本仓库内与比特安索（Bitanswer）相关的 URL、回调概念及受影响系统能力。  
> **日期**：2026-04-06  
> **关联**：[授权制度与规则](bitanswer-licensing-design-and-rules.md) · [客户端 API 纲要](bitanswer-client-api-overview.md) · [创飞侧平台与对接能力评估](chuangfei-bitanswer-integration-platform.md)

---

## 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`](../java/craftlabs-auth-core/src/main/java/cn/craftlabs/auth/config/BitanswerConfigSection.java) 字段 `url`。  
- **校验**：[`AuthConfigs`](../java/craftlabs-auth-core/src/main/java/cn/craftlabs/auth/config/AuthConfigs.java) 在 `provider=bitanswer` 时要求非空。  
- **Schema**：[`schemas/craftlabs-auth-config.schema.json`](../schemas/craftlabs-auth-config.schema.json) 描述为 **Bit_Login `szURL`**（云 `http(s)://`、集团 `bit://`、本地 `lic://` 等）。  
- **示例**：  
  - [`examples/config/floating.bitanswer.json`](../examples/config/floating.bitanswer.json)、[`school.bitanswer.json`](../examples/config/school.bitanswer.json)：`https://cloud.bitanswer.example/e3`（占位云地址）。  
  - [`examples/config/wharf.bitanswer.json`](../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`](bitanswer-licensing-design-and-rules.md) §5.5，对应官方 [规则](https://doc.bitanswer.cn/docs/function/rule/) 文档。  
- **形态**：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`](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`](../java/craftlabs-auth-bitanswer/src/main/java/cn/craftlabs/auth/bitanswer/BitAnswerProvider.java) 未暴露 `setAttr`/这些回调；若需使用，要在 **native 层或后续 JNI** 扩展。

### 2.4 其它：`selfhosted.baseUrl`

- **定义**：[`SelfhostedConfigSection`](../java/craftlabs-auth-core/src/main/java/cn/craftlabs/auth/config/SelfhostedConfigSection.java)。  
- **代码**：[`native/src/selfhosted/http_client.h`](../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`](../native/src/bitanswer/bitanswer_adapter.h) 仍为占位；真正接入 `Bit_Login` 等后，应同步更新本文 §2.1 的实现引用。

---

## 4. 修订记录

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