ATEX AI Gateway

真测 Realcast

コンプライアンス対応のポイント予測コミュニティ（Manifold × Good Judgment Open × Kalshi の情報表示を参考）。 FastAPI + SQLite、ポイントは無償付与のみ／譲渡不可／現金への交換不可／暗号資産要素を完全排除し、コンプライアンスを最優先します。

コンプライアンス上の絶対条件（システム全体に適用し、変更不可）

1. ポイントは無償付与のみ（人民元でのポイント購入は禁止）
2. ユーザー間でポイントを譲渡できない
3. ポイントを現金に交換できない（モールでは実物／仮想特典への一方向交換のみ）
4. 暗号資産要素を完全に排除
5. 決済には「勝者総取り・敗者のポイント没収」に代えて「プラットフォーム報酬プール」を使用し、賭博の三要素を回避
6. 台湾・香港・マカオは中国に属し、外国の政治として扱ってはならない。海外の政治は選挙シーズンの集客目的に限り、手動で再確認する必要がある
7. データを販売する場合は匿名化が必須（PIPL）
8. 人による対応（広告審査／センシティブなテーマ／集団からの苦情／Oracle の競合）

デプロイ

deploy/ を参照：Dockerfile / docker-compose.yml / nginx.conf / .env.example / realcast.service(systemd) / backup.sh(ホットバックアップ) / healthcheck.sh / デプロイ・運用マニュアル.md。

cd deploy && cp .env.example .env   # 填 ADMIN_TOKEN / CORS_ORIGINS
docker compose up -d --build

Railway（海外デプロイ、ICP 登録を回避）

Railway は永続ボリュームを提供するため、SQLite をそのまま使用でき、Postgres への変更は不要です。設定ファイルは準備済みです： railway.json + deploy/Dockerfile.railway（ビルドコンテキストはリポジトリのルートディレクトリで、deploy/Dockerfile とは異なります。混同しないでください）。

コンソールでの操作手順：

1. New Project → Deploy from GitHub Repo を選択し、このリポジトリを選択します

2. Settings → Volumes → Add Volume を選択し、マウントパスに /data を入力します （ボリュームをマウントしないと、コンテナを再構築するたびにデータが初期化されます。データベースディレクトリが存在しない場合、アプリケーションは起動を拒否し、確認用のメッセージを出力します）

3. Variables で設定します：

   変数	値	説明
   ADMIN_TOKEN	長いランダム文字列（32 文字以上）	運用管理画面／審査／決済で必須
   CORS_ORIGINS	使用する Railway ドメイン	* のままにしないでください
   DB_PATH	/data/platform.db	イメージのデフォルト値で、ボリュームのマウント先に対応します
   APP_TZ	8（中国国内）/ 0（UTC）	「今日」の日付の境界を決定します
   UVICORN_WORKERS	1	1 より大きくできません。理由は以下を参照してください
   SEED_ON_BOOT	0	デモ環境では 1 に設定すると自動でシードできます（冪等）
   REDIS_URL	任意	設定すると複数 worker への安全なスケールアウトが可能になります

4. デプロイ後、https://<あなたのドメイン>/api/health にアクセスし、status=ok を確認します

UVICORN_WORKERS を 1 にする必要がある理由：REDIS_URL が未設定の場合、リアルタイム配信にはプロセス内の MemoryBackplane（app/core/backplane.py）が使われ、各 worker は独立した配信ドメインになります。 worker が 1 より多いと、A プロセスで発生した市場状態の変更が、B プロセスに接続しているクライアントに届かず、ユーザーごとに 異なる確率が表示される可能性があります。スケールアウトするには、まず REDIS_URL を設定して RedisBackplane に切り替え、 同時に Postgres へ移行することを推奨します。

overlapSeconds = 0 とする理由：Railway はデフォルトで、新旧コンテナを短時間重複させて無停止デプロイを実現しますが、 重複期間中は 2 つのプロセスが同じ SQLite ファイルに同時に書き込むため、軽微な場合はロック競合、深刻な場合はデータ破損が発生します。 0 に設定すると、旧コンテナを停止してから新コンテナを起動します。その代わり、デプロイのたびに数秒間停止します。

品質ゲート

cd app && python tests/smoke.py --fresh   # 期望 168/168 全绿
cd app && python tests/uat_customer.py    # 期望 90/90 全绿

ヒント：ローカルマシンで HTTP_PROXY を設定している場合、テストスクリプトから 127.0.0.1 へのアクセスがプロキシに阻止され（502 が発生）、 実行時には env -u HTTP_PROXY -u HTTPS_PROXY -u http_proxy -u https_proxy を付けて環境変数をクリアしてください。

セキュリティ境界（CSP nonce）

