lotteryAdmin/AGENTS.md

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

玩家双模式（钱包 / 信用）

后端字段（players 表）：

字段	值	含义
funding_mode	wallet / credit	主站钱包 vs 信用盘
auth_source	main_site_sso / lottery_native	主站 SSO vs 彩票端账号

后台统一用法（不要各页手写 funding_mode === "credit"）：

• isCreditFundingPlayer(row) / playerUsesCredit(row) — 是否信用盘
• playerShowsTransferOrders(row) — 是否展示主站转账单
• playerFundingModeLabel / playerAuthSourceLabel — 文案
• playerBalanceCells — 列表余额列（信用用 major 额度，钱包用 minor）
• <PlayerFundingModeBadge /> / <PlayerLedgerSourceBadge /> — 表格徽章

模块边界：

• /admin/wallet/*：仅主站钱包流水与转账单
• /admin/settlement-center → 账务流水单页（筛选 + 分类 + 表格 + ⋯ 操作），合并信用/收付/调账/坏账；账单单页用分类筛选待确认/待收付等
• 玩家详情：按 funding_mode 切换 Tab（信用流水 / 钱包流水；信用盘隐藏转账单）

新增涉及玩家资金的页面时，先读 src/lib/admin-player-display.ts。

Learned User Preferences

• 占成/授信/回水/上限等数值字段用 AdminNumericStepper（± 步进 + 可手输），勿单独裸 input[type=number]。
• 对外文档（接入 + 后台运营手册）禁用 RBAC slug（如 prd.settlement.agent.manage）；对客户称「贵司」；排版忌 AI 感，正文对比度与字号可读优先。
• 文档 i18n：useTranslation 须显式 ns；returnObjects 列表用 Array.isArray 守卫；避免节名与表头 key 冲突（如 billStatus）。
• 运营页少堆 text-xs 说明与多层免责条；口径/默认范围合并进各模块一行 summary，勿叠加 filterPanel/queryHint/disclaimer 等小字（对账、报表中心已按此精简）。
• i18n 按语言懒加载，不要一次 import 三语全套。

Learned Workspace Facts

• 无接入站时依赖站点的页面展示 <AdminNoIntegrationSiteState />；仅 profile.is_super_admin 显示创建入口。
• 超管判定用登录态 is_super_admin，勿用站点角色或 admin_user_site_roles 绑定推断。
• 站点管理员（profile.site != null）代理 UI 绕过选中代理的 can_create_* 门控，按自身 manage 权限展示 Tab/操作；在代理下创建玩家须传 agent_node_id，勿默认挂根代理。
• 客户对外文档：/docs、/docs/integration、/docs/admin 公开免登录；读者为接入方与站点运营/代理；顶栏「管理后台」链 /admin；SSO 无登录换票、JWT+player/me、iframe data.token；Docs 侧栏 --docs-sticky-top；静态校验用 document.body.innerText。
• SettlementBillRow 无 currency_code；账单金额展示用玩家 default_currency。
• 浏览器 /api/v1/* 由 Next 转发到 LOTTERY_API_UPSTREAM；与本地 Postgres 对账前须确认 upstream 与所查库一致。
• Tanumo 联调/生产默认：H5 https://front.tanumo.com、API https://lotterylaravel.tanumo.com、管理端/文档 https://lotteryadmin.tanumo.com。
• 风控页默认：风险池仅显示有占用/高风险；单号详情可看占用来源；组合明细在注单详情页。
• 模块边界：对账中心=主站↔彩票钱包划转；报表中心=钱包盘经营分析；结算中心=信用账期占成/收付。
• 报表中心：默认近 30 天；盈亏类按 draws.business_date；金额读 API currency_code；导出仅后端 report-jobs 全量（按筛选，无需先预览）；注单盈亏≠信用账期结算。
• 对账中心：校验 transfer_orders vs 彩票 wallet_txns；差异 B 侧引用=彩票 wallet_txns 流水号；补单/冲正在钱包转账单页。