v0.9 工单修复部署

2026-06-24 00:41:29 +00:00
commit 73720d8306
279 changed files with 39708 additions and 0 deletions
@@ -0,0 +1,93 @@
+# Echo Nexus · 云排行榜 mini-service
+
+回响星核 / Echo Nexus 的 P2 云排行榜服务（v0.8.2 / Task 10-b）。
+
+把信标本机排行榜（`localStorage`）升级为云端 Top100，玩家间可比。
+
+## 技术栈
+
+- **运行时**：Bun（原生 TypeScript，无需编译）
+- **框架**：Hono（轻量 web 框架，bun 原生支持）
+- **存储**：内存数组，重启清空（够用，符合 P2 规格）
+- **端口**：固定 `3030`（Caddy 通过 `?XTransformPort=3030` 转发）
+
+## 目录结构
+
+```
+mini-services/leaderboard-service/
+├── package.json    # 独立 bun 项目
+├── index.ts        # Hono 入口
+└── README.md
+```
+
+## API
+
+所有响应自动 CORS 开放，OPTIONS 预检由 Hono 自动处理。
+
+| 方法 | 路径 | 入参 | 返回 |
+|---|---|---|---|
+| GET | `/` | — | `{ service, version, ok, uptime }` 健康检查 |
+| GET | `/api/leaderboard` | — | `{ entries: BeaconScoreEntry[], total }` Top100 |
+| POST | `/api/leaderboard` | body `{ entry: BeaconScoreEntry }` | `{ entries, total, rank }` rank=1..N 或 -1 |
+| GET | `/api/leaderboard/stats` | — | `{ totalSubmissions, uniquePlayers, topScore }` |
+
+### `BeaconScoreEntry` 结构
+
+```ts
+{
+  timestamp: number,        // 提交时间戳
+  dateKey: string,          // YYYY-MM-DD 或 YYYY-Www
+  challenge: string,        // decode | expedition | pulse | boss | insight
+  difficulty: string,       // routine | anomaly | singular
+  progress: number,         // 0-1，1 = 完成
+  score: number,            // 最终得分
+  durationSec: number,      // 完成时长（秒）
+  isWeekly?: boolean,       // 周挑战记录
+  isTimed?: boolean         // 限时挑战记录（预留）
+}
+```
+
+## 存储 & 防刷规则
+
+- **容量**：最多 1000 条，按分数降序；超过自动丢弃尾部。
+- **Top 榜**：API 返回前 100 条。
+- **同分排序**：先看用时短，再看提交早。
+- **防刷**：同 `dateKey + challenge` 10 秒内只接受 1 次提交，返回 `429`。
+
+## 启动
+
+```bash
+cd mini-services/leaderboard-service
+bun run dev
+# 等价于 bun --hot index.ts，文件变更自动重启
+```
+
+## 联调（前端请求规范）
+
+前端必须用相对路径 + `?XTransformPort=3030`：
+
+```ts
+// 拉取全球 Top100
+const res = await fetch("/api/leaderboard?XTransformPort=3030");
+const { entries, total } = await res.json();
+
+// 提交一条记录
+const res = await fetch("/api/leaderboard?XTransformPort=3030", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ entry }),
+});
+const { entries, total, rank } = await res.json();
+```
+
+**禁止** `fetch("http://localhost:3030/...")` —— 不通过 Caddy 网关，会被浏览器同源策略拦截。
+
+## 部署形态
+
+独立 bun 项目，与主 Next.js 项目解耦：
+
+- 主项目端口 3000（Next.js dev）
+- 本服务端口 3030（Hono + Bun）
+- Caddy 网关端口 81（按 `?XTransformPort=3030` 转发到本服务）
+
+服务重启会清空数据，符合 P2 阶段规格（不需要持久化）。
@@ -0,0 +1,15 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "echo-nexus-leaderboard-service",
+      "dependencies": {
+        "hono": "^4.6.14",
+      },
+    },
+  },
+  "packages": {
+    "hono": ["hono@4.12.27", "", {}, "sha512-1yrb/+w6HWQJrUCLkJ2IF5jNIPvvFkblV5RNOYl6bV+OA6p9GLcMpHFFGTosSvHvcAUibuUukRqhlYI4z32C7Q=="],
+  }
+}
@@ -0,0 +1,182 @@
+// 回响星核 / Echo Nexus — 云排行榜 mini-service
+// P2/#4：把信标本机排行榜升级为云排行榜。
+// 端口固定 3030；Caddy 通过 ?XTransformPort=3030 转发。
+// 内存存储（重启清空），Hono + Bun 原生。
+//
+// API：
+//   GET  /api/leaderboard        → { entries: BeaconScoreEntry[], total }
+//   POST /api/leaderboard        body { entry } → { entries, total, rank }
+//   GET  /api/leaderboard/stats  → { totalSubmissions, uniquePlayers, topScore }
+//   GET  /                        → 健康检查
+//
+// 所有响应自动 CORS 开放（hono/cors），OPTIONS 预检 hono 自动处理。
+
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+
+// ---------------------------------------------------------------------------
+// 类型（与前端 BeaconScoreEntry 一致，但这里宽松化以接受历史数据）
+// ---------------------------------------------------------------------------
+interface BeaconScoreEntry {
+  timestamp: number;
+  dateKey: string;
+  challenge: string;
+  difficulty: string;
+  progress: number;
+  score: number;
+  durationSec: number;
+  isWeekly?: boolean;
+  isTimed?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// 内存存储
+// ---------------------------------------------------------------------------
+const entries: BeaconScoreEntry[] = [];
+const MAX_ENTRIES = 1000;
+const TOP_N = 100;
+
+// 简单防刷：同 dateKey+challenge 10 秒内只接受 1 次提交
+const lastSubmitAt = new Map<string, number>();
+const RATE_LIMIT_MS = 10_000;
+
+function sortEntries() {
+  entries.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    // 同分情况下，用时短者靠前
+    if (a.durationSec !== b.durationSec) return a.durationSec - b.durationSec;
+    // 仍相同，按时间戳升序（先提交靠前）
+    return a.timestamp - b.timestamp;
+  });
+  while (entries.length > MAX_ENTRIES) entries.pop();
+}
+
+function findRank(entry: BeaconScoreEntry): number {
+  const idx = entries.findIndex(
+    (e) =>
+      e.timestamp === entry.timestamp &&
+      e.dateKey === entry.dateKey &&
+      e.score === entry.score
+  );
+  return idx >= 0 ? idx + 1 : -1;
+}
+
+// ---------------------------------------------------------------------------
+// Hono 实例
+// ---------------------------------------------------------------------------
+const app = new Hono();
+
+// 全局 CORS 开放（前端跨端口访问）
+app.use(
+  "*",
+  cors({
+    origin: "*",
+    allowMethods: ["GET", "POST", "OPTIONS"],
+    allowHeaders: ["Content-Type", "X-Requested-With"],
+    exposeHeaders: ["Content-Length"],
+    maxAge: 600,
+  })
+);
+
+// 健康检查
+app.get("/", (c) =>
+  c.json({
+    service: "echo-nexus-leaderboard",
+    version: "v0.8.2",
+    ok: true,
+    uptime: Math.floor(process.uptime?.() ?? 0),
+  })
+);
+
+// GET /api/leaderboard — 返回 Top100
+app.get("/api/leaderboard", (c) => {
+  sortEntries();
+  const top = entries.slice(0, TOP_N);
+  return c.json({ entries: top, total: entries.length });
+});
+
+// POST /api/leaderboard — 插入一条记录，返回新榜 + 排名
+app.post("/api/leaderboard", async (c) => {
+  let body: { entry?: unknown };
+  try {
+    body = await c.req.json();
+  } catch {
+    return c.json({ error: "Invalid JSON body" }, 400);
+  }
+  if (!body || !body.entry || typeof body.entry !== "object") {
+    return c.json({ error: "Missing entry in body" }, 400);
+  }
+  const e = body.entry as Partial<BeaconScoreEntry>;
+  if (
+    typeof e.timestamp !== "number" ||
+    typeof e.dateKey !== "string" ||
+    typeof e.challenge !== "string" ||
+    typeof e.difficulty !== "string" ||
+    typeof e.score !== "number"
+  ) {
+    return c.json({ error: "Entry schema mismatch" }, 400);
+  }
+
+  // 防刷：同 dateKey+challenge 10 秒内只接受 1 次
+  const key = `${e.dateKey}|${e.challenge}`;
+  const now = Date.now();
+  const last = lastSubmitAt.get(key) ?? 0;
+  if (now - last < RATE_LIMIT_MS) {
+    return c.json(
+      {
+        error: "Rate limited",
+        retryAfterMs: RATE_LIMIT_MS - (now - last),
+        rank: -1,
+      },
+      429
+    );
+  }
+  lastSubmitAt.set(key, now);
+
+  // 规范化 entry（去多余字段，补默认值）
+  const entry: BeaconScoreEntry = {
+    timestamp: e.timestamp,
+    dateKey: e.dateKey,
+    challenge: e.challenge,
+    difficulty: e.difficulty,
+    progress: typeof e.progress === "number" ? e.progress : 0,
+    score: Math.max(0, Math.floor(e.score)),
+    durationSec: typeof e.durationSec === "number" ? e.durationSec : 0,
+    isWeekly: e.isWeekly === true,
+    isTimed: e.isTimed === true,
+  };
+
+  entries.push(entry);
+  sortEntries();
+  const rank = findRank(entry);
+
+  return c.json({
+    entries: entries.slice(0, TOP_N),
+    total: entries.length,
+    rank,
+  });
+});
+
+// GET /api/leaderboard/stats — 全局统计
+app.get("/api/leaderboard/stats", (c) => {
+  sortEntries();
+  const uniqueDateKeys = new Set(entries.map((e) => e.dateKey));
+  return c.json({
+    totalSubmissions: entries.length,
+    uniquePlayers: uniqueDateKeys.size,
+    topScore: entries.length > 0 ? entries[0].score : 0,
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 启动
+// ---------------------------------------------------------------------------
+const PORT = 3030;
+console.log(`[leaderboard-service] listening on :${PORT}`);
+
+const server = {
+  port: PORT,
+  fetch: app.fetch,
+};
+
+export default server;
@@ -0,0 +1,13 @@
+{
+  "name": "echo-nexus-leaderboard-service",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --hot index.ts",
+    "start": "bun index.ts"
+  },
+  "dependencies": {
+    "hono": "^4.6.14"
+  }
+}