docs: 记录商务画像口径和后续实现入口

docs/sw6-to-kra/portrait-source-notes.md

@@ -0,0 +1,43 @@
+# 下一批：商务与 SDK 商务画像
+
+状态：已核对以下源码，尚未实现两种画像接口和页面入口。账号状态联动已在 `fc17b38` 完成，不要重复迁移。下一步直接实现画像及其报表查询依赖。
+
+## 范围与入口
+
+- `GET /sw/business/:userId/portrait`：普通商务画像。旧 `BusinessPortraitQueryBo` 取 `sourceDbList`，必须选择平台；不是渠道接口的 `sourceDb` 参数。通过目标商务本人及下级的正常绑定解析渠道范围。
+- `GET /sw/business/bindPlatform/portrait`：指定 `sourceDb` 与 `platformBusierId` 的正常绑定，校验当前登录人的可见范围。基本资料读取对应平台 `tab_promote_business`，不能用 SW 用户资料冒充。
+- 两种画像共用旧 `BusinessProfileDrawer.vue`。商务列表“画像”、绑定正常行“画像”、只读 SDK 绑定详情的平台入口都需要接上；此前移除的“编辑”不能恢复。
+- SDK 基本信息中 `userId` 实际是平台商务 ID。关联预警及旗下渠道的查询仍应使用打开抽屉时的 SW 用户 ID 和绑定参数，不能误用这个平台 ID。
+
+## 基本信息
+
+- 普通商务：账号、姓名、级别、父商务账号/姓名、创建时间、审核状态；渠道数只数所选范围内一级渠道，本月新增判断渠道创建 Unix 秒位于上海本月首日（含）至明天零点（不含）。
+- SDK 商务：账号、姓名、级别、创建 Unix 秒。二级的父商务是 `commerce1`，三级是 `commerce2`，一级没有父级；父记录不存在时不填父资料。
+- SDK 状态与 SW 不同：SDK 的 1 为正常、0 为待审核、其余为停用；不能把 SDK 字符串 `"0"` 套用成 SW 正常。
+- 普通商务画像的渠道数包含目标商务的下级绑定；旧“旗下渠道”抽屉接口仍是直属口径，需要保留并记录两者差异。
+
+## 时间、卡片与趋势
+
+来源：`BusinessPortraitServiceImpl`、`BusinessPortraitSupport`。
+
+- 画像服务支持 today、yesterday、last7、last30、thismonth，大小写归一，空/未知回退 today。公共 helper 另外支持 total，但普通商务画像服务不接受 total；渠道画像才使用累计模式。
+- today 对比昨日；yesterday 对比前日；last7/last30 包含今天并对比前一完整同长周期；thismonth 对比上月首日至相同日号，上月不足该日时截到月末。
+- 注册玩家来自日汇总身份键的 REGISTER=1；付费率为 PAY=3 人数 / ACTIVE=2 人数 ×100，保留 1 位；人均充值为金额 / 注册人数，保留 2 位。
+- 当前活跃为零时付费率为 0.0；对照期活跃为零时 compareValue 为 null，百分点差也为 null。
+- 注册、金额、ARPU 的相对变化率为 `(current-previous)*100/previous`，保留 1 位；对照为零/null 时 changeRate 为 null。付费率用 changeDiff 百分点差。
+- today/yesterday 的趋势读取原始主账号注册与成功支付，补齐 24 个小时；小时注册趋势不做身份证去重。还需核对 Mapper 的具体小时桶时区表达式。
+- 其他周期趋势来自日汇总/身份键，按天补零。金额查询固定 dedup_mode=0；人数随当前登录人的偏好。
+- 跨平台不去重人数需要给身份键加 source_db 前缀；身份证去重模式按身份键跨平台去重。具体 SQL 在 `TabSwReportDayKeyMapper.xml` 的 summary / summaryByDate 中。
+
+## 排行和关联预警
+
+- 注册 TOP 5 经 `ChannelTreeMetricsSupport.countRegisterByDisplayChannel` 汇总；实现前继续读取这个 helper 和对应 Mapper，不能把子渠道人数直接求和替代整棵树去重。
+- 充值 TOP 5 先按渠道取金额，再按 `resolveRootPromoteId` 归根；同平台分组，过滤 <=0，只取前五。按值降序、渠道 ID 升序，返回 rank、平台、渠道 ID/账号、value（保留两位）。
+- 关联预警不在画像 DTO 中，由前端独立请求 `/sw/alertRecord/list`，参数为 `platformCodes`、SW `businessId`、分页。
+- 旧 SDK 画像的预警仍按 SW 商务及平台筛选，没有单独按 platformBusierId 收窄；需按实际模板核对，不从基本资料 ID 推断范围。
+
+## 验证与实现要求
+
+沿用 DTO → service → biz → data，金额用精确计算，页面采用 Kra 图表/表格风格。不要在 stats 缺表时伪造零；没有任何绑定是已知空范围，可返回真实零和零趋势，有绑定但渠道/汇总未接入时保留可读取基本信息并明确未知指标。
+
+当前真实测试库仍缺完整业务表、平台/OA 别名尚未配齐。正向指标和权限测试继续用隔离数据与真实 TCP HTTP，真实 18000 实例用现有会话验证查询和缺数据场景。最终仍需用户确认旧库后复制验收。