<!-- 4459211d-83e4-4bc9-9a52-2fc0b9f1f467 -->
---
todos:
  - id: "arch"
    content: "修订第 4.2/8/8.1-8.4/21/22/26/27 章：app/tenant 改为 webman 多应用 + 继承 TenantController + 注解挂中间件 + 前端 App-Id 说明"
    status: pending
  - id: "datascope"
    content: "修订第 9.1-9.3 章：删除 TenantDataScopeService，改复用 TenantController 的 organization/channels/restrictRequestSourceByChannels，新增 channels==['all'] 防御"
    status: pending
  - id: "orders"
    content: "修订第 3/4.3/6/13.1/14.1/14.7/22.4/22.5/26/27 章：订单改直连 s_pay + Logic 层 org+source 过滤与字段白名单，补单表无归档限制"
    status: pending
  - id: "firstpay"
    content: "修订第 10.2 章并波及 10.6/11.3/11.4：去掉今日首充金额，处理 frist_pay_cash_amount 引用"
    status: pending
  - id: "enum"
    content: "修订第 14.4 审核状态补 0/1/2/3；新增 slot_all.user 与 gm_stat_summary 字段核对说明"
    status: pending
  - id: "crossrepo"
    content: "修订第 12.10/15/16 章：DDL/索引/PHPDoc 标注为跨团队协调项，不在 saas6.x 执行"
    status: pending
isProject: false
---
# 商户后台文档修订计划

仅修订 [saas6.x/docs/商户后台.md](saas6.x/docs/商户后台.md)，不改任何代码。依据已确认的 5 项决策对齐现网实现。

## 已确认决策（贯穿全文）

- 鉴权与数据权限：复用 Saimulti tenant 体系，控制器继承 `plugin\saimulti\basic\TenantController`，`plugin/saimulti` 一行不改。
- 应用形态：真正的 webman 多应用目录 `server/app/tenant/`（命名空间 `app\tenant\`），默认路由 `/tenant/*`。
- 订单数据：复用现网直连 `s_pay` 的 `app\model\RechargeOrderModel` / `WithdrawalOrderModel`，在 `app/tenant` Logic 层强制 `organization + source` 过滤并裁敏感字段；不走 slot-sdk、不改 slot-pay。
- 渠道隔离：数据治理 + 代码防御双管（商户配真实渠道、禁 `['all']`；商户后台遇 `channels==['all']` 拒绝/返回空）。
- 首页去掉"今日首充金额"，保留首充人数。

## 具体章节改动

### 1. 架构归属（第 4.2、8、8.1-8.4、21、22、26、27 章）
- 把 `server/app/tenant` 明确为 **webman 多应用**（`app\tenant\` 命名空间，自动路由 `/tenant/...`），并说明依据：框架 `App::guessControllerAction()` 支持 `app\<app>\controller\...`。
- 新增"基类约定"：`app\tenant\controller\MerchantBaseController extends plugin\saimulti\basic\TenantController`，基类用 `#[Middleware(CheckTenantLogin::class, CheckTenantAuth::class, TenantLog::class)]` 挂鉴权（与现网 [FundController](saas6.x/server/app/controller/fund/FundController.php) 同构）。
- 说明前端 `tenant-vue` 调 `/tenant/*` 需带 `Authorization` + `App-Id`（`TenantController::checkSite()` 校验）。
- 权限用方法注解 `#[Permission('名称','slug')]`，由 `CheckTenantAuth` 校验。

### 2. 数据权限：删除 TenantDataScopeService（第 9.1-9.3 章）
- 删除自建 `TenantDataScopeService`，改为复用 [TenantController](saas6.x/server/plugin/saimulti/basic/TenantController.php) 已有的 `$this->organization`、`$this->channels`、`restrictRequestSourceByChannels()`，渠道展开复用 `SystemOrganizationLogic::resolveEffectiveChannelCodes()`。
- 新增 `channels==['all']` 防御要求（商户后台拒绝/返回空）。

### 3. 订单改直连 s_pay（第 3、4.3、6、13.1、14.1、14.7、22.4、22.5、26、27 章）
- 把"slot-sdk → slot-pay / 禁直连 s_pay"改为"复用现网 `s_pay` 直连模型，Logic 层强制 `organization+source` + 字段白名单"。
- 14.7 敏感字段：由"在 slot-pay 端剔除"改为"在 `app/tenant` Logic 层 `field()` 白名单只选可展示字段"。
- 补充限制说明：现网 `RechargeOrderModel`/`WithdrawalOrderModel` 为 `s_pay` 单表、不含按月归档表，跨月历史订单查询范围受限。

### 4. 首页首充金额（第 10.2 章，并波及 10.6 / 11.3 / 11.4）
- 删除 10.2 "今日首充金额 SUM(frist_pay_cash_amount)"行，保留首充人数 `first_recharge_num`。
- 同步标注：凡引用 `frist_pay_cash_amount`（市场明细 11.3、汇总 11.4 的"首充金额"）首期一并去除或标注脏值风险，保留首充人数与首充转化率。

### 5. 枚举与口径修正
- 14.4 审核状态补齐为实表 4 值：0 未审核 / 1 通过 / 2 拒绝退钱 / 3 拒绝扣钱（对齐 [WithdrawalOrderModel](saas6.x/server/app/model/WithdrawalOrderModel.php)）。
- 新增"字段核对"说明：`slot_all.user` 确含 `organization`/`currency`/`first_pay_date`（建表与 alter 已证实）；`gm_stat_summary` 确含 `refund_amount`/`recharge_channel_fee`/`withdrawal_channel_fee`（Summary 脚本写入）。

### 6. 跨仓库事项标注（第 12.10、15、16 章）
- 把 `gm_stat_summary` 加 `uk_source_date`、改 `create_time`/加 `update_time`、`slot_all.user` 与 `recharge_order/withdrawal_order` 加索引、以及相关 Model PHPDoc 补全，统一标注为 **跨团队协调项**（库属 `s_statistics`/`slot_all`/`s_pay`，由 slot-console/slot-user/slot-pay 执行），按工作区规则不在 saas6.x 仓库改。

## 不做
- 不写任何 PHP/前端代码。
- 不改 `plugin/saimulti/**` 及 slot-* 仓库。
- 不执行任何 DDL。