AI Internal Tools Portal

可讓 AI 調用的內部工具服務，已接上娛樂城後台的三條核心查詢鏈：

• 會員總覽
• 輸贏報表 / 遊戲帳務
• 點數 / 金流報表

目前核心報表工具已包含：

• game_ledger_report
• cashflow_report
• deposit_report
• withdraw_report
• platform_credit_report
• agent_settlement_report
• agent_settlement_overview_report

目前系統採用：

• 手動登入後台一次
• 重用有效 session / cookie / csrf
• 直接抓後台 HTML 頁面
• 解析表格並輸出結構化資料
• 提供 HTTP 工具端點與 MCP 風格 list / call 入口

Current scope

• Discovery docs for member / game ledger / cashflow sources
• Shared contracts for AI-callable query and result schemas
• Session-based HTML adapters for internal backend pages
• Runtime health checks and session-ready detection
• MCP-style tools/list and tools/call

Workspace layout

• apps/server: backend service and tool / MCP entry point
• packages/shared: contracts, types, schemas
• packages/adapters: session HTTP client and internal HTML sources
• docs/discovery: source inventory and integration risk analysis
• docs/session-setup.md: session 取得與接線方式

Commands

• npm install
• npm run typecheck
• npm run build
• npm run start

Runtime endpoints

• GET /health
• GET /runtime-health
• GET /session/status
• POST /session/update
• GET /tools
• POST /tools/member-lookup
• POST /tools/agent-settlement-overview-report
• POST /tools/agent-settlement-report
• POST /tools/game-ledger-report
• POST /tools/cashflow-report
• POST /tools/deposit-report
• POST /tools/withdraw-report
• POST /tools/platform-credit-report
• GET /mcp/tools/list
• POST /mcp/tools/call

Quick start

1. Build and start

npm install
npm run build
npm run start

2. Check session status

curl http://localhost:3000/session/status

3. Update session without editing .env

curl -X POST http://localhost:3000/session/update `
  -H "Content-Type: application/json" `
  -d '{
    "ownerActorId":"support-lead-1",
    "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
    "csrfToken":"YOUR_CSRF_TOKEN",
    "cookiesHeader":"laravel_session=YOUR_SESSION; XSRF-TOKEN=YOUR_XSRF; remember_account=zerohua"
  }'

更新後再次確認：

curl http://localhost:3000/session/status

Common test paths

Member lookup by account

curl -X POST http://localhost:3000/tools/member-lookup `
  -H "Content-Type: application/json" `
  -H "x-actor-id: support-lead-1" `
  -H "x-role-ids: support-lead" `
  -H "x-query-reason: support-audit" `
  -d '{"lookupBy":"account","lookupValue":"test989tw5"}'

Single-member game ledger

curl -X POST http://localhost:3000/tools/game-ledger-report `
  -H "Content-Type: application/json" `
  -H "x-actor-id: operations-1" `
  -H "x-role-ids: operations-manager" `
  -H "x-query-reason: single-member-ledger" `
  -d '{"reportId":"game-ledger-win-loss","scopeMode":"self","scopeAccount":"test989tw5","platform":"all","beginAt":"2026-03-01 00:00:00","endAt":"2026-03-31 23:59:59","queryMode":"realtime"}'

Single-member cashflow

curl -X POST http://localhost:3000/tools/cashflow-report `
  -H "Content-Type: application/json" `
  -H "x-actor-id: finance-1" `
  -H "x-role-ids: finance-manager" `
  -H "x-query-reason: single-member-cashflow" `
  -d '{"reportId":"credit-ledger-summary","scopeMode":"self","scopeAccount":"test989tw5","transactionType":"deposit","beginAt":"2026-03-01 00:00:00","endAt":"2026-03-31 23:59:59","creditWay":"deposit"}'

Agent settlement report

curl -X POST http://localhost:3000/tools/agent-settlement-report `
  -H "Content-Type: application/json" `
  -H "x-actor-id: finance-1" `
  -H "x-role-ids: finance-manager" `
  -H "x-query-reason: monthly-reconciliation" `
  -d '{"parentAccount":"99jj99","beginAt":"2026-03-01 00:00:00","endAt":"2026-03-31 23:59:59"}'

Agent settlement overview report

curl -X POST http://localhost:3000/tools/agent-settlement-overview-report `
  -H "Content-Type: application/json" `
  -H "x-actor-id: finance-1" `
  -H "x-role-ids: finance-manager" `
  -H "x-query-reason: monthly-reconciliation" `
  -d '{"month":"2026-03"}'

MCP-style call

curl -X POST http://localhost:3000/mcp/tools/call `
  -H "Content-Type: application/json" `
  -H "x-actor-id: operations-1" `
  -H "x-role-ids: operations-manager" `
  -H "x-query-reason: monthly-reconciliation" `
  -d '{"name":"game_ledger_report","arguments":{"reportId":"game-ledger-win-loss","scopeMode":"self","scopeAccount":"test989tw5","platform":"all","beginAt":"2026-03-01 00:00:00","endAt":"2026-03-31 23:59:59","queryMode":"realtime"}}'

Notes

• lookupBy 必須是欄位類型，例如 account，不是直接填會員帳號
• session 過期時不用改 .env，直接重新登入後台後呼叫 /session/update
• createdAt / lastUsedAt 已由系統自動管理
• agent_settlement_report 是衍生型聚合工具，不是單一 backend URL 的直接 wrapper
• agent_settlement_overview_report 會回傳 橫式 rows + CSV 字串，適合整批代理月帳匯出
• 目前代理月結已可用，但若後台未來出現多頁代理名單，仍需要再補 pagination 驗證

Report tool guide

• 查輸贏 / 遊戲帳務 → game_ledger_report
• 查全部有投注結果的代理月帳 / CSV → agent_settlement_overview_report
• 查代理月結 → agent_settlement_report
• 查原層級點數 / 金流總表 → cashflow_report
• 查儲值 → deposit_report
• 查取款 → withdraw_report
• 查各遊戲平台點數 → platform_credit_report

Next docs

• docs/session-setup.md
• docs/deployment.md
• docs/ai-usage.md
• docs/agent-tool-catalog.md
• docs/report-tool-url-map.md
• docs/report-scope-cheatsheet.md
• docs/project-status.md
• docs/vps-session-helper.md