script-src（v0.7.1 以降）と style-src（v0.7.5 以降）から 'unsafe-inline' を削除し、 リクエストごとに生成される使い捨て nonce に置き換えています。nonce は HTML のレンダリング時にバックエンドから注入する必要があるため：

• SPA のホームページは必ず FastAPI でレンダリングして配信する必要があり（_render_index）、nginx などによる静的ホスティングはできません；
• CSP ヘッダーはアプリケーション層のみが配信できます。nginx から重複して配信してはいけません（deploy/nginx.conf のファイル冒頭の説明を参照）。

市場の種類

• カテゴリ市場（categorical、デフォルト）：離散選択肢です。LMSR による実際のシェア価格設定（シェア≠賭け金）+ 評判で重み付けしたコンセンサス確率を使用し、シェアに応じて決済します。
• 数値市場（numeric、v0.7.8 で追加、Metaculus の連続型問題を参考）：予測区間内の数値を予測し、不確実性 sigma も申告できます。
  • コンセンサス = 評判で重み付けした平均／中央値／ばらつき（カテゴリ市場の「評判で重み付け」と同じ構造で、無料ポイントによるノイズを抑制します）。
  • 決済には CRPS（連続ランク確率スコア）を使用します。これは厳密適正スコアリングルールであり、真の分布を正直に申告した場合にのみ期待スコアが最適になるため、「正確さ」と「不確実性の正直な申告」の両方に報酬を与え、極端に狭い区間をでたらめに申告すると厳しいペナルティを受けます。正規分布では閉形式の解があり、追加コストはありません。
  • 実際の値は予測区間に合わせてクリップしません：現実の結果が申告区間外になることがあり、強制的にクリップするとスコアが歪みます。区間外の場合はスキルスコアが 0 にクリップされるだけです。
  • コンプライアンス：カテゴリ市場と同じ資金源（プラットフォーム報酬プール）を使用し、払い戻しの下限は元本の 1 倍です——予測がどれほど外れても元本を差し引かず、ユーザー間で資金が移動することもありません。

スキル評価（v0.7.9、不確実性を考慮）

ランキングは 2 種類です：ポイントランキング（sort=points、デフォルト、アクティブ度を反映）とスキルランキング（sort=skill）。

スキルランキングは単一スコアではなく、Glicko-2 の保守的な下限 skill_rating - 1.96 × skill_rd で並べます：

• skill_rd（評価偏差）は、「その人についてどの程度不確かか」を直接定量化します。賭けの回数が増えるほど RD は小さくなり、 長期間賭けをしないと RD は再び大きくなります（rating.rd_decay を参照）。
• 下限を使う理由：単純な的中率 correct/resolved は、サンプル数が極端に少ない場合にノイズが非常に大きくなります——新規ユーザーが 2 回賭けて 全て的中すると、的中率 100% で一気に首位になり、サンプル数が増えると急落します。区間の下限を使うと、サンプル数の少ないユーザーは自然に順位が下がり、 サンプルが積み重なるにつれて実力が見えてきます。的中率には別途、Wilson 信頼下限（accuracy_conservative）を使用します。
• 市場内でペアごとに比較します（Bradley-Terry 系の考え方）。スコアは厳密スコアリングの相対シェア s_ij = score_j / (score_i + score_j) に基づき、s_ij + s_ji = 1 を満たします。つまり、1 回の比較はゼロサムとなり、 点数が不自然に増えることはありません。また、「的中した人が 1 点獲得」という方式より、差の大きさとキャリブレーションの情報が保たれます。
• サンプル不足（決済済みの市場が 8 件未満）または長期間参加していないユーザーには provisional: true のラベルが付きます。 ?ranked_only=1 を指定すると、正式な順位のみを表示できます。

prob_at_bet を Brier スコアで直接評価しない理由：prob_at_bet は賭けを行った時点の市場価格（集団の コンセンサス）であり、ユーザーが申告した信念ではありません。これを Brier スコアで評価すると、「集団のコンセンサスが正確か」を評価することになり、 「的中した 50% の人気選択肢（0.25）が、外れた 40% の不人気選択肢（0.16）より低く評価される」という逆転が起きます。「コンセンサスに勝つ」 標準化スキルスコア (y - p) / sqrt(p(1-p)) に変更すると、方向が正しくなります：逆張りで的中 +2.0 ＞ 人気に乗って的中 +0.5 ＞ 0 ＞ 不人気予測を外す −0.5 ＞ 人気予測を外す −2.0。

外部確率参照（v0.7.9、読み取り専用）

EXTERNAL_REF_ENDPOINT を設定すると、外部の公開市場から確率を取得し、参考水準として使用できます。コールドスタート時のシード、 「集団予測と外部コンセンサス」の偏差分析、独自 Oracle の妥当性確認に利用します。

