From 5e58c6bcf3ee5e6430a97091e4572a4e4affd78c Mon Sep 17 00:00:00 2001
From: Yvan <8574526@qq,com>
Date: Tue, 3 Nov 2026 20:57:51 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=E6=B8=A0=E9=81=93?=
 =?UTF-8?q?=E9=A1=B5=E9=9D=A2=E4=B8=8E=E7=BB=9F=E8=AE=A1=E8=BF=81=E7=A7=BB?=
 =?UTF-8?q?=E5=A5=91=E7=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/sw6-to-kra/channel-source-notes.md | 53 +++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 docs/sw6-to-kra/channel-source-notes.md

diff --git a/docs/sw6-to-kra/channel-source-notes.md b/docs/sw6-to-kra/channel-source-notes.md
new file mode 100644
index 0000000..22a5ca9
--- /dev/null
+++ b/docs/sw6-to-kra/channel-source-notes.md
@@ -0,0 +1,53 @@
+# 渠道列表与新增渠道：源码核对记录
+
+以下是下一批实现的契约，不代表已经完成。源码基线与 `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` 及其累计报表范围。实现前继续核对该方法及报表查询，不可按列表的直接注册/支付聚合臆造游戏分布。完整画像、报表汇总任务和预警生成任务仍属于后续范围。