# DEV-001 系统架构

# 概述

驿站（yizhan）采用 pnpm monorepo 架构，三个包协同工作：

packages/
├── shared/    # 共享类型、常量、协议、工具
├── server/    # Fastify HTTP + WebSocket 后端
└── web/       # Vue 3 + Vite SPA 前端

# 通信架构

┌─────────────────────────────────────────┐
│              web (Vue 3 SPA)            │
│  ┌─────────┐ ┌─────────┐ ┌──────────┐  │
│  │终端列表  │ │聊天区域  │ │终端管理  │  │
│  └─────────┘ └─────────┘ └──────────┘  │
│       │             │          │        │
│       └─────────────┼──────────┘        │
│                     │                   │
│           WebSocket + WebRTC            │
└─────────────────────┬───────────────────┘
                      │
┌─────────────────────┴───────────────────┐
│            server (Fastify)             │
│  ┌────────┐ ┌──────────┐ ┌──────────┐  │
│  │Auth/JWT│ │Terminal  │ │Transfer  │  │
│  │Service │ │Registry  │ │Relay     │  │
│  └────────┘ └──────────┘ └──────────┘  │
│                     │                   │
│           PostgreSQL + Redis            │
└─────────────────────────────────────────┘

# 数据流

# 文件传输流程

1. 发送方选文件 → transfer_request WS 消息
2. 服务器创建 DB 记录 → 通知接收方（在线直接推，离线标记 queued）
3. 接收方确认 → transfer_accept
4. 发送方启动传输：
   • 同源/localhost → 直接 relay（WS binary frame）
   • 远程 → 尝试 P2P（2s 超时）→ 降级 relay
5. relay：文件分 64KB chunk → WS binary frame → 服务器转发 → 接收方拼装 → 存 IndexedDB
6. 传输完成 → 更新 DB 状态

# 离线排队

接收方离线时，文件暂存服务器 data/queue/（24h TTL）。终端上线后自动推送 queued 记录。

# 端口分配

服务	端口
web (Vite dev)	12670
server (Fastify)	12671
PostgreSQL	12672
Redis	12673

# 技术栈

层	技术	版本
Runtime	Node.js	22+
Package Manager	pnpm	10
Frontend	Vue 3 + Vite + Tailwind CSS 4	3.5 / 8 / 4
UI	shadcn-vue (planned)	—
Backend	Fastify 5 + Drizzle + Zod + Pino	—
DB	PostgreSQL 16	16
Cache	Redis 7	7
Real-time	WebSocket (ws) + WebRTC (native)	—
Language	TypeScript	6