77 lines
7.0 KiB
Markdown
77 lines
7.0 KiB
Markdown
# 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)。
|