Files
trumpsignal-monorepo/README.md
T

77 lines
7.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# TrumpSignal monorepo
将原有 Next.js 前端与 Python/FastAPI 后端迁移为 TypeScript monorepo。前端使用 **Next.js Pages Router + Tailwind CSS + shadcn/ui**,API、后台任务、共享业务逻辑和数据库代码位于同一个仓库。
## 目录
| 目录 | 职责 |
| -------------------- | ---------------------------------------------------------------------------- |
| `apps/web` | 17 个页面入口;Pages Router、SSR、钱包连接、行情图表、SEO/PWA、同源 API 代理 |
| `apps/api` | Fastify API、钱包签名验证、WebSocket、公开查询与用户操作 |
| `apps/worker` | 单实例后台进程:行情、采集、扫描、仓位监控、Telegram、定时任务 |
| `packages/backend` | 交易、账户、采集、AI、KOL、宏观和通知服务 |
| `packages/core` | 策略、指标、签名、Fernet 兼容与保守回测等纯逻辑 |
| `packages/contracts` | 共享接口类型与浏览器签名消息构造 |
| `packages/database` | Drizzle/PostgreSQL 表结构与 SQL 迁移源码 |
| `packages/ui` | 共享 shadcn/ui Button、Input、Card 和样式工具 |
| `scripts` | 显式执行的迁移、导入、备份、运维与静态检查命令 |
| `tests` | 行为回归测试源码;本次未执行 |
| `migration` | 原始 commit、逐模块对应、接口清单、静态核对结果与交付说明 |
## 本次验证边界
已执行不生成产物的 TypeScript 静态类型检查、源码语法/结构检查与 Git 差异检查。结构核对覆盖原项目 **55 个 API handler、17 个页面、11 张表的 184 个字段**。
按用户要求,**没有启动应用、执行功能测试、编译构建、运行数据库迁移、连接交易账户或部署**。静态检查不证明新旧系统行为完全等价;交易、数据导入、外部 API、WebSocket 和通知仍需另行做运行验收。
## 环境与依赖
使用 Node.js 22 LTS(至少 22.14)或满足依赖要求的后续 LTS,以及 PostgreSQL。原前端的直接依赖和 transitive lock entries 用作 monorepo lockfile 的迁移基础,避免在重构时顺便升级钱包栈。
依赖准备可使用 `npm ci --ignore-scripts`。这是禁止安装脚本的安装方式,不启动项目;本次依赖准备也禁用了脚本。项目 `.npmrc` 保留 `legacy-peer-deps=true`,避免钱包库自动拉入无关的 React Native peer 环境。
复制根目录 `.env.example` 为 `.env`,按需填写服务端环境。前端在自己的目录读取环境文件,复制 `apps/web/.env.example` 到 `apps/web/.env.local`。真实密钥、数据库文件与备份均被 Git 忽略。未配置的外部集成保持关闭;示例使用 Hyperliquid testnet 且关闭 X 发布。
## 仅在以后明确需要运行时执行
下列命令是使用说明,本次没有运行启动、测试、迁移或备份命令。
| 命令 | 用途 |
| ---------------------------------- | ------------------------------------------------ |
| `npm run typecheck` | `tsc --noEmit`,不生成产物 |
| `npm run check:structure` | 静态核对路由、页面和数据库字段 |
| `npm test` | 执行行为回归测试,需要单独安排验证环境 |
| `npm run migrate` | 显式应用 SQL;旧 PostgreSQL 必须已到 Alembic 027 |
| `npm run start:api` | 启动 API,默认 8000 |
| `npm run start:worker` | 启动唯一 worker |
| `npm run dev:web` | 启动前端,端口 3001 |
| `npm run ops -- preflight` | 检查数据库连通性和配置存在性 |
| `npm run ops -- seed-wallets` | 幂等导入原项目的公开钱包种子 |
| `npm run ops -- reanalyze 500` | 默认 dry-run 的重分析工具 |
| `npm run ops -- backtest-batch 50` | 历史行情回测,不下单 |
所有构建、打包和隐含编译的运行验证,都应在用户确认的远程 runner 上执行。本仓库没有添加自动触发构建的 CI 工作流,也没有假定任何现有 runner 已获授权。
## 数据兼容
保留原生产 PostgreSQL 的表名、字段名、日期语义和 `enc:v1`/`enc:v2` Fernet 数据格式。`0001_legacy_027_baseline.sql` 对应旧库 Alembic 027 的最终结构;`0002_runtime_state.sql` 增加签名防重放、进程间事件、价格与运行状态。迁移不会在启动时自动执行。
新运行环境统一使用 PostgreSQL:API/worker 通过数据库通知同步事件,用 advisory lock 串行化钱包和仓位操作。旧 SQLite 提供 `scripts/import-sqlite.ts` 只读导入工具,目标必须是空的、已迁移的 PostgreSQL;新服务不直接运行 SQLite。导入和密钥重加密均未在本次执行。旧库回滚需要保留原数据库备份与原应用版本;没有自动回滚交易的操作。
## 业务规则
- Trump 是唯一自动开仓来源。BTC 底部与资金费率信号保持手动开仓、接管管理或仅提醒;未知来源不自动交易。
- 释放管理不平仓,自动监控与恢复跳过 `released_at` 已设置的仓位。
- 退出使用交易行的冻结参数,保留实际杠杆、分段减仓、Grow、阶梯止损、峰值和独立熔断状态。
- 回测使用保守的同根 K 线执行顺序,忽略手续费和滑点;不等于真实收益。
- 已停用的 Breakout Monitor 保留 API 和显式运维工具,但不重新加入调度;两个历史归档实验保持不启用。
- 日报开关与实时提醒开关独立。Telegram 绑定、静默时段、来源偏好与接管/释放命令保留。
反向代理部署时,仅将已知代理 IP/CIDR 写入 `TRUSTED_PROXY`;未配置时不信任客户端提供的转发 IP。前端代理和 SSR 的后端地址统一使用 `API_URL`。
## 参考与追踪
原仓库与 commit 见 `migration/inventory.json`;55 个 handler 的对应关系见 `migration/routes.json`。源码交付不表示已经合并、部署或做过线上验证。
路由转换参考 [Next.js Pages Router](https://nextjs.org/docs/pages/building-your-application/routing/pages-and-layouts),共享 UI 参考 [shadcn/ui monorepo](https://ui.shadcn.com/docs/monorepo),交易客户端使用 [Hyperliquid TypeScript SDK](https://github.com/nktkas/hyperliquid)。Fernet 固定测试向量来自 [Fernet specification](https://github.com/fernet/spec/blob/master/verify.json)。