v0.9 工单修复部署

2026-06-24 00:41:29 +00:00
commit 73720d8306
279 changed files with 39708 additions and 0 deletions
@@ -0,0 +1,75 @@
+# star-tide-service · 全球星潮同步 mini-service
+
+> 回响星核 / Echo Nexus · P3 工单 #10-c
+>
+> socket.io 多人同步星潮 —— 所有在线玩家同时经历同一道全球星潮 60 秒。
+
+## 设计
+
+- **端口**：固定 `3031`
+- **网关**：Caddy 通过 `?XTransformPort=3031` 转发；前端用 `io("/?XTransformPort=3031")`
+- **运行时**：bun + socket.io 4
+- **存储**：纯内存（无状态，重启不影响前端游戏）
+
+## 星潮节奏
+
+- 首次星潮：服务端启动后 **60 秒**（可由 env `FIRST_TIDE_DELAY_MS` 覆盖，便于 QA）
+- 后续星潮：**10-15 分钟随机间隔**
+- 每次持续：**60 秒**
+- 类型：从 6 种星潮按权重随机抽取（与前端 `TIDE_EVENTS` 一致）
+  - 晶体潮 22 / 谐振风暴 20 / 遗迹共振 16 / 虚空低语 18 / 星核悸动 14 / 寂静期 10
+
+## socket.io 事件
+
+### 服务端 → 客户端
+
+| 事件 | 载荷 | 触发时机 |
+|------|------|---------|
+| `tide-state` | `{ current: GlobalTideState \| null, nextTideAt, serverTime }` | 客户端连接时立即推送 |
+| `global-tide` | `{ type, name, startedAt, endsAt, durationSec }` | 全球星潮开始 |
+| `tide-ended` | `{ endedAt, nextTideAt }` | 全球星潮结束 |
+| `next-tide-info` | `{ current, nextTideAt, serverTime, remainingMs }` | 响应客户端 `get-next-tide` |
+
+### 客户端 → 服务端
+
+| 事件 | 载荷 | 行为 |
+|------|------|------|
+| `get-next-tide` | — | 查询下次星潮剩余时间 |
+| `admin-trigger-tide` | — | **dev/QA 用**：立即触发一次全球星潮 |
+
+## HTTP 端点
+
+socket.io `path: '/'` 拦截所有 HTTP 请求，因此本服务不提供独立 HTTP 健康检查端点。
+
+- `GET /` —— socket.io 默认握手响应（`{"code":0,"message":"Transport unknown"}` 表示服务在线）
+
+## 启动
+
+```bash
+cd mini-services/star-tide-service
+bun run dev   # bun --hot index.ts，热重载
+# 或
+bun run start # bun index.ts，无热重载
+```
+
+## QA 验证
+
+```bash
+# socket.io 在线验证（收到 JSON 响应即表示服务在线）
+curl http://localhost:3031/
+# 预期：{"code":0,"message":"Transport unknown"}
+```
+
+前端可在浏览器 console 触发全球星潮（QA 用）：
+
+```js
+const sock = io("/?XTransformPort=3031");
+sock.on("tide-state", (s) => console.log("当前状态:", s));
+sock.emit("admin-trigger-tide"); // 立即触发一次全球星潮
+```
+
+## 离线容错
+
+- 服务端宕机 → 前端 `useGlobalTide` 自动重连（socket.io 默认行为）
+- 断连期间 → 前端本地 `tickTide` 继续按原节奏工作，玩家不会卡住
+- 全球星潮进行中 → 前端本地 `tickTide` 暂停触发（避免冲突）