# 17 经营看板与风控（for AI Agents）

> 关联代码：internal/service/{cockpit,finance,risk}/、internal/model/{finance_log,commission_settlement,risk_log,risk_device,supplier}.go
> 管理端页面：web/src/views/sprint6/（cockpit/finance/risk/suppliers/announcements）、web/src/views/finance/breakeven/
> 权限：cockpit:read / finance:read / risk:* / supplier:*

====================================================================
1. 功能概述
====================================================================

经营层：运营驾驶舱（核心指标墙）、财务对账（日汇总）、盈亏平衡看板、CPS 佣金结算、供应商管理、跑马灯公告；风控层：风控中心（风险用户/日志/阈值配置）+ V8 五级风控引擎。多数页面为只读看板，操作集中在阈值调整、佣金结算、供应商维护、公告维护。

====================================================================
2. 底层逻辑
====================================================================

2.1 财务日汇总（finance Sweeper 10min → FinanceLog）
- 按日聚合：广告收入/佣金/奖品成本/服务器成本/净利润。

2.2 CPS 佣金结算（CommissionSettlement）
- 数据源：Order.CommissionRateBps + CPSClickID（幸运抽奖 CPS 商品跳转上报，见 07/12）+ CommissionSettledAt 去重。
- 流程：预览（preview）→ 生成结算单（settlements，OrderIDs JSON）→ 执行结算（settle）。
- 注意：佣金归因依赖 cps-click 上报链路完整；缺口会导致结算单为空。

2.3 V8 风控引擎（internal/service/risk/v8.go）+ RiskSvc
- L1 设备指纹（X-Device-Id 绑定 RiskDevice，识别群控）；L2 IP 滑窗（Redis 共享计数，阈值 risk.l2_ip_limit / risk.l2_window_seconds）；L3 行为（risk.l3_draw_threshold 抽奖频次）；L4 社交层（24h 重评，L4Sweeper）；L5 综合评分（risk.score_device / risk.score_behavior 权重）→ MpUser.RiskScore。
- RiskSvc.CheckAllowed 前置注入：抽奖参与（2108）、提现、兑换等。
- RiskLog 事件 6 种 + severity 1/2/3（info/warn/block）；处理状态人工标记。

2.4 供应商（Supplier）
- 奖品供应商档案：status 0 待审核/1 合作中/2 已停用。

2.5 跑马灯公告
- 全局启用公告（内容≤255/排序/起止时间）；小程序首页跑马灯组件消费。

====================================================================
3. 后台操作
====================================================================

3.1 运营驾驶舱 /sprint6/cockpit（Cockpit.vue，只读）
- 日期选择器（右上角，默认今天，非今天时显示「回到今天」按钮）→ 传 ?date=YYYY-MM-DD 给 API。
- 指标墙：今日抽奖/DAU/今日新增/次日留存/分享率/K 值（邀/新）+ 今日盈亏（广告/佣金/奖品成本/净利，单位元）+ 成本进度（文本：当日 X / 预算 Y 元 ｜ 预警 Z ‰ ｜ 熔断 W ‰）+ 待办（待发货订单/待审核供应商/未处理风控）+ 近 7 天趋势柱状图（CSS 柱状图，7 天抽奖数）。
- 数据源 GET /api/admin/cockpit/overview?date=。每日运营盯板入口。

3.2 财务对账 /sprint6/finance（Finance.vue，只读）
- 时间范围选择器（7/15/30/90 天单选切换）。
- 图表区：CSS 柱状图（每日抽奖数，>30 天时隐藏标签），图例。
- 每日明细表：日期/抽奖数/订单数/奖品成本（元）/净利（元），净利按正负着色（绿/红）。
- 数据源 GET /api/admin/finance/daily?days=。

3.3 盈亏平衡看板 /finance/breakeven（views/finance/breakeven/）
- 日期选择器（右上角，默认今天，非今天时显示「回到今天」按钮）→ 传 ?date=YYYY-MM-DD 给 API。
- 4 指标卡：月总收入/月净利/净利率/盈亏平衡 DAU vs 当前 DAU；收入结构表（广告充值/展示券/商城/抽奖报名/其他）。
- 可操作：月固定成本编辑保存（元输入，存分）。

3.4 CPS 佣金结算（驾驶舱-财务对账域，无独立菜单入口时经 API）
- GET /api/admin/finance/commission/preview        结算预览
- GET /api/admin/finance/commission/settlements    结算单列表
- POST /api/admin/finance/commission/settle        执行结算（权限 finance:read 以上）

