kra-new/docs/sw6-to-kra/channel-source-notes.md

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

以下是实现核对契约，源码基线与 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。报表汇总任务、预警生成任务和最终实库验收仍属于后续范围。