kang
5b6d4cb74d
- Updated AGENTS.md to clarify agent account restrictions and permissions. - Implemented checks in AgentNodeAdminUserStoreController and AgentNodeRoleStoreController to restrict admin user and role creation to the agent's own node. - Enhanced validation in AdminPlayerStoreController and AdminPlayerUpdateController to enforce credit limit and rebate rate rules based on player funding mode. - Refactored various request classes to utilize shared admin account field rules for consistency. - Improved error handling in services related to credit allocation and rebate limits to ensure proper validation and messaging.
5.3 KiB
5.3 KiB
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 存储与比较；后台展示转浏览器本地时区，创建/编辑表单提交前须转回 UTC。 - 下注是否开放由
DrawHallSnapshotBuilder::isBettingOpen()/effectiveHallDisplayStatus()实时判定，不只看draws.status。 - 后台期号列表展示数据库
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=本节点（不含下级玩家的账单、不含更深层代理链）。账务流水/账期 pipeline 的玩家维度同样仅直属玩家。站点财务/超管仍见全站。 - 登记收付/确认：绑定代理仅可操作 收款方（玩家账单=直属 counterparty；代理账单=按 net_amount 方向的 payee）。上级不能代登下级玩家收付，下级也不能代登向上级的代理账单。
- 收付/调账/坏账后端落库
payment_records、settlement_adjustments；账期详情 收付与调账 Tab 查操作台账，账务流水 仅玩家信用变动；单张账单详情内另有该账单的收付列表。 - 代理仪表盘/账期列表「输赢」用本级占成（
share_profit），不可看platform_pnl全站报表。 - 开/关账期仅未绑定代理的站点财务（
canManagePeriods = canOperateBills && boundAgent === null）。 - 一级代理 profile：每站唯一根节点（
depth=0）的占成/授信/回水仅超管可改（AdminAgentScope::nodeProfileEditableBy）；站点管理员与一级代理账号对根节点 profile API 为 403；下级仍由上级代理维护。