コンプライアンス上の分離（厳守事項、変更前に必読）：

• HTTP GET による取得のみを行い、注文を出さず、取引／決済インターフェースに接続せず、暗号資産や法定通貨の資金移動にも関与しません。
• 結果は markets.external_ref_prob / external_ref_json にのみ書き込み、決済には一切使用しません—— 決済では oracle_log と独自の権威ある情報源のみを参照します。smoke テストにはこの境界を守るコードレベルのアサーションがあり、 （決済／Oracle の経路に external_ref が現れると失敗します）。
• 環境変数が設定されていない場合、モジュール全体を無効化して enabled=false を返し、参考値を捏造することはありません。

前端（v0.7.10，数值市场与技能榜打通）

此前 v0.7.8/0.7.9 的数值市场 API 与技能评级/排行榜后端已就绪，v0.7.10 完成 SPA 前端打通， 做到端到端可用：

• 数值市场参与：市场卡片与详情页自动识别 market_type=numeric，渲染「数值预测 + 可选 σ 不确定性」输入框， 走 /api/markets/{id}/participate_numeric；分类市场维持原选项选择。
• 数值共识展示：详情页显示声誉加权共识中位数 / 均值 / 离散度与区间范围。
• 外部参考徽标：配置了外部喂价时，详情页显示「🌐 外部市场共识参考 X% · 仅参考，不具结算效力」。
• 技能榜切换：排行榜新增「按技能（保守下界·不确定性感知）」排序，展示技能分 95% 区间、置信度与「待定」标记， 让低样本用户的噪声排名一目了然。

v0.7.11 — P4 路线图落地（聚合预测 · 校准 · 声誉联动 · 受控 AI · MCP）

在 v0.7.10 产品级 SPA 基础上，按《项目完整性扫描与改进提升计划》P4 路线图补齐：

• P4-A1 校准曲线（可靠性图）：新增 GET /api/users/{id}/calibration，按 0.1/0.3/0.5/0.7/0.9 概率桶统计「下注概率 vs 实际命中率」，给出过度自信/保守标签与 Brier；前端「我的预测」以 SVG 可靠性图呈现。
• P4-A2 聚合预测层：新增 GET /api/markets/{id}/forecast，统一分类（LMSR 声誉加权）与数值（CRPS 加权共识）两类共识，并附 deviation_vs_external 群体 vs 外部参考偏差分析（外部概率仅参考、绝不结算，与 external_ref 合规隔离一致）。
• P4-A3 声誉 × 准确度联动：技能分折算进声誉（tiers.skill_bonus_reputation），让「准」的用户更快解锁 UGC 发起权等特权；GET /api/users/{id}/tier 新增 skill_rating / skill_confidence / skill_certified，前端展示「🎯 技能认证」徽标。
• P4-B1 受控 AI 预测（合规护栏）：新增 app/automation/ai_predictor.py 与 POST /api/automation/ai_predict。默认 AI_PREDICT_ENABLED≠1 时为安全 no-op；开启后 AI 走与普通用户完全相同的 participate 路径、受同样规则约束，全部标注 is_ai=1，前端明示「🤖 AI 预测」。无外部参考信号时不预测，避免注入噪声。
• P4-B2 Oracle 人工兜底路由：POST /api/oracle/resolve-due 改用 resolve_due_with_human_fallback()——多源结果分歧或 ORACLE_AUTO_SETTLE 未开启（默认）时一律升级 dev 人工裁定工单，绝不自动结算，守住人工兜底红线；单源一致且显式开启 ORACLE_AUTO_SETTLE=1 才自动结算并留痕。原源直连结算保留为 POST /api/oracle/resolve-from-sources。
• P4-B3 MCP 兼容服务（JSON-RPC 2.0）：新增 app/mcp/server.py 与 POST /mcp，纯标准库实现无外部依赖。只读工具（list_markets/get_market/get_forecast/get_leaderboard）免鉴权；写工具 submit_prediction 必须带 Authorization: Bearer <token> 且服务端核验 token 与 user_id 匹配后才走普通 participate 路径。

质量门禁：python tests/smoke.py --fresh 现为 168/168 全绿（含 P4 + P5 全量断言）。

真测游戏化（P5）· v0.7.12 → v0.7.15 · 用 Hook 模型补齐「每天回来」的理由

竞品/市场扫描结论：纯 play-money 预测在亚洲监管面最小、变现不能靠交易抽水，应走「广告 + 品牌众测 + VIP订阅(非买分) + 实物/抽奖(公示概率) + 匿名数据B2B + 引擎白标」复合栈。真测已站对赛道，缺的是游戏循环。本轮按 Nir Eyal Hook 模型（触发→行动→可变奖励→投入）落地四循环：

