Poshkan Paper Trading

Poshkan — 模拟交易

使用虚拟资金练习交易美股、ETF、加密货币和外汇。Poshkan 将模拟账户、每笔交易旁的研究、业绩追踪和策略实验室结合起来，帮助你构建并测试自己的交易规则。

所有余额、交易和收益均为模拟数据。应用会使用市场数据为模拟交易定价。

线上应用：www.poshkan.com。

功能

• 各市场独立账户 — 独立投资组合、可配置的虚拟初始资金、观察列表和现金调整。
• 新手引导 — 创建模拟账户、研究公司、进行模拟交易，并在历史记录中回顾决策。账户和交易步骤会自动完成；研究和回顾步骤需由用户自行确认，进度会按用户保存在当前浏览器中。策略实验室位于仪表板导航的高级部分。
• 现货和杠杆交易 — 支持股票和加密货币的市价单与限价单，还支持覆盖三个市场的杠杆多头／空头头寸，并可为每笔交易设置杠杆、止损和止盈。外汇支持七种主要货币对、挂单、分批平仓和定时自动平仓。挂单支持 DAY/GTC 有效期。
• 买入前研究 — 公司基本面、历史价格背景、图表、新闻、股票发现和加密货币市场地图。无需账户即可使用公开研究页面、市场扫描、交易解读和计算器。
• 业绩和排行榜 — 已实现／未实现盈亏、资产配置、账户价值历史、交易历史，以及按百分比收益率排名的账户排行，并提供活动和回撤统计数据。
• 策略实验室 — 组合入场规则、选择代码和时间范围、设置止损／目标位和持仓时限，然后使用已完成的蜡烛图进行回测，并估算交易成本。回测策略可用于实时模拟交易提醒；自定义策略目前不会下单。
• 可选 AI 工具 — AI 扫描器支持自定义指令，并可选择在账户风险限额内自动进行模拟交易；还提供头寸分析。以上功能使用每位用户自己的 Anthropic API 密钥。密钥在存储前会加密。
• 通知和移动端访问 — 应用内通知、Web Push、邮件提醒、每周摘要端点，以及支持明暗主题的可安装 PWA。
• Claude/MCP 访问 — 个人令牌允许兼容的 MCP 客户端查看账户和市场数据、进行现货交易，并管理外汇头寸和挂单。

旧版 SMC、OTE、趋势、均值回归和蜡烛图区间扫描器开关已弃用。相关策略解读仍作为教育内容保留；当前工具为用户自建策略和 AI 扫描器。

技术栈与架构

领域	实现
应用	Next.js 16 App Router、React 19、TypeScript
UI	Tailwind CSS v4、Lucide 图标、自定义 SVG／蜡烛图表、TradingView widgets
身份验证与数据库	Supabase Auth、Postgres、行级安全、用于执行交易的 SQL RPC
客户端数据	使用 TanStack Query 轮询报价并管理缓存
市场数据	通过 yahoo-finance2 获取 Yahoo Finance 数据；可选集成 Twelve Data
AI	Anthropic SDK，用户提供的密钥经过加密
集成	MCP 服务、Resend 邮件、Web Push/VAPID
托管	Vercel，搭配计划任务和外部高频 cron 触发器

**报价优先使用 Yahoo：**批量请求可解析多个交易品种；配置 Twelve Data 后，会用它补充未能解析的报价。报价会缓存在内存和共享的 market_quotes 表中。配置 Twelve Data 后，K 线数据优先使用 Twelve Data，否则回退到 Yahoo； Yahoo 也提供发现和新闻功能。无需市场数据密钥，应用也可仅使用 Yahoo 运行。 历史数据覆盖范围和报价时效性取决于数据提供商及可用缓存。

交易操作会在服务端获取价格。Postgres RPC 会验证余额并原子化更新交易状态；待执行订单通过 status = 'pending' 声明。虽然数据库名称使用 fx_*，但股票、加密货币和外汇共用同一杠杆头寸引擎。

本地设置

1. 安装依赖项

使用 Node.js 20.9 或更高版本、npm 和 Supabase 项目。

git clone https://github.com/afrazja/poshkan-v2.git
cd poshkan-v2
npm ci

2. 配置环境

将 .env.local.example 复制为 .env.local，并替换占位符。 PowerShell 命令：

Copy-Item .env.local.example .env.local

