# 渠道列表与新增渠道：源码核对记录

以下是实现核对契约，源码基线与 `implementation.md` 一致。列表、新增、绑定选项、游戏分布及渠道画像已接入并验证；报表构建任务及完整数据验收仍未完成。

## 页面

来源 `sw/web/src/views/BusMgmt/ChannelList.vue`、`components/AddChannelDrawer.vue`、`components/ChannelGameDrawer.vue`。

- 筛选：平台默认全选、商务账号、关键词、渠道层级、注册类型、锁定状态。实际关键词后端只查询渠道账号；旧占位文案“渠道账号 / 负责人姓名”与实现不一致。
- 列：平台、ID、渠道账号、渠道层级、归属商务、上级渠道、负责人、渠道类型、推广游戏、玩家数量、累计充值、锁定状态、画像。没有编辑入口。
- 列表的注册类型选项只有“个人 0 / 公会 1”，其余选项被注释；新增抽屉则是“个人 0 / 企业 1”，不能擅自根据其中一处统一名称。
- 状态筛选及列使用 `lockStatus`：0 正常、-1 已锁定、-2 解除合作，与渠道审批字段 `status` 不同。
- “添加渠道”只按按钮权限判断，旧代码没有额外要求三级商务。游戏商务下拉随平台变化加载，选项取平台商务 ID 并去重。
- 新增字段：平台、游戏商务、推广类型、渠道账号、密码。账号为 `[\u4e00-\u9fa5a-zA-Z0-9]{4,30}`，提交前 trim；密码原值保留，按 Java UTF-16 长度 6–15 校验。
- 推广游戏与画像均是右侧抽屉，必须同时传 `sourceDb` 与渠道 ID。游戏抽屉调用 `/system/promote/game-distribution`，累计口径，列为游戏、玩家数量、充值金额。画像尚待迁移，不能宣称渠道整个菜单完成。

## 列表权限和查询

来源 `PromoteServiceImpl`、`BusinessBindScopeServiceImpl`、`BusierAccountFilters`。

- 非超管查询本人及全部下级的已通过平台绑定，三级仅本人。列表自身并不会因全局“包含下级渠道”关闭而只列一级；该偏好用于指标聚合。
- 超管默认不限绑定；一旦指定 `busierUserId` 或商务账号关键词，必须按匹配绑定收窄。
- `busierUserId` 是指定用户本人绑定，不能套用预警筛选“该商务及全部下级”的语义。
- 商务账号关键词在 Java 中按忽略大小写的文字子串匹配平台商务账号或 SW 用户名。`%`、`_` 在这里是普通字符，不能随意变成 SQL 通配符。
- 平台商务与渠道以 `(source_db, busier_id)` 关联，跨平台同号不得混用。用户名展示为 `平台账号（SW用户名）`；两者相同或其中为空时不重复拼接。
- 支持平台、层级、注册类型、审批状态、锁定状态、渠道账号关键词。默认按创建时间、ID 倒序；新增稳定的平台排序可用于跨平台同号并列。

## 列表指标

来源 `PromoteListMetricsSupport`、`PromotePortraitScopeHelper` 和三个 Mapper。

- `gameCount`：`tab_promote_apply.status=1`，按该行渠道自身去重 `game_id`；不随包含下级扩展。
- `playerCount`：`tab_user` 主账号（`puid=0 OR puid IS NULL`）。不去重时累计行数；身份证去重时在整棵统计树内去重，空证件不计入。
- 身份证规范化仅 trim，并将末尾大写 X 改为小写 x，不能做额外证件合法性校验或把无证件用户按 ID 计入。
- `totalPayAmount`：`tab_spend.pay_status=1` 累计 `pay_amount`，不按身份证去重，也没有日期上限。
- 关闭包含下级、层级为空或 >=3：只统计当前渠道。二级：本级与 `parent_id=当前ID AND promote_level=3`。一级：本级与同平台 `top_promote_id=当前ID OR parent_id=当前ID`。
- 注意一级旧加载函数还会加载第二跳子渠道，但最终 `PromotePortraitScopeHelper` 再按 top/parent 条件过滤；不能仅看加载函数就扩大最终统计集合。
- 当前 sw7 缺业务表，列表本体及各指标要明确表示未接入，不能伪造真实零。

## 源平台创建事务

来源 `PlatformPromoteWriteServiceImpl`、`PlatformTabPromote`、`TabPromoteSettlementTime`、`TabPromoteBusinessMapper`。

1. 先验证当前用户可用的已通过绑定与目标平台商务匹配，再进入对应 `lx/hw/yq` 源库写入事务。
2. 源库 `tab_promote` 账号不得重复。密码为 `XiguPasswordUtils.cmfPassword` 格式，需要复用已有环境盐适配器，不能用 Kra 登录密码算法替换。
3. 新渠道 `status=-3`、`promote_level=1`、`parent_id=0`、`top_promote_id=0`、`game_ids2=''`，注册类型默认 0；时间为 Unix 秒。
4. 同事务创建 `tab_promote_settlement_time`：`time_type=0`、`day_period=7`，下一次结算为当前秒数加 7 天。
5. 游戏商务必须存在，原子追加新渠道 ID 到 `tab_promote_business.promote_ids`，避免并发覆盖；任一步失败整体回滚。
6. 返回新 ID 与 `sourceDb`，原成功文案提示“添加成功，数据同步到列表可能有延迟”。不直接制造主库同步副本，不在真实平台库创建测试渠道。

## 游戏分布的已核对依赖

游戏分布依赖 `PromotePortraitServiceImpl.buildGameDistribution`、`SwReportDayQueryServiceImpl` 和日汇总/身份键 Mapper。当前实现只列根渠道已通过的游戏，用同渠道统计树读取日汇总：人数对 metric=1 的 identity_key 去重，dedup_mode 随偏好；金额固定 dedup_mode=0。累计起点从当前人数模式的最早日汇总取得，缺失则使用上海当天，即使模式 0 有更早数据也不改写该起点。截止上海当天，排除未来日期。先将金额保留两位再按金额降序、游戏 ID 升序排列。

完整渠道画像已接入，规则及验证见 `channel-portrait-source-notes.md`。报表汇总任务、预警生成任务和最终实库验收仍属于后续范围。