diff --git a/PROJECT_AUDIT_2026-03-03.md b/PROJECT_AUDIT_2026-03-03.md new file mode 100644 index 0000000..517c5b7 --- /dev/null +++ b/PROJECT_AUDIT_2026-03-03.md @@ -0,0 +1,201 @@ +# 项目全面审查报告(2026-03-03) + +## 审查范围与方法 +- 范围:`src/`、`prisma/`、`Dockerfile`、`Jenkinsfile`、`README.md`、测试与构建脚本。 +- 方式:静态审查 + 命令基线 + 关键链路手工走读(Panic 模式、房间投票、盲盒计划)。 +- 执行过的基线命令: + - `npm run lint` + - `npm test` + - `npx tsc --noEmit` + - `npm run test:coverage` + - `npm run build`(当前环境因无法访问 Google Fonts 未完全通过) + +## 结论概览 +- 发现高优问题(P0/P1):5 个 +- 发现中优问题(P2):6 个 +- 主要风险类型:业务功能中断、状态数据污染、鉴权边界不完整、敏感信息暴露、工程质量门禁缺失。 + +--- + +## 关键问题(按优先级) + +### P0-1 Panic 模式“手动加入房间”输入规则与后端房间 ID 规则不一致(功能性缺陷)【已完成】 +- 修复状态:✅ 已完成(2026-03-03) +- 修复内容: + - 前端改为 6 位字母数字房间号输入,统一转大写并过滤非法字符; + - 后端 `POST /api/room/[id]/join` 增加房间号格式校验与标准化; + - 补充校验与页面行为测试用例。 +- 证据: + - `src/app/panic/page.tsx:173`(要求长度必须为 4) + - `src/app/panic/page.tsx:567`(`maxLength={4}`) + - `src/app/panic/page.tsx:566`(仅允许数字) + - `src/lib/roomRepository.ts:21`(实际房间 ID 生成规则为 6 位,且含字母) +- 影响: + - 用户无法通过手输房间号加入大多数房间(尤其是含字母的房间号)。 + - 直接影响核心转化路径(邀请后加入房间)。 +- 建议: + - 前端加入输入改为 6 位字母数字(与 `ROOM_ID_CHARS` 一致); + - 后端补充房间号格式校验与明确错误提示; + - 增加 E2E 用例覆盖“手输邀请码加入”。 + +### P0-2 投票接口未校验 `restaurantId` 是否属于房间候选列表(可污染房间状态) +- 证据: + - `src/app/api/room/[id]/swipe/route.ts:25`(仅查 index) + - `src/app/api/room/[id]/swipe/route.ts:32-42`(即使 `restaurantIndex === -1` 仍可写入 `likes` 并可能设置 `match`) +- 影响: + - 客户端可提交伪造 `restaurantId`,导致房间匹配结果异常或不可展示; + - 状态污染会影响所有成员的结果一致性。 +- 建议: + - 在进入投票逻辑前强制校验 `restaurantIndex >= 0`,否则返回 400; + - 对 `undo/reset` 等相关接口同步增加 ID 合法性校验; + - 增加“非法 restaurantId”单测。 + +### P1-1 `suggest-item` 接口缺失鉴权(可被匿名滥用,产生外部 API 成本) +- 证据: + - `src/app/api/blindbox/plan/suggest-item/route.ts:6-11`(无 `getAuthUserId` / 无 membership 校验) +- 影响: + - 任意匿名请求可触发 AI + 地图查询,存在成本与滥用风险。 +- 建议: + - 至少要求登录态;更稳妥是同时校验房间成员身份(若与房间上下文绑定); + - 配合限流(IP + 用户维度)。 + +### P1-2 API 错误响应直接回传内部异常细节(信息泄露) +- 证据: + - `src/lib/api.ts:63-65`(500 响应包含 `ErrorName: message`) +- 影响: + - 暴露内部实现信息、库错误细节、潜在环境配置线索; + - 提升攻击者探测效率。 +- 建议: + - 客户端统一返回泛化错误文案; + - 详细错误仅记录在服务端日志(可加 requestId 关联)。 + +### P1-3 CI 配置中存在敏感信息硬编码 +- 证据: + - `Jenkinsfile:6`(地图 key 常量) + - `Jenkinsfile:11`(固定触发 token) +- 影响: + - 密钥泄露与流水线被外部触发的风险增加; + - 密钥轮转和环境隔离困难。 +- 建议: + - 全部迁移到凭据系统(Jenkins Credentials / Secret Manager); + - 触发 token 改为密文凭据并定期轮换。 + +--- + +## 中优问题(P2) + +### P2-1 SSE 成员校验逻辑未真正启用(前端未传 `userId`) +- 证据: + - `src/app/api/room/[id]/events/route.ts:14-18`(仅在 query 存在 `userId` 时校验) + - `src/hooks/useRoomPolling.ts:32`(实际建立 SSE 连接时未携带 `userId`) +- 影响: + - 只要知道房间 ID 即可订阅房间流事件(当前实现下)。 +- 建议: + - 改为服务端基于认证态校验,或强制 query/body 校验成员身份; + - 前端补齐身份参数并确保不可伪造(推荐 token/cookie 方案)。 + +### P2-2 “接受计划”前端逻辑乐观更新过早,且未检查 `res.ok` +- 证据: + - `src/hooks/useBlindboxPlan.ts:227-240`(先 `setPlanAccepted(true)`,请求后不判断 `res.ok`) +- 影响: + - 后端失败时前端仍显示“已接受”,形成状态不一致。 +- 建议: + - 先请求成功再更新 `planAccepted/activeContract`; + - 失败回滚并展示错误信息。 + +### P2-3 TypeScript 基线不通过(测试代码类型漂移) +- 证据: + - `npx tsc --noEmit` 当前报多个错误(测试辅助类型、mock 签名、类型定义漂移等)。 +- 影响: + - 类型系统对回归的兜底失效;重构时风险上升。 +- 建议: + - 将 `tsc --noEmit` 纳入 CI 必跑; + - 优先修复测试目录类型错误,确保类型门禁恢复。 + +### P2-4 Lint 存在阻塞错误(React hooks 新规则触发) +- 证据: + - `npm run lint`:10 error / 32 warning。 + - 代表性问题: + - `src/components/SwipeableCard.tsx:81`(render 阶段注册副作用) + - `src/components/GlobalUserBadge.tsx:23`(effect 内同步 setState) + - `src/components/PageTransition.tsx:14`(render 期间 ref 访问) + - `src/hooks/useGeolocation.ts:67`(effect 内直接触发状态写入路径) +- 影响: + - 渲染稳定性与性能风险;后续升级 React/Next 成本上升。 +- 建议: + - 先清理 error 级规则,再统一处理 warning; + - 针对 hooks 规则建立最小回归测试。 + +### P2-5 定时器清理不完整(潜在内存泄漏/卸载后状态写入) +- 证据: + - `src/hooks/useBlindboxIdeas.ts:52` + `:129`(保存定时器,但无统一 cleanup) + - `src/hooks/useBlindboxDraw.ts:25` + `:38`(定时器与动画回调未见 unmount 清理) +- 影响: + - 页面切换或快速操作下可能出现卸载后 setState、额外渲染噪音。 +- 建议: + - 为上述 hook 增加 `useEffect` cleanup 清理 `timersRef`; + - confetti 动画增加销毁标志与取消逻辑。 + +### P2-6 构建/测试门禁链路不完整 +- 证据: + - `Jenkinsfile` 当前仅构建和部署,无 `lint/test/tsc` 阶段。 + - `npm run test:coverage` 缺少 `@vitest/coverage-v8`。 + - `npm test` 虽通过,但出现多处 `act(...)` 警告。 +- 影响: + - 回归问题可能绕过 CI 直接进入部署。 +- 建议: + - CI 最少增加:`npm run lint`、`npx tsc --noEmit`、`npm test`; + - 补齐 coverage 依赖并设定最低阈值; + - 修复 `act(...)` 警告提升测试可信度。 + +--- + +## 可重构/可优化项(非阻塞,但收益高) + +### R1 计划查询存在 N+1 查询模式 +- 证据: + - `src/lib/planQueries.ts:30-36`、`63-68`(每条计划单独查房间) +- 建议: + - 使用 `include` / 批量映射一次性拉取房间信息,减少 DB 往返。 + +### R2 `atomicUpdateRoom` 对 likes 的“全删全建”策略成本较高 +- 证据: + - `src/lib/roomRepository.ts:185-195` +- 建议: + - 按增量 diff 更新(新增/删除差集)替代全量重建; + - 对高频路径(swipe/undo)优先优化。 + +### R3 请求参数契约不统一(前端仍大量发送已废弃 `userId`) +- 证据: + - 例如 `src/hooks/useBlindboxIdeas.ts:57/71/104/...`、`src/hooks/useBlindboxPlan.ts:50/68/...` +- 建议: + - 明确“鉴权由 cookie/token 提供”,清理冗余 `userId` 参数; + - 用 Zod schema 统一约束(`src/lib/schemas/requests.ts` 目前未形成全链路使用)。 + +### R4 统一 API 调用层(减少重复 fetch + 错误处理分散) +- 现状: + - 客户端很多模块各自拼接 URL、手写错误分支。 +- 建议: + - 为业务 API 建立 typed client(含统一重试、错误映射、鉴权处理); + - 与 SWR key 规范化一起推进。 + +--- + +## 基线执行结果(本次审查) +- `npm run lint`:失败,`10 errors / 32 warnings`。 +- `npm test`:通过,`53 files / 329 tests`,但有 `act(...)` 警告。 +- `npx tsc --noEmit`:失败(测试相关类型错误若干)。 +- `npm run test:coverage`:失败(缺少 `@vitest/coverage-v8`)。 +- `npm run build`:本地环境因无法访问 Google Fonts 失败(与当前受限网络环境相关)。 + +--- + +## 建议修复顺序(可执行) +1. 先修 P0(房间号规则不一致、swipe 非法 ID 校验)。 +2. 再修 P1(`suggest-item` 鉴权、API 错误脱敏、CI 密钥治理)。 +3. 处理 P2 工程门禁(lint/tsc/CI),恢复“提交即验证”。 +4. 最后推进 R 类重构(N+1、增量更新、API client 统一)。 + +## 交付说明 +- 本文档为静态审查结论,未改动业务代码。 +- 建议下一步按“P0/P1 修复 PR + 回归测试补齐”方式分批落地。 diff --git a/src/app/api/room/[id]/join/route.test.ts b/src/app/api/room/[id]/join/route.test.ts index 84f654b..c843420 100644 --- a/src/app/api/room/[id]/join/route.test.ts +++ b/src/app/api/room/[id]/join/route.test.ts @@ -74,11 +74,11 @@ describe("POST /api/room/[id]/join", () => { it("returns 404 when room not found", async () => { mockAtomicUpdate.mockResolvedValue(null); - const req = createRequest("/api/room/NONEXIST/join", { + const req = createRequest("/api/room/ABC123/join", { method: "POST", body: { userId: "user-1" }, }); - const ctx = createRouteContext({ id: "NONEXIST" }); + const ctx = createRouteContext({ id: "ABC123" }); const res = await POST(req, ctx); expect(res.status).toBe(404); }); @@ -92,4 +92,14 @@ describe("POST /api/room/[id]/join", () => { const res = await POST(req, ctx); expect(res.status).toBe(401); }); + + it("returns 400 when room id format is invalid", async () => { + const req = createRequest("/api/room/1234/join", { + method: "POST", + body: { userId: "user-1" }, + }); + const ctx = createRouteContext({ id: "1234" }); + const res = await POST(req, ctx); + expect(res.status).toBe(400); + }); }); diff --git a/src/app/api/room/[id]/join/route.ts b/src/app/api/room/[id]/join/route.ts index ee8a357..d8e9598 100644 --- a/src/app/api/room/[id]/join/route.ts +++ b/src/app/api/room/[id]/join/route.ts @@ -2,14 +2,16 @@ import { NextResponse } from "next/server"; import { atomicUpdateRoom } from "@/lib/roomRepository"; import { notify } from "@/lib/roomEvents"; import { apiHandler, ApiError, requireUserId } from "@/lib/api"; +import { validatePanicRoomId } from "@/lib/validation"; export const POST = apiHandler(async (req, { params }) => { const { id } = await params; + const roomId = validatePanicRoomId(id); const { userId } = await req.json(); requireUserId(userId); - const updated = await atomicUpdateRoom(id, (data) => { + const updated = await atomicUpdateRoom(roomId, (data) => { if (data.kickedUsers.includes(userId)) { throw new ApiError("你已被移出该房间", 403); } @@ -24,10 +26,10 @@ export const POST = apiHandler(async (req, { params }) => { if (!updated) throw new ApiError("房间不存在或已过期", 404); - notify(id); + notify(roomId); return NextResponse.json({ - roomId: id, + roomId, userCount: updated.users.length, }); }); diff --git a/src/app/panic/page.test.tsx b/src/app/panic/page.test.tsx index 7daab98..c000577 100644 --- a/src/app/panic/page.test.tsx +++ b/src/app/panic/page.test.tsx @@ -58,6 +58,7 @@ const mockFetch = vi.fn().mockResolvedValue({ vi.stubGlobal("fetch", mockFetch); import PanicPage from "./page"; +import { joinRoom } from "@/lib/room"; const toastCtx: ToastContextValue = { show: vi.fn() }; @@ -97,4 +98,20 @@ describe("PanicPage", () => { renderPage(); expect(screen.getAllByText("餐厅").length).toBeGreaterThanOrEqual(1); }); + + it("normalizes room code as 6-char alphanumeric when joining", async () => { + renderPage(); + const input = screen.getByPlaceholderText("输入 6 位房间号"); + fireEvent.change(input, { target: { value: "ab12-cd!" } }); + expect(input).toHaveValue("AB12CD"); + + const submitButton = screen.getByLabelText("加入房间"); + expect(submitButton).not.toBeDisabled(); + + fireEvent.click(submitButton); + + await waitFor(() => { + expect(vi.mocked(joinRoom)).toHaveBeenCalledWith("AB12CD", "user-1"); + }); + }); }); diff --git a/src/app/panic/page.tsx b/src/app/panic/page.tsx index 89c4d4b..98cb997 100644 --- a/src/app/panic/page.tsx +++ b/src/app/panic/page.tsx @@ -170,15 +170,16 @@ export default function PanicPage() { const handleJoin = async (e: React.FormEvent) => { e.preventDefault(); - if (roomCode.length !== 4) { - setError("请输入 4 位房间号"); + if (roomCode.length !== 6) { + setError("请输入 6 位房间号"); return; } setLoading(true); setError(""); try { - await joinRoom(roomCode, getUserId()); - router.push(`/room/${roomCode}`); + const normalizedRoomCode = roomCode.toUpperCase(); + await joinRoom(normalizedRoomCode, getUserId()); + router.push(`/room/${normalizedRoomCode}`); } catch (e) { console.error("PanicPage: handleJoin failed:", e); setError("房间不存在,请检查房间号"); @@ -562,13 +563,17 @@ export default function PanicPage() {
{ - setRoomCode(e.target.value.replace(/\D/g, "").slice(0, 4)); + const normalized = e.target.value + .toUpperCase() + .replace(/[^A-Z0-9]/g, "") + .slice(0, 6); + setRoomCode(normalized); setError(""); }} disabled={loading} @@ -576,7 +581,7 @@ export default function PanicPage() { />