# 商务与 OA 对接

商务应用负责展示和发起申请，OA 负责商务账号管理、SDK 绑定审核、渠道激活审核与渠道操作。OA 使用 `oa/server`，不依赖尚未迁移业务的 `oa-new`。

## 部署顺序与连接

1. 先升级新商务，完成自动迁移和原商务数据迁移。新商务用户表为 `sys_users`，角色表为 `sys_authorities`，用户角色关系为 `sys_user_authority`。本次新增用户备注列及激活接口权限迁移。
2. OA 的 `db-list` 中保留连接别名 `shangwu`，把该连接的数据库指向**迁移后的新商务主库**。`lx`、`hw`、`yq` 仍指向对应 SDK 数据库。OA 启动会检查 `shangwu.sys_users`，避免误连旧库。
3. 新商务 `data.database_list` 的 `oa` 连接指向 OA 主库；`lx`、`hw`、`yq` 指向对应 SDK 数据库。新商务只读取这些外部表，不创建它们。
4. 两边设置同一服务间密钥。OA 配置使用 `service-credentials.business-integration-key`；新商务可使用环境变量 `KRA_BUSINESS_OA_KEY`，或配置文件中的 `business_oa.key`。密钥只保存在部署环境，不提交版本库。
5. 新商务设置 `KRA_BUSINESS_OA_URL`（或 `business_oa.url`），值为 OA 服务地址，包含 OA 配置的 `router-prefix`，末尾无需添加接口路径。例如 OA 前缀为 `/api` 时，基地址以 `/api` 结尾。
6. 升级 OA。启动迁移新增 OA 激活申请字段，并在已配置的三个 SDK 库创建 `tab_promote_business_event`。部署账号需要对应的建表／改表权限。应用不会把旧库用户字段自动改造成新商务结构。

## 接口与行为

| 功能 | 新商务接口 | OA 行为 |
| --- | --- | --- |
| 激活列表 | `GET /sw/promoteActivePool/bindList` | 读取 OA 的绑定记录，按当前用户已通过的 SDK 绑定限定范围 |
| 激活流水 | `GET /sw/promoteActivePool/bindSpendDetail` | 绑定起算至实际解绑；达标不中止累计；跨平台关联渠道来自申请时的快照，流水和注册读取 OA 使用的 SDK 库 |
| 可申请渠道 | `GET /sw/promoteActivePool/pool` | 仅可认领渠道，状态来自 SDK 库；不返回联系方式、注册详情、充值金额或充值详情 |
| 本人商务选项 | `GET /sw/promoteActivePool/options` | 仅本人审核通过的 SDK 商务；申请平台必须匹配 |
| 申请 | `POST /sw/promoteActivePool/apply` | 后端转发到 `POST /internal/business/activation/apply`，再次校验申请人及其绑定权限 |
| 流失记录 | `GET /sw/promoteActivePool/churn` | 按 SDK 渠道换绑事件展示离开原商务的一侧；从池返回不新增回流记录 |
| 工作台 | 原工作台概览接口 | 锁定／解除合作按事件发生时间、发生时归属商务统计渠道数，解锁不抹去历史 |

服务间申请接口以 HMAC-SHA256 校验方法、完整路径、时间戳和请求体，允许前后五分钟时钟偏差。`X-Business-Timestamp` 为 Unix 秒，`X-Business-Signature` 为十六进制签名。签名串为 `METHOD\nPATH\nTIMESTAMP\nBODY`。业务 ID 使用十进制 JSON 字符串。密钥未配置时拒绝服务间申请。

OA 商务创建／编辑兼容旧请求的 `roleId` 字段，但忽略该值，按 `sys_authorities.business_level` 唯一解析角色。新增账号使用新商务自增 ID、UUID、密码更新时间和默认偏好；锁定同时设置 `business_status` 与 `enable`。调整等级会校验整棵子树并同步角色，不允许把已有 SDK 绑定的账号变成非三级商务。

OA SDK 绑定审核继续使用原接口。审批遇到重复 SDK 绑定时返回已有账号提示，调用方确认后需传 `confirmDuplicate: true`。通过、驳回、解绑与新商务申请共用平台商务键锁。

OA 激活审核接口新增 `bindAt`（`YYYY-MM-DD`，省略时取审核当天）、`reason`（驳回必填）及 `restoreCooperation`（明确确认恢复合作时传 `true`）。审核通过只进入观察期，不改变渠道商务归属；累计流水达标后才变更主渠道及下级的商务归属，并从池中移除关联渠道。`ownershipPending` 表示达标后的跨库归属同步尚待完成；定时扫描会重试，同步成功前关联渠道仍保持认领锁定。观察期内主动解绑或到期未达标，只解除认领，不改渠道归属；已达标记录保持原 OA 规则，不能通过观察期解绑接口退回。

绑定扫描只在观察期内判定达标，迟到的观察期外流水不能使过期申请达标；达标后的展示统计继续累计。外部换绑会结束原激活关系，新商务读取流水时也会依据换绑事件截断，防止读到新归属期间数据。

累计注册统计仅包含绑定期间新增的主账号；身份证去重开启时跨平台按非空实名身份证合并，缺实名不计入。流水不受身份证去重影响。

免预警名单自动移出依据 OA 实际入池记录，避免本地流水不足却被 OA 豁免的渠道被误移出。预警列表的实时流失风险指标仍按其原型定义计算，历史预警快照不更改。

## 历史与校验

渠道事件从本版本部署后开始记录。SDK 事件表保存首次启用时间；工作台查询或同比区间早于该时间时显示历史不完整，而不把缺失记录当成真实零值。现有 SDK 表仅保留当前状态，不能可靠还原过去每次锁定／解除合作与人工换绑，因此不以当前状态伪造历史事件。既有激活记录继续可读；没有关联快照的历史申请按原平台渠道统计。

联调应覆盖：新建商务登录、锁定／解锁、SDK 绑定冲突确认、申请→审核→观察期→达标→归属同步、驳回重提、达标后继续累计、到期解绑、跨库暂时不可用后的同步重试，以及不同商务／平台的访问隔离。单元测试使用临时 SQLite 数据库，真实部署还需按上述连接配置验证实际 OA 和 SDK 数据源。