变量	用途
NEXT_PUBLIC_SUPABASE_URL	必需的 Supabase 项目 URL。
NEXT_PUBLIC_SUPABASE_ANON_KEY	必需的公开 Supabase 客户端密钥；数据库访问受 RLS 限制。
NEXT_PUBLIC_SITE_URL	用于电子邮件确认和密码恢复的应用来源地址；本地使用 http://localhost:3000。
SUPABASE_SERVICE_ROLE_KEY	服务端管理员访问密钥，用于用户名登录、cron 作业、MCP 身份验证、共享缓存和通知。完整运行应用时请设置此项。
CRON_SECRET	用于验证计划任务身份并为摘要邮件的取消订阅链接签名的密钥。

可将可选设置添加到 .env.local；示例文件仅包含基本设置：

变量	启用项／行为
TWELVE_DATA_API_KEY	可选的 K 线数据提供商和报价备用来源。留空则仅使用 Yahoo。
TWELVE_DATA_CREDITS_PER_MINUTE	本地 Twelve Data 请求额度；默认为 8。请根据数据提供商的额度设置。
ENCRYPTION_KEY	保存／使用用户提供的 Anthropic 密钥时必需：32 个随机字节，以 base64 编码。
RESEND_API_KEY	应用邮件发送。
EMAIL_FROM	应用邮件的发件人身份；请配置 Resend 账户允许的发件人。
CONTACT_EMAIL	公开联系表单的收件人。
NEXT_PUBLIC_VAPID_PUBLIC_KEY	Web Push 公钥。
VAPID_PRIVATE_KEY	匹配的服务端 Web Push 私钥。
ADMIN_EMAILS	以逗号分隔的管理员允许列表；配置电子邮件后，第一个地址会收到注册通知。
AUTO_TRADE_ENABLED	设置为 false 可全局禁用 AI Scanner 自动交易。用户自建策略只会生成提醒。

使用以下命令在本地生成加密密钥：

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

请妥善保管 .env.local。只有面向浏览器的变量才应使用 NEXT_PUBLIC_； 服务角色、cron、加密、数据提供商和推送私钥必须保留在服务端。 AI 功能使用用户在应用中保存的密钥；没有供运营方共用的 Anthropic 密钥备用方案。 AI Scanner 目前还要求用户订阅推送通知。

3. 应用数据库脚本

SQL 文件位于 supabase/，需通过 Supabase SQL 编辑器手动应用。 npm run dev 或 npm run build 不会自动执行迁移。

对于全新数据库，请按顺序应用以下基础脚本（每个名称都是一个 .sql 文件）：

schema → orders → upgrades → forex → forex-sltp → orders-tif
→ leaderboard → hardening → mcp → push-journal → ai-limits
→ login-stats → market-quotes → leaderboard-stats

然后按下表顺序应用其余脚本，每行内从左到右依次应用：

顺序	supabase/ 中的文件	添加内容
1	username-login.sql → google-auth.sql	用户名登录和社交身份验证档案支持。
2	market-data-cache.sql	共享 K 线缓存和历史同步元数据。
3	fx-leverage.sql → forex-pairs.sql → forex-timed-close.sql → forex-tp-levels.sql → fx-position-source.sql	账户杠杆、货币换算、定时／分级退出，以及持仓来源跟踪。
4	forex-scan-alerts.sql → forex-scan-auto.sql → forex-auto-settings.sql → forex-ai-instruction.sql → ai-scanner-symbols.sql → byok-anthropic-key.sql	AI Scanner 历史记录、风险设置、指令、交易品种和加密密钥。
5	smc-scanner.sql → ote-scanner.sql → trend-scanner.sql → meanrev-scanner.sql → candlerange-scanner.sql	后续架构脚本仍会引用的旧版表。
6	scanner-auto-close.sql → scanner-position-cap.sql → per-trade-leverage.sql	持仓期限限制、持仓上限和逐笔交易杠杆。
7	custom-strategies.sql	当前 Strategy Lab 配置、回测和信号。
8	notifications.sql → account-notify.sql → scans.sql	通知中心、账户通知偏好设置和公开的每日扫描。
9	mcp-crypto-risk.sql	受保护的 MCP 加密货币入场：1–2× 杠杆、原子化止损／目标／截止时间、持仓和风险上限、加密货币小数单位。
10	crypto-cloud-monitor.sql	持久化云端扫描认领和原子化交易回执。需要 mcp-crypto-risk.sql。

