webman-buildadmin/docs/渠道管理后台说明.md

渠道管理后台说明

1. 文档目的

说明 渠道管理（/admin/channel）页面的统计卡片、列表数据范围、操作按钮权限、下注记录弹窗与相关接口，便于运营配置权限与开发联调。

分红计算与代理树拆分口径见 分红说明文档.md。

---

2. 页面入口与统计卡片

卡片	说明
渠道总数	当前账号可读范围内渠道数量
启用渠道	status = 1 的渠道数
待分红渠道	carryover_balance > 0 的渠道数
待分红总额	上述渠道 carryover_balance 合计
公司总投注额	可读范围内全部玩家总投注（含未结算）；可点击打开全部下注记录（需 channel/index）
已分红金额	可读范围内渠道下，已发放佣金（agent_commission_record.status = 1）合计；可点击打开已分红记录弹窗（需 channel/index）

列表上方筛选：全部 / 有分红余额 / 无分红余额 / 仅启用 / 仅停用（前端 search 条件，不改变数据范围规则）。

---

3. 数据可见范围（只读）

由 app/common/service/AdminChannelScopeService.php 统一判定，列表与统计均遵守：

优先规则：只要绑定了渠道，就只能看绑定渠道（即使勾选了「查看所有渠道」）：

• 本人 admin.channel_id > 0，或
• 任一所属角色组 admin_group.channel_id > 0

上述情况合并去重后作为可读渠道 ID 列表。

全平台渠道范围（读、写一致，须同时满足）：

条件	说明
超管	权限含 *
未绑定任何渠道	账号 channel_id 为空且所有角色组 channel_id 为空
且拥有渠道模块基础权限	如 channel/index、channel/edit 等（含渠道菜单或任一 channel/* 按钮）

未绑定渠道且无上述渠道权限时，渠道列表为空。

读、写范围一致：绑定渠道 → 仅绑定渠道；未绑定且有渠道模块权限 → 全部渠道（含新增/编辑/删除/手动结算写库）。

其它菜单（用户、充值/提现订单、游玩记录、控制台等）在只读全平台时同样可不按 admin_id 收窄，逻辑与 Backend::hasGlobalReadScope() 一致。

---

4. 列表字段与操作

4.1 常用列

• 渠道标识、名称、代理模式、联营负结转、契约编号、结算周期等
• 直属投注额：该渠道名下全部玩家的总投注额（含未结算）；可点击打开该渠道直属玩家游戏下注记录（需 channel/index）
• 顶部统计卡片 公司总投注额：当前账号可见渠道范围内的真实码量合计（含未结算）；可点击打开全部下注记录明细（需 channel/index）
• 操作列：手动结算、编辑、删除（后两者受写权限约束）

4.2 操作按钮权限

按钮权限节点	名称	行为
channel/index	查看	列表、统计卡片点击、下注/分红记录弹窗
channel/manualSettle	手动结算	操作列；预览并提交渠道结算（见 §5）
channel/batchSettlePending	一键批量结算	批量结算当前账号可写范围内启用渠道
channel/add / edit / del	增删改	须对目标渠道具备写权限

角色组在 权限管理 → 角色组 中勾选对应按钮；保存后管理员需重新登录以刷新前端 authNode。

---

5. 手动结算

• 接口：GET /admin/channel/manualSettlePreview?id={channelId}、POST /admin/channel/manualSettle
• 权限：超管，或拥有 channel/manualSettle 且目标渠道在可读范围内
• 逻辑：与超管结算相同，调用 ChannelSettlementService::settleBySuperAdmin，结算即按代理树发放至 admin_wallet
• 周期：上次结算结束时间 ~ 当前时间；金额来自期内 已结算 游玩记录（game_play_record.status = 2）
• 手续费：渠道字段 settlement_handling_fee 为默认手续费比例(%)；计算公式：手续费金额 = 费前佣金 × 比例 / 100；预览弹窗可按代理修改比例，提交时 commission_split[].handling_fee_rate 回传；实发 = 费前佣金 − 手续费金额，记录表 handling_fee 存扣除金额
• 分配预览：按代理树先序展示，列含层级缩进、结算基数（上级分给该代理的金额）、分配比例、费前佣金、手续费、实发佣金
• 批量：POST /admin/channel/batchSettlePending 需 channel/batchSettlePending；仅结算当前账号可写范围内启用渠道

---

6. 下注记录弹窗

两种入口共用同一套 UI 与筛选（接口不同）：

入口	接口	数据范围
直属投注额（列点击）	GET /admin/channel/directBetRecordList	该渠道名下玩家 全部 游玩记录（含未结算）
公司总投注额（顶部卡片）	GET /admin/channel/companyBetRecordList	当前账号可见渠道范围内 全部 游玩记录（含未结算）

6.1 顶部统计（Card）

• 总笔数、总投注额、总中奖额（随筛选条件重算）

6.2 列表列

游戏期号、玩家名、渠道、选号、中奖号码、中奖状态（已中奖 / 未中奖 / 待开奖）、投注金额、玩家中奖金额（含 jackpot_extra_amount）。

6.3 筛选参数（GET）

参数	说明
channel_id	必填
page / limit	分页，默认 1 / 20，最大 200
period_no	期号模糊（pr.period_no 或 game_record.period_no）
user_keyword	玩家名或手机号模糊
result_number	开奖号码精确匹配
pick_number	选号模糊（匹配 pick_numbers JSON 文本）
win_hit	won / lost / pending（与列表中奖状态一致）

6.4 移动端适配

• 弹窗宽度约 92% 视口，内容区可纵向滚动（勿使用 ba-operate-dialog 固定高度）
• 统计 Card 一行三列；筛选项纵向铺满；表格区域可横向滑动

---

7. 已分红记录弹窗

• 接口：GET /admin/channel/dividendRecordList
• 权限：channel/index
• 字段：结算单号、渠道名、代理账号、分红金额、结算周期、发放时间等

---

8. 相关接口一览

方法	路径	说明
GET	/admin/channel/index	渠道列表
GET	/admin/channel/settleStats	顶部统计卡片
GET	/admin/channel/directBetRecordList	直属下注记录
GET	/admin/channel/settlementBetRecordList	分红口径下注记录
GET	/admin/channel/dividendRecordList	已分红记录
GET	/admin/channel/manualSettlePreview	手动结算预览
POST	/admin/channel/manualSettle	提交手动结算
POST	/admin/channel/batchSettlePending	批量结算（可写渠道范围）

---

9. 相关代码

模块	路径
渠道控制器	app/admin/controller/Channel.php
数据范围	app/common/service/AdminChannelScopeService.php
渠道结算	app/common/service/ChannelSettlementService.php
前端页面	web/src/views/backend/channel/index.vue
权限迁移	database/migrations/20260530120000_*、20260530130000_*

---

10. 变更记录

日期	说明
2026-05-30	新增：查看所有渠道、下注/分红查看按钮；下注记录弹窗列与筛选；移动端弹窗适配
2026-05-30	手动结算：拥有 channel/manualSettle 且渠道可读即可操作（不再仅限超管展示按钮）
2026-05-30	修复：账号已设 channel_id 时不再因角色组未绑渠道而误判为全平台可见
2026-05-30	移除 channel/viewAllChannels；未绑定渠道且拥有渠道模块基础权限时读写全平台渠道