3.5 风控中心 /sprint6/risk（RiskCenter.vue，3 Tab）
- 风险用户表：用户/风险分/团队等级/总抽奖数/操作（GET /api/admin/risk/users）。
- 风控日志表：同 /fission/risk 数据源。
- 阈值配置表单：risk.l2_ip_limit / risk.l2_window_seconds / risk.l3_draw_threshold / risk.score_device / risk.score_behavior → PUT /api/admin/risk/config。保存后引擎实时读取。

3.6 供应商 /sprint6/suppliers（Suppliers.vue）
- 筛选：关键词、状态。
- 表格列：ID/名称/联系人/手机/状态/操作。
- CRUD 弹窗：名称/联系人/电话/状态（0 待审核/1 合作中/2 已停用）/备注。
- 行操作：编辑、启用/禁用、删除。

3.7 跑马灯公告 /sprint6/announcements（Announcements.vue）
- 筛选：关键词、状态。
- 表格列：ID/内容/排序/启用/开始时间/结束时间/操作。
- CRUD 弹窗：内容（≤255）/排序/启用开关/起止时间。
- 行操作：编辑、启用/禁用、删除。

3.8 裂变域页面（/fission/*）数据侧见 14；风控日志在裂变运营与风控中心两处入口同源。

3.9 后台操作逻辑备注（隐藏约束，UI 不直接体现）
- 风控阈值调整即时生效：PUT /risk/config 保存后引擎下次 CheckAllowed 即读取新值；调低阈值会立即放大拦截面（影响参与/提现/兑换），调整前评估在线用户量。
- L2 IP 滑窗依赖 Redis：单机 SQLite 部署时计数为进程内近似（重启丢失），多实例必须配 Redis 否则同 IP 限流失效。
- 佣金结算去重：CommissionSettledAt 字段标记已结算订单，重复执行 settle 不会重复付款；但结算单生成后新增的已确认收货订单需下一周期才纳入。
- 供应商状态流转：0 待审核→1 合作中→2 已停用；「待审核」状态会进驾驶舱待办计数，及时审核避免奖品供应链阻塞。
- 跑马灯公告时间窗口：启用开关 + 起止时间共同控制展示；超出时间范围的公告即使启用也不在小程序首页展示。
- 风控日志处理标记：PUT /risk/logs/:id/handle 仅标记为「已处理」，不触发任何自动动作（如解封用户）；需配合其他操作。

====================================================================
4. 小程序端操作
====================================================================

无直接页面。风控对用户的表现：参与被拒（2108「您的账号操作受限」）、提现被拒、兑换拦截；跑马灯公告在首页 components/marquee 展示。

====================================================================
5. API 速查
====================================================================

GET  /api/admin/cockpit/overview                       驾驶舱指标（cockpit:read）
GET  /api/admin/finance/daily                          财务日汇总（finance:read）
GET|PUT /api/admin/finance/breakeven(/cost)            盈亏平衡看板/固定成本
GET  /api/admin/finance/cps-conversion                 CPS 转化监控
GET  /api/admin/finance/commission/preview|settlements；POST /api/admin/finance/commission/settle
GET  /api/admin/risk/users|logs；PUT /api/admin/risk/config；PUT /api/admin/risk/logs/:id/handle
GET|POST|PUT /api/admin/suppliers（supplier:*）
跑马灯公告 CRUD：GET/POST/PUT/DELETE /api/admin/drawbox/announcements（读=drawbox:prize:list，写=drawbox:config:update；handler 属 Sprint6 模块，页面在 /sprint6/announcements）

====================================================================
6. 注意事项
====================================================================

- 驾驶舱/财务看板金额前端展示为元（API 层自动 fen↔yuan 转换），后端存储仍为分。
- 风控阈值调低会立即放大拦截面（影响参与/提现），调整前评估在线用户量；severity=3 事件通常已有自动动作，处理时先看用户当前 RiskScore。
- L2 IP 滑窗依赖 Redis；单机 SQLite 部署时计数为进程内，多实例必须配 Redis，否则同 IP 限流失效。
- 佣金结算 settle 前先看 preview；CommissionSettledAt 去重保证重复结算不重复付，但结算单生成后新增订单需下一周期。
- 供应商「待审核」状态会进驾驶舱待办；及时审核避免奖品供应链阻塞。
