🎉 init: 小龙的工作空间

2026-06-06 10:40:48 +08:00
commit a188ee1426
3201 changed files with 231817 additions and 0 deletions
@@ -0,0 +1,140 @@
+# Network Tool - 异地组网工具 MVP
+
+> PC Tool Factory 测试需求：异地组网工具最小可运行版本
+
+## 项目结构
+
+```
+network-tool/
+├── apps/
+│   ├── client-electron/    # Electron + React 桌面客户端
+│   ├── control-server/     # Fastify + SQLite 控制服务器
+│   └── relay-node/         # TCP 转发节点
+├── packages/
+│   ├── shared-types/       # 共享 TypeScript 类型定义
+│   ├── shared-crypto/      # 加密工具 (JWT, bcrypt, SHA256)
+│   └── shared-protocol/    # 网络协议 (帧编解码)
+├── test-e2e.js             # 端到端测试脚本
+└── README.md
+```
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+cd network-tool
+npm install
+```
+
+### 2. 构建共享包
+
+```bash
+npm run build:shared
+```
+
+### 3. 启动 Control Server (终端 1)
+
+```bash
+npm run dev:server
+# → http://localhost:3001
+# → ws://localhost:3001/ws
+```
+
+### 4. 启动 Relay Node (终端 2)
+
+```bash
+npm run dev:relay
+# → TCP: localhost:4101
+# → 自动向服务器注册并发送心跳
+```
+
+### 5. 运行 E2E 测试 (终端 3)
+
+```bash
+node test-e2e.js
+```
+
+### 6. 启动 Client Desktop (终端 3)
+
+```bash
+cd apps/client-electron
+npm run dev:main        # 编译主进程 + 启动 Electron
+npm run dev:renderer    # 启动 Vite React dev server
+```
+
+## 验证结果
+
+| 验收标准 | 状态 |
+|----------|------|
+| npm install 成功 | ✅ |
+| 服务器启动成功 | ✅ |
+| 节点启动成功 | ✅ |
+| 客户端启动成功 | ⚠️ 源码完成，需 Electron 二进制 |
+| 用户注册登录成功 | ✅ |
+| 设备注册成功 | ✅ |
+| 节点注册成功 | ✅ |
+| Token 验证成功 | ✅ |
+| 客户端消息转发成功 | ✅ (E2E Test A↔B PASS) |
+| TypeScript 编译 | ✅ 5/5 包编译通过 |
+
+## API 端点
+
+### Auth
+- `POST /api/auth/register` — 用户注册
+- `POST /api/auth/login` — 用户登录
+- `GET /api/auth/me` — 当前用户信息
+
+### Devices
+- `POST /api/devices/register` — 注册设备
+- `GET /api/devices` — 设备列表
+- `PATCH /api/devices/:id/status` — 更新状态
+- `DELETE /api/devices/:id` — 删除设备
+
+### Nodes
+- `POST /api/nodes/register` — 节点注册
+- `POST /api/nodes/heartbeat` — 心跳上报
+- `GET /api/nodes` — 节点列表
+- `GET /api/nodes/available` — 可用节点
+
+### Connections
+- `POST /api/connections/request` — 请求连接 Token
+- `POST /api/connections/verify-token` — 节点验证 Token
+- `POST /api/connections/disconnect` — 断开连接
+- `GET /api/connections/logs` — 连接日志
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `PORT` | `3001` | 服务器端口 |
+| `HOST` | `0.0.0.0` | 绑定地址 |
+| `DB_PATH` | `./data/network.db` | 数据库路径 |
+| `JWT_SECRET` | 开发密钥 | JWT 签名密钥 |
+| `SERVER_URL` | `http://localhost:3001` | Relay Node 服务地址 |
+| `NODE_NAME` | `relay-node-1` | 节点名称 |
+| `TCP_PORT` | `4101` | 节点 TCP 端口 |
+
+## 安全
+
+- 密码 bcrypt 哈希存储
+- JWT Token 鉴权（过期 24h）
+- 连接 Token 5 分钟过期
+- 节点必须向服务器验证客户端 Token
+- 客户端不能伪造设备身份
+- 日志不存储明文密码
+
+## 技术栈
+
+- **Server**: Fastify, sql.js (SQLite), JWT, WebSocket
+- **Relay**: Node.js TCP, HTTP client, 帧协议
+- **Client**: Electron, React, TypeScript, Vite
+- **Shared**: TypeScript types, bcrypt, JWT, SHA256
+
+## Build
+
+```
+TypeScript 文件: 22
+总代码行数: ~2031
+编译状态: 5/5 PASS
+```