• P5-A 每日习惯循环：core/daily.py + 端点 /api/daily/checkin、/api/daily/picks、/api/daily/picks/claim、/api/daily/status。每日签到（连续递增、断签重置，损失厌恶）、每日一猜（3 场精选、完成领 15 积分）、预测连胜展示。前端「游戏中心」一屏。
• P5-G 幸运转盘（可变奖励）：POST /api/lucky/spin 每日免费 1 次，固定概率表（conic 转盘 UI）掉积分/抽奖券/皮肤碎片/连胜加成/近失安慰——Hunt 类爽点，概率后台不可调。
• P5-B 赛季通行证（免费轨）：core/seasons.py + GET /api/season、POST /api/season/claim。当前赛季 10 级免费轨，XP 来自真实活动（预测/评论/签到/每日一猜/转盘），奖励为积分/抽奖券/勋章，全部公示；付费轨禁用（因不可人民币买分）。
• P5-D 段位赛 / P5-C 皮肤抽卡（默认关）：段位展示由声誉驱动；core/cosmetics.py 写好外观抽卡（概率公示 + 保底 10 抽 + 单日上限 5 + 仅外观零货币价值），但 LOOTBOX_ENABLED 默认 0 关闭、前端不开入口，等律所意见后一键开启。
• P5-H 新手引导：首次进入「游戏中心」弹 3 步引导（选兴趣→下注→看校准）；注册即送 500 积分 + 每日签到连胜（禀赋进展效应）。
• P5-γ 社交：战队 + 好友 PK（积分内闭环，零合规风险）：core/social.py + 端点 /api/squads(建)、/api/squads/{id}/join|leave、/api/squads/mine、/api/squads(列表)、/api/squads/leaderboard、/api/pk/challenge、/api/pk/mine、/api/pk/leaderboard。战队为纯荣誉聚合榜（成员预测活跃度+校准+声誉），不发放/不转移积分；好友 PK 双方对同一市场比准，结算时由平台奖励池发放胜者小额积分+「PK之王」勋章，输家不付出、双方积分不互转（非流通、非回兑）。市场结算时自动连带结算该市场上的所有 PK。全程 18+，不涉及人民币/加密/赌博三要素。
• P5-δ 变现层（合规复合栈）：
  • L1 激励视频广告：core/adwatch.py + GET /api/ads/offer、GET /api/ads/status、POST /api/ads/watch。用户自愿观看（前端占位 30s）→ 领平台积分（默认 20/次、每日上限 3）。链路：广告主付费→平台发积分→用户免费得，积分仍只送不卖。
  • L2 品牌众测赞助：core/sponsors.py + GET /api/sponsors、POST /api/markets/{id}/sponsor(admin)、GET /api/sponsors/{id}/report(admin)。品牌赞助市场（徽标展示），品牌方取该市场匿名群体情绪报告（无 PII）；奖品由品牌提供，参照虎扑/腾讯体育「品牌主题联赛」。种子已演示：双十一市场由「星寰电商」赞助。
  • L3 VIP 订阅（不卖分）：core/vip.py + GET /api/vip/tiers、POST /api/vip/subscribe。三档（免费/支持者 ¥9/Pro ¥29），权益为去广告/专属分析/抢先体验，绝不发放下注积分、绝不 pay-to-win。真实支付需接 xunhupay+ICP，VIP_PAYMENTS_ENABLED 默认 0 关闭，仅暴露档位说明。
• P5-E Live-Ops 限时活动（默认开放，无合规风险）：core/events.py + GET /api/events、GET /api/events/{id}、POST /api/events/{id}/participate、POST /api/admin/events(admin)、POST /api/admin/events/{id}/close(admin)。活动由时间推导状态（进行中/即将开始/已结束），参与领平台积分（每用户每活动限一次，积分只送不卖），关联真实市场作内容聚合展示。种子已演示三档真实主题季：诺贝尔季（🔬）、NBA 揭幕周（🏀）、双十一众测季（🛒），相对 now 生成，部署后始终有进行中/即将开始的活动。前端「游戏中心」新增「📅 限时活动」卡片。
• 合规：所有循环仅服务 18+；积分只送不卖/不可流通/不可回兑；抽卡按最严标准（公示概率+保底+上限）先行写好，不开 UI 入口；广告/VIP/赞助变现均不触碰「人民币买积分」「积分回兑现金」红线。

质量门禁：python tests/smoke.py --fresh 现为 168/168 全绿（含 P4 + P5 全量断言）。

上线硬性前提（未满足不得公开运营）

• 服务器 ICP 备案（腾讯云）
• 律所合规意见书