# lotterLaravel — Agent 须知

## 数据库：禁止擅自清空

**未经用户明确同意，不得执行：**

| 禁止 | 说明 |
|------|------|
| `php artisan migrate:fresh` | 删表重建，业务数据全失 |
| `php artisan db:wipe` | 清空所有表 |
| `php -r` / 脚本中的 `migrate:fresh`、`db:wipe` | 易误连 `.env` 开发库（如 `pgsql` / `lottery`） |

**可以做的：** `php artisan migrate`（增量）、`php artisan test`（走 `phpunit.xml` 的 SQLite 内存库）。

用户明确要求 `migrate:fresh` 时：先说明目标库名与数据将全部丢失，待用户确认后再执行。

详见 `.cursor/rules/database-destructive-commands.mdc`。

## 后台 RBAC

改 `app/Support/AdminAuthorizationRegistry.php` 后，在已有库执行 `php artisan lottery:admin-auth-sync --audit`（见 `docs/admin-rbac.md`）。`migrate:fresh --seed` 会走迁移内的 resync，一般不必再手动 sync。

## 双模式玩家（主站钱包 / 代理信用）

- `players.auth_source`：`main_site_sso`（主站 JWT）与 `lottery_native`（彩票端账号密码）。
- `players.funding_mode`：`wallet`（主站划转）与 `credit`（授信下注）；**禁止**仅用整站 `credit_line_mode` 代替玩家级判断，用 `PlayerFundingMode::usesCredit($player)`。
- 生产环境配置独立 `LOTTERY_NATIVE_JWT_SECRET`（勿与主站 SSO 混用）。

## 信用占成盘（代理账期结算）

- 业务真理源：`docs/信用占成盘代理系统设计说明文档.md`；实施路线：`docs/信用占成盘代理体系改造计划.md`。
- **代理账期**代码包：`App\Services\AgentSettlement\`（勿与彩票开奖 `App\Services\Settlement\` / `SettlementBatch` 混用）。
- **禁止**在生产关账路径使用 `DesignDocExample12` 硬编码账单；仅单元/Feature 测试可引用。
- 非 `testing` 环境关账受 `AGENT_SETTLEMENT_ALLOW_PRODUCTION_CLOSE`（默认 `true`）控制；预发可设为 `false` 门禁。
- 占成账单聚合必须读注单**快照**（`share_snapshot`），禁止按当前 `agent_profiles` 重算历史。

## 接入站点与超管

- 超管身份：`admin_users.is_super_admin`；**禁止**经 `admin_user_site_roles` 绑站；全库仅一名（DB partial unique index）。
- 零站点：`admin_sites` 可为 0；`defaultAdminSiteId()` 无站返回 null；超管仍可登录；需站点的写操作用 `requireDefaultAdminSiteId()` 抛 `no_integration_site`。
- 删接入站：DELETE API/UI；默认站亦可删（含最后一个）；仅删除仅绑 `site_admin_{code}` 的自动账号，**不得**删超管。

## Learned Workspace Facts

- 期号 `close_time`/`draw_time` UTC 存储；下注由 `DrawHallSnapshotBuilder` 实时判定；列表展示 DB `status`，详情 API 有 `hall_preview_status`。
- `AgentProfileCapabilityFilter` 仅作用于**已绑定代理节点**的经营账号（按档案 `can_create_*` 收紧权限）；**禁止**对无代理绑定的平台账号（如 `site_admin`）套用，否则会误剥 `prd.agent.manage` 等权限。绑定经营代理主账号统一绑 `slug=agent`，模板仅含 `prd.settlement.agent.view`；登录态对绑定代理主账号自动补足 `settlement.agent.manage`，实际操作仍受直属边 + 收款方校验。
- 站点管理员（`admin_user_site_roles` + `slug=site_admin`，且**未**绑 `admin_user_agents`）定位单站信用盘运营（代理树/玩家/结算/注单/报表）；不含开奖赔率等平台技术权限；开通一级代理线路仅超管（`prd.agent-line.provision`）。
- 结算中心登记收付/确认/坏账/补差 UI 需 `prd.settlement.agent.manage`（`canManage`）；仅 view 时操作区静默隐藏。另需账单 `status` ∈ confirmed/partial_paid/overdue 且 `unpaid_amount > 0`。**坏账核销 / 补差冲正** 另需未绑定代理（站点财务，`canFinanceAdjustments`），绑定代理仅有收付/确认。绑定代理账单可见范围：**玩家账单**仅直属玩家；**代理账单**仅 `owner=本节点` 或 `counterparty=本节点`；登记收付/确认仅可操作 **收款方**。
- 收付/调账/坏账后端落库 `payment_records`、`settlement_adjustments`；账期详情 **收付与调账** Tab 查操作台账，**账务流水** 仅玩家信用变动；单张账单详情内另有该账单的收付列表。
- 线上生产：已有库用 `php artisan lottery:db-init --no-demo`（含 RBAC sync）；常驻 `schedule:work`、`queue:work redis --queue=broadcasts:countdown,broadcasts,default`、`reverb:start`；`CACHE_STORE`/`QUEUE_CONNECTION` 须 Redis；先部署 lotterLaravel 再前端。
- `AgentProfileService::upsertForNode` PATCH 缺省键会写 0（占成/回水等），须按 `array_key_exists` 合并既有 profile。
- 代理仪表盘/账期「输赢」用本级 `share_profit`；开/关账期仅未绑定代理站点财务；根节点（`depth=0`）profile 仅超管可改。
- SSO 钱包盘：首次有效 JWT 调 `GET /api/v1/player/me` 按 `(site_code, site_player_id)` 自动建档；`username`/`nickname` 彩票生成 `nlotto******`，不从主站同步。
- 错误 8005（Account suspended）：站点不存在/停用或玩家冻结；**生产**按 `admin_sites` 验站点，`.env` `MAIN_SITE_*` 兜底仅 `local/testing`。
- 建站即生成 `sso_jwt_secret`/`wallet_api_key`；`main-site/` 须手动对齐 `MAIN_SITE_CODE` 与两把密钥（未设时默认 `main-site`），不会从后台自动同步；`wallet_api_url` 填主站钱包根 URL，勿填彩票 H5。