之所以包含旧版扫描器表，是因为 scanner-position-cap.sql 和 per-trade-leverage.sql 会修改这些表，并且添加当前功能所用的字段。 如果缺少旧版表，应用这些脚本可能会失败。对于现有数据库，请先检查已应用的脚本 以及每个文件中的前置条件，再运行尚未应用的脚本。部分可选功能在相应迁移尚未应用前， 会隐藏或显示不可用状态。

4. 配置身份验证

在 Supabase 中启用带有电子邮件确认的电子邮件／密码身份验证。将 Supabase Auth Site URL 设置为应用的来源，并添加以下本地重定向 URL，以及每个已部署来源对应的 URL：

http://localhost:3000/auth/confirm
http://localhost:3000/auth/callback
http://localhost:3000/auth/reset

电子邮件确认处理程序需要 token_hash 和 type 查询参数。请将确认邮件链接配置为指向 /auth/confirm，例如：

<a href="{{ .RedirectTo }}?token_hash={{ .TokenHash }}&type=email">Confirm your email</a>

注册表单会将 /auth/confirm 作为 RedirectTo。Google 登录使用单独的 /auth/callback 路由来交换授权码；密码恢复使用 /auth/reset。

如需使用 Google 登录，请应用 google-auth.sql，配置包含应用来源的 Google OAuth Web 客户端， 并将 Supabase 提供商回调地址 注册为其授权重定向 URI：

https://YOUR-PROJECT-REF.supabase.co/auth/v1/callback

将 Google 客户端 ID 和密钥添加到 Supabase Google 提供商并启用它。Google 提供商回调和应用的 /auth/callback 是同一流程中的不同步骤。

5. 启动应用

npm run dev

打开 localhost:3000，创建账户并创建模拟投资组合。 后台扫描、订单监控和每日历史记录需要运行下方的定时任务。

定时任务与部署

项目从 main 部署到 Vercel。在那里配置环境变量，并将 NEXT_PUBLIC_SITE_URL 和 Supabase Auth 重定向设置为已部署的来源。数据库脚本 需与应用部署分开执行。

vercel.json 目前安排了两个任务（UTC）：

端点	计划	工作内容
/api/cron/market-check	工作日 15:30	待处理订单、价格提醒和杠杆仓位平仓。
/api/cron/snapshots	每日 22:15	账户价值快照、DAY 订单到期处理和公开每日扫描。

如需持续监控订单和扫描策略，请配置外部调度器，每 1–5 分钟调用一次 GET /api/cron/scanners，并附上以下标头：

Authorization: Bearer <CRON_SECRET>

此端点整合了 custom-scan、scan-opportunities（AI）和 market-check。 仅依靠 vercel.json 中的两个定时任务无法实现频繁监控。旧的 smc-scan、ote-scan、trend-scan、meanrev-scan 和 candlerange-scan 路由已不存在。

/api/cron/weekly-digest 可用，但未在 vercel.json 中安排；如需电子邮件摘要，请添加每周 外部调度。也可以单独调用 /api/cron/daily-scans，不过快照任务已经会调用它。定时路由需要 CRON_SECRET 和服务端 Supabase 访问权限。

MCP 集成

在应用的 AI/MCP 访问对话框中创建个人令牌。使用 Authorization: Bearer <token> 将 MCP 客户端连接到 https://<your-app-host>/api/mcp/mcp。 对话框会提供连接详情；令牌仅显示一次，以哈希形式存储，并可撤销。

服务端会将工具的访问范围限定为令牌所有者的账户。支持读取账户/持仓、 报价、价格历史和指标、符号搜索、交易、现货交易和限价订单。 专用外汇工具可开仓/列出/平仓，并创建/列出/取消待处理入场订单。 open_crypto_position 可开立加密货币杠杆多头/空头仓位，必须设置 SL/TP，杠杆为 1–2×，计划止损风险不得超过可用现金的 0.5%，保证金不得超过 25%，计划盈亏比至少为 3:1， 并须在六天内定时退出（默认为 72 小时）。dry_run: true 会进行验证但不交易。账户最多只能有一个已开立的杠杆仓位，且不能有待处理的杠杆入场订单。SQL RPC 会锁定账户，并随仓位保存止盈止损位和截止时间。 使用此工具前，请先应用 mcp-crypto-risk.sql：如果缺少 RPC，它会返回不可用错误，绝不会回退到 旧版 fx_open RPC 的固定 30× 保证金计算。 list_forex_positions 会读取不同市场的杠杆仓位；status: "closed" 会返回近期已结算仓位，以便跟踪已实现亏损。定时退出和止盈止损退出依赖 market-check 工作进程运行且市场数据可用；无法保证精确的执行时间。

