Files

kang 3a59cc3f42 feat: enhance reporting and dashboard functionalities

- Updated AGENTS.md to clarify SSO wallet integration and error handling for account status.
- Refactored date handling in AdminReportQueryService and related classes to use precise date filtering for financial reports.
- Improved query logic in AdminDashboardSnapshotBuilder, AgentDashboardOverviewBuilder, and SiteDashboardOverviewBuilder to ensure accurate activity statistics based on business dates.

2026-06-16 14:18:56 +08:00

5.4 KiB

Raw Blame History

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******；建站生成 sso_jwt_secret/wallet_api_key，main-site/ 须手动对齐；wallet_api_url 填主站钱包根 URL；8005=站点不存在/停用或玩家冻结（生产按 admin_sites 验站）。
报表 AdminReportQueryService：未传日期默认近 30 天；玩家/玩法/回水按 draws.business_date；SQLite 对 business_date 用 whereDate 勿 whereBetween（列可能带时间戳）；日盈利过滤零活动日。

5.4 KiB Raw Blame History Unescape Escape