kra-new/docs/BUSINESS_OA.md

商务与 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 数据源。