开发参考

电脑关闭时监控加密货币

.github/workflows/crypto-cloud-monitor.yml 每小时两次在 GitHub 托管的运行器上调用 POST /api/cron/crypto-monitor。该任务独立于 Codex 和你的 PC 运行。 GitHub 定时任务尽力执行，可能延迟或被跳过；它并非精确的 30 分钟监控或有保证的止损执行服务。现有的 market-check 工作进程也会 处理已保存的止盈止损位和定时退出。

先应用 supabase/mcp-crypto-risk.sql，再应用 supabase/crypto-cloud-monitor.sql。将仓库 变量 CRYPTO_MONITOR_ACCOUNT_ID 设置为所选加密货币账户的 UUID，并将 CRYPTO_MONITOR_ENABLED 设置为 true；该工作流使用现有的 CRON_SECRET 仓库 密钥。将变量设为 false 可停止此工作流，也可在 GitHub Actions 中禁用它。 全局服务器设置 AUTO_TRADE_ENABLED=false 会阻止新的入场，同时工作进程会继续检查退出条件。关闭账户的旧版 AI 自动交易，以免两个机器人同时运行。 云端分析器使用账户所有者保存在 Poshkan 中的 Claude API 密钥，以及应用现有的 Opus 4.8 模型。API 用量计入该密钥的账单，与任何 Codex 订阅分开；不会回退到运营方密钥。缺少密钥或迁移未完成时，会阻止建仓，并在工作流摘要中报告。status 会检查前置条件，但不会交易；preview 会进行分析，但不会交易；run 可能会开立符合条件的模拟仓位。任何模式都不会强制进行测试交易。

仅考虑 BTC、ETH 和 SOL 的杠杆多头／空头。分析以已收盘的 15 分钟／小时／日线 K 线为依据。服务端检查会强制要求：杠杆不超过 2 倍、计划止损风险不超过可用现金的 0.5%、现金保证金不超过 25%、计划收益风险比至少为 3:1、仅持有一个杠杆仓位、必须设置 SL/TP，且期限为 72 小时。现有现货持仓会予以保留。数据库会为每个账户的 30 分钟扫描进行一次认领，并将交易回执与现金变更一并提交，因此重试时会返回原始回执。回执和分析记录存储在账户所有者可读取的 crypto_monitor_runs 表中。建仓／平仓通知和新的可操作故障通知会使用 Poshkan 现有的通知中心及已配置的推送订阅。

使用 node --experimental-strip-types --test scripts/crypto-monitor-policy.test.mjs 运行策略检查。

位置	职责
src/app/page.tsx	公共首页。
src/app/dashboard/	账户、排行榜、历史记录和 Strategy Lab 路由。
src/app/dashboard/actions.ts	创建账户和设置演示环境。
src/app/dashboard/[accountId]/actions.ts	交易、订单、账户设置、令牌和提醒。
src/app/dashboard/scanners/	策略持久化、回测、启用和扫描器状态。
src/lib/marketdata.ts	数据提供方路由和市场数据获取。
src/lib/market-quote-cache.ts、src/lib/market-candle-cache.ts	共享市场数据缓存。
src/lib/pnl.ts、src/lib/forex.ts、src/lib/assets.ts	盈亏、保证金／仓位计算和资产类别限制。
src/lib/custom-strategy.ts、src/lib/custom-strategy-backtest.ts、src/lib/trading-costs.ts	规则评估、回测和预计执行成本。
src/app/api/cron/、src/app/api/mcp/[transport]/	后台任务和通过令牌验证的 MCP 工具。
src/lib/supabase/、src/proxy.ts	数据库客户端、身份验证会话和路由保护。
src/lib/email.ts、src/lib/push.ts、public/sw.js	电子邮件、推送递送和服务工作线程。
supabase/	手动应用的架构和 RPC 迁移。

常用命令：

npm run dev          # Development server
npx tsc --noEmit      # Type check
npm run lint         # ESLint
npm run build        # Production build
npm start            # Serve a completed production build

发布前，请运行类型检查和生产构建，并在浏览器中检查公共页面。开发服务器运行时，请勿删除 .next。修改 Next.js 时，请阅读 node_modules/next/dist/docs/ 中的相关指南；本仓库采用 Next.js 16 约定。

贡献规则请参阅 AGENTS.md，计划中的工作请参阅 docs/ROADMAP.md；DESIGN.md 和 docs/OVERVIEW.md 提供历史背景，可能描述的是早期版本；当前行为以代码为准。