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）。

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（API 接入）、/docs/admin（后台运营手册），均公开免 /admin 登录；读者为接入方技术与站点运营/代理，非内部运维；旧 /admin/docs/integration-guide 重定向 /docs/integration；顶栏「管理后台」链 /admin（勿 /admin/login）。
• SettlementBillRow 无 currency_code；账单金额展示用玩家 default_currency。
• 浏览器 /api/v1/* 由 Next 转发到 LOTTERY_API_UPSTREAM；与本地 Postgres 对账前须确认 upstream 与所查库一致。
• 接入文档页静态内容校验用 document.body.innerText；DocCode 非裸 <pre>/<code>，勿只查 code 选择器。
• Docs 侧栏粘性定位用 CSS 变量 --docs-sticky-top（含顶栏/header 偏移）。
• Tanumo 联调/生产默认：H5 https://front.tanumo.com、API https://lotterylaravel.tanumo.com、管理端/文档 https://lotteryadmin.tanumo.com。
• 接入文档 SSO：无「登录换票」；主站 JWT 直传 H5/iframe，GET /api/v1/player/me 自动建档；iframe 约定 token 在顶层 data.token；勿引用 main-site/monorepo 等内部仓库路径。
• 风控页默认：风险池仅显示有占用/高风险；单号详情可看占用来源；组合明细在注单详情页。