juwan-frontend/AUDIT.md

聚玩前端 缺陷审计报告

审计时间：2026-02-20 项目：聚玩（JuWan）— 基于 Next.js 16 + shadcn/ui + Tailwind CSS 4 的游戏陪玩平台前端 仓库结构：约 100 个源文件，分布在 app/（页面）、components/（共享组件）、lib/（工具/类型/mock 数据）、store/（Zustand 状态管理） 背景：本项目由 AI 辅助生成，本报告检查脏代码、AI 生成痕迹、劣质 UI 设计、与 PLAN.md 的偏差等问题 审计方法：8 个并行审计 Agent 分别负责不同维度（代码卫生、AI 痕迹、UI 设计、文案质量、mock 数据、架构、功能完整性），交叉验证

---

一、代码卫生

对全部 .ts/.tsx/.css/.json 文件做了关键词扫描。

扫描结果：全部为零。

• @ts-ignore / @ts-expect-error / as any：零
• biome-ignore / eslint-disable / prettier-ignore：零
• console.log / console.warn / console.error：零
• 空 catch 块：零
• 代码注释：整个 app/components/store/lib 目录没有一行注释
• AI 工具签名（Claude / Copilot / Cursor / GPT / Sisyphus / OpenCode）：零
• 对话痕迹（"根据你的要求" / "as you requested" 等）：零
• Git 提交消息：风格统一（Conventional Commits），无 AI 工具提及

唯一残留：next.config.ts:4 的脚手架占位注释 /* config options here */。

结论：代码表面非常干净。AI 痕迹不在注释层面，而在内容和设计层面（见后续章节）。

---

二、Emoji 滥用

2.1 游戏图标用 emoji 代替 [严重]

lib/mock-data.ts 第 71-78 行定义了 8 个游戏，它们的 icon 字段全部使用 emoji 字符：

🎮（英雄联盟）👑（王者荣耀）🔫（和平精英）⚔️（原神）🌟（永劫无间）🪖（CS2）🛡️（DOTA2）💥（绝地求生）

这些 emoji 通过 {game.icon} 被渲染到以下 UI 位置：

• app/(main)/page.tsx:46 — 首页游戏分类卡片
• app/(main)/search/page.tsx:212 — 搜索页游戏筛选标签
• app/(dashboard)/dashboard/services/new/page.tsx:73 — 服务发布页游戏选择列表

这是典型的 AI 生成偷懒行为——用 emoji 代替真实图标。应替换为 lucide-react 图标或自定义 SVG 图标映射。

2.2 UI 标签中的 emoji [严重]

app/(main)/community/page.tsx:66 — 社区页帖子中出现 📋 关联订单秀单，在 UI 标签/区块标题场景使用 emoji 装饰，是典型 AI 生成风格。

2.3 可接受的 emoji [低]

lib/mock-data.ts:459 — 聊天消息 "感谢好评！下次继续带飞 💪"，这是模拟用户聊天行为，emoji 使用合理，可保留。

---

三、AI 味文案

项目中没有直接的 AI 工具签名，但大量 UI 文案带有明显的 AI 生成特征——空洞的营销语、模板化表达、过于正式的语气。

3.1 首页/搜索页营销腔 [严重]

文件:行号	文案内容	问题
app/(main)/page.tsx:15	"专业陪玩、代练、上分，覆盖主流游戏，安全可靠"	空洞的"全都好"营销句，任何平台都能用
app/(main)/search/page.tsx:383	"找到最适合你的游戏伙伴，一起畅玩游戏世界"	泛化 AI 文案，无具体信息
app/(main)/search/page.tsx:407	"调整筛选条件以找到更匹配的陪玩"	说明书口吻，不像产品在和用户说话
components/footer.tsx:14	"专业游戏陪玩服务平台"	通用 slogan，品牌辨识度为零

3.2 Mock 数据中的模板化文案 [中等]

lib/mock-data.ts 中的文本内容几乎全部带有 AI 生成特征：

服务描述（第 87-135 行）：标题和描述高度模板化——"上分陪玩"、"代练上星"、"带飞"、"安全高效"、"保证胜率60%+"。这些像是 AI 批量生成的电商文案，缺少真实卖家会写的个性化表达。

用户简介（第 37、56、65 行）：营销腔明显——"全国百强"、"全球精英"、"专业工作室"。真实用户简介通常更随意。

店铺介绍（第 188 行）："专业电竞陪玩工作室，拥有50+签约打手，覆盖主流游戏"——万能介绍模板。

评价内容（第 280、292、304 行）：语句太完整、太"好文案"，缺少真实评价中常见的口语化表达、碎句、停顿词。

聊天消息（第 382、402 行）：偏客服话术（"请问什么时候方便开始"），真实私聊通常更短更随意。

通知文案（第 516 行）："聚玩春节活动即将开始，敬请期待！"——"敬请期待"式公告模板化明显。

3.3 页面文案细节 [中等]

文件:行号	文案内容	问题
app/(main)/post/new/page.tsx:110	"分享你的游戏体验..."	典型 AI 占位句，泛而无指向
app/(main)/post/[id]/page.tsx:127	"来抢沙发吧"	老论坛语感，和当前产品调性不匹配
app/(order)/review/[id]/page.tsx	"确保真实性和公正性"	偏 AI/公文腔
app/(main)/page.tsx:21	"搜索打手"	用词偏硬，和"陪玩"语境不统一

3.4 术语不统一 [严重]

同一概念在不同位置使用不同称呼，这是 AI 分次生成不同页面时缺乏全局一致性的典型表现：

位置	对用户的称呼	对服务提供者的称呼
components/header.tsx:38	"消费者"	—
社区页 roleLabels	"玩家"	—
components/header.tsx:93 搜索框	—	"打手"
首页/其他页面	—	"陪玩"

应建立统一的术语体系并全局替换。

---

四、Mock 数据 AI 味道

lib/mock-data.ts 是全站的模拟数据源，约 550 行。其中的数据分布和内容风格暴露了大量 AI 批量生成的特征。

4.1 用户名/昵称过于规整 [中等]

第 22-62 行定义了 5 个用户。用户名模式过于规整（全是英文词+下划线+拼音姓，如 pro_zhang、carry_chen），昵称过于"人设化"（张小明、李大神、王老板、陈Carry、刘甜甜）。真实用户名通常有数字、大小写混搭、随机后缀（如 xm_2003、LDShen666、甜甜酱w）。

4.2 数值分布过于理想化 [中等]

• 价格：全是整数且多为 5 的倍数（30、40、50），缺少真实定价噪声（如 23、29、33、58）
• 评分：集中在 4.7-4.9，完单率 0.97-0.99，区间极窄，分布过于理想化
• 订单总价：都刚好是服务单价×3（90/120/60），模式过齐

4.3 数据关联不匹配 [严重]

• 打手累计订单数很高（645/832/1256），但全局评论只有 3 条——一个接了 1256 单的打手只有 1 条评价，严重不合理
• 店铺写了 12 名打手、5600 单，但当前只挂了 2 名店内打手，样本关系断裂

4.4 数据结构冗余 [中等]

第 85-86、214-217 行：同一实体重复存储 id+name（如 gameId + gameName、consumerId + consumerName、playerId + playerName）。这种冗余容易导致数据漂移，是 AI "先堆字段再补逻辑"的常见写法。

---

五、类型建模问题

lib/types.ts 定义了全站的 TypeScript 类型。主要问题是约束过松——AI 倾向于用 optional 字段"兜住"所有情况，而不是用联合类型精确建模。

5.1 Order 状态机松散 [严重]

第 76-101 行：Order 类型用大量 optional 字段承载状态机（acceptedAt?、closedAt?、completedAt?、cancelledAt?），但没有按 status 区分的联合类型。例如，一个 status: "pending" 的订单在类型层面也允许有 completedAt，这在逻辑上是矛盾的。应改为按状态区分的判别联合类型。

5.2 其他类型问题 [中等]

位置	问题
types.ts:129-132	ChatSession 的 type 已区分 order/consultation，但 orderId 仍是 optional，缺少判别联合约束（type 为 order 时 orderId 应必填）
types.ts:117-125	Dispute.result 与 status 无联动，resolved 状态时也可无结果
types.ts:18,29,31	Game.category、PlayerService.unit、availability 过宽（全是 string），应使用字面量联合类型
types.ts:112-113	Review.content? + sealed 缺语义关系，允许"无内容且未密封"等不自然组合
全局	时间字段全部裸 string，无 ISO 8601 / epoch 约束

---

六、代码架构问题

6.1 Auth 系统设计缺陷 [严重]

当前的认证系统是一个极简的 Zustand store，存在多个设计问题：

文件	问题
store/auth.ts	login() 函数不接收任何参数（用户信息、token），直接硬编码设置登录状态
store/auth.ts	switchRole() 无权限校验，任何人可切换到任何角色
store/login-dialog.ts	状态过窄，只有 open/close，无法携带"登录后继续动作"的上下文（如用户点了收藏→弹登录→登录后应自动收藏）
lib/use-require-auth.ts	登录成功后不会自动续执被中断的操作
components/header.tsx	用户信息来自 mock 常量而非 auth store，导致状态源分裂

6.2 重复代码 [中等]

以下常量/组件在多处重复定义，应提取到共享模块：

重复内容	出现位置
statusLabels（订单状态中文映射）	app/(order)/orders/page.tsx:15、app/(order)/order/[id]/page.tsx:20、app/(dashboard)/dashboard/page.tsx:12
roleLabels（用户角色中文映射）	app/(main)/community/page.tsx:9、app/(main)/post/[id]/page.tsx:12
侧栏组件结构	components/account-sidebar.tsx 与 components/dashboard-sidebar.tsx 结构高度重复
Layout 壳层	app/(account)/layout.tsx 与 app/(dashboard)/layout.tsx 完全相同的侧栏+内容布局

6.3 过度工程 [低-中等]

位置	问题
app/(main)/search/page.tsx:77,82	对轻量计算（取最小价格、取单位）做了不必要的 useMemo
app/(main)/search/page.tsx:335,354,355	对类型中已标记为必填的 services 字段做防御式 ?. + || [0]
app/(order)/orders/page.tsx:105	JSX 内使用 IIFE（立即执行函数）做条件渲染，降低可读性
store/player-status.ts:9,22	getStatus 是单行包装函数（get().statuses[playerId]），抽象价值很低

6.4 响应式缺失 [中等]

• components/account-sidebar.tsx 和 components/dashboard-sidebar.tsx 固定 w-56，无移动端断点
• 对应的 layout 文件直接常驻侧栏，未做 md: 以上的条件显示
• 移动端用户会看到被侧栏挤压的内容区

6.5 假异步模式 [中等]

以下 5 处使用 await new Promise((r) => setTimeout(r, 500)) 模拟表单提交，是 AI 生成 demo 的典型模式：

• app/(auth)/login/page.tsx:31
• app/(auth)/register/page.tsx:38
• components/login-dialog.tsx:41
• app/(dashboard)/dashboard/services/new/page.tsx:44
• app/(main)/post/new/page.tsx:52

6.6 硬编码问题 [中等]

多处将用户 ID、数据索引等写死，导致页面只能展示特定 mock 数据：

位置	硬编码内容
app/(main)/player/[id]/page.tsx:34	收藏判断写死 userId === "u1"
app/(main)/shop/[id]/page.tsx:29	收藏用户写死 u1
app/(order)/chat/[id]/page.tsx:29	当前用户写死 participants[0]
app/(dashboard)/dashboard/page.tsx:27-28	直接取第一个 player/shop
app/(dashboard)/dashboard/shop/page.tsx:13	固定 mockShops[0]
app/(dashboard)/dashboard/shop/employees/page.tsx:23	写死 shop1

6.7 占位渲染 [严重]

以下位置有图片/上传等功能的数据结构，但 UI 只渲染了占位文字，是明显的原型态残留：

位置	占位内容
app/(main)/post/[id]/page.tsx:70	有图片数据却只渲染「图片」二字
app/(order)/dispute/[id]/page.tsx:81	证据图只渲染「截图」二字
app/(account)/verify/page.tsx:102	身份证上传是静态卡片
app/(dashboard)/dashboard/shop/templates/page.tsx:88	直接写死"原型演示中暂不支持拖拽"

---

七、UI 设计质量

整体评价：项目功能上是完整的 Draft，但视觉上患有"shadcn 默认主题综合征"——看起来像 B2B SaaS 后台管理系统，而不是面向消费者的游戏平台。

7.1 各页面成熟度评级

页面	评级	核心问题
首页 app/(main)/page.tsx	Prototype	Hero 区只是居中文字+两个按钮，零视觉冲击力；三段区块都用"标题+查看全部+卡片列表"重复模板
搜索页 app/(main)/search/page.tsx	Draft（功能好）	筛选/排序/移动端适配做得不错，但卡片信息过密缺视觉层次；整卡可点同时又有「查看详情」按钮，交互语义重复
打手详情 app/(main)/player/[id]/page.tsx	Draft	最通用的 profile 布局（头像左+信息右+Tabs 下），无个性；bio 区是纯灰色盒子
店铺详情 app/(main)/shop/[id]/page.tsx	Draft	不像店铺，像组件列表；banner 文字叠加用最基础的 bg-black/40
登录/注册 app/(auth)/	Prototype	最简表单（图标+标题+输入框+按钮），无背景图/分屏布局/社交登录
订单管理 app/(order)/	Production-ready	状态步骤指示器和上下文操作按钮做得不错
仪表盘 app/(dashboard)/	Production-ready（通用）	零定制，和 shadcn/ui 官方示例一模一样；缺图表/趋势可视化
社区 app/(main)/community/page.tsx	Draft	通用论坛外观，帖子类型无视觉区分；缺最新/最热/关注切换和标签筛选
Header components/header.tsx	Production-ready	功能完整（sticky、backdrop-blur、移动端 Sheet），但缺品牌感
Footer components/footer.tsx	Draft	标准 4 列布局；支持区链接是纯 <span> 不可点击，用户预期会落空

7.2 系统性设计问题

品牌感缺失：app/globals.css 整套 CSS 变量接近黑白灰中性色，没有明确主色和游戏化氛围。作为游戏陪玩平台，视觉上应该有活力和沉浸感，而不是企业后台的冷淡风格。

Card 过度使用：几乎所有内容都装在 <Card> 组件里，1px 边框+白色背景，缺少视觉变化。应该用留白、背景色渐变、字体层级来分隔内容，而不是全靠卡片边框。

微交互缺失：当前 hover 效果只有 hover:shadow-md，缺少 scale 变化、颜色过渡、focus 指示器等。游戏平台用户期望更丰富的交互反馈。

暗色模式未考虑：游戏平台通常偏暗色主题，当前项目完全没有暗色模式的设计考虑。

字体配置不完整：app/layout.tsx 中只配了 Geist 字体的 latin subset，中文站点缺少中文字体配置，中文内容会 fallback 到系统默认字体。

导航设计问题：主导航是「首页/社区/订单/消息」，缺少核心业务入口"找陪玩"或"找店铺"，新用户不知道从哪里开始。移动端抽屉里没有通知入口，和桌面端信息架构不对齐。

---

八、功能完整性（对照 PLAN.md）

PLAN.md 是本项目的需求规格文档。以下列出当前实现与 PLAN 之间的偏差。

8.1 未实现 / 不完整的功能

功能	当前状态	与 PLAN 的偏差
订单状态流转	不完整	只展示状态标签和步骤条，缺少接单、发起结单、确认结单、超时自动流转等可执行动作
争议仲裁	不完整	只有发起争议+静态详情展示，缺少双方举证、平台处理节点、申诉动作闭环
密封评价	未实现	只有文案提示"评价将在双方都提交后公开"，但展示逻辑直接显示评价内容，未实现双方同时揭晓机制
聊天会话	部分实现	有咨询/订单会话标签和只读状态，但缺少咨询转订单、时效关闭、争议期特殊规则
店铺规则设置	未实现	派单模式、多店挂靠、独立接单等规则是只读 Badge 展示，不可配置
钱包分流	未实现	消费者充值和打手/店主提现混在同一界面，PLAN 要求按身份展示不同视图
身份认证审核	不完整	只有"填写→审核中"两个状态，缺少拒绝、补件、重新提交等完整审核状态机
搜索混合展示	未实现	当前只筛选 mockPlayers，PLAN 要求"店铺打手+独立打手混合展示"
社区筛选排序	未实现	缺少时间/热度排序、标签/游戏筛选，PLAN 中有明确要求

8.2 违反 PLAN 的设计 [严重]

位置	问题	PLAN 要求
app/(main)/shop/[id]/page.tsx:67-71	店铺公开页直接展示抽成比例（如"平台抽成 10%"）	PLAN 明确规定消费者不可见抽成比例和打手实收金额
app/(account)/settings/page.tsx:74	设置页可直接切换到 owner/player 角色，无需认证	PLAN 要求打手/店主身份需通过认证申请和审核后才能启用

---

九、优先级建议

P0 — 必须修（违反 PLAN 或严重 AI 痕迹）

1. 删除 emoji 游戏图标，替换为 lucide-react 图标或自定义 SVG 映射
2. 重写首页 hero 和搜索页的 AI 营销文案，使用具体、有人味的表达
3. 统一术语体系（确定"陪玩"还是"打手"，"消费者"还是"玩家"）
4. 修复店铺页泄露抽成比例（违反 PLAN）
5. 修复设置页可绕过认证直接切角色（违反 PLAN）
6. 删除占位渲染和"原型演示"文案

P1 — 应该修（代码质量和数据真实性）

1. 重写 mock 数据使其更真实（用户名加噪声、价格不规整、评分分布拉宽、评价口语化）
2. 收敛重复常量（statusLabels、roleLabels）到 lib/constants.ts 共享模块
3. 加强类型建模（Order 按状态区分的联合类型、ChatSession 判别联合）
4. 修复 auth store 设计（login 接收参数、switchRole 权限校验、登录后续执）
5. 侧栏移动端适配（md: 断点条件显示）
6. 配置中文字体 subset
7. 修复 Footer 支持区链接不可点击

P2 — 设计提升（视觉和交互）

1. 建立品牌色系，替换黑白灰中性色，体现游戏平台氛围
2. 首页 hero 重设计（动态背景、品牌色、视觉冲击力）
3. 减少 Card 过度使用，用留白和字体层级分隔内容
4. 添加微交互（hover scale/color transition、loading skeleton）
5. 暗色模式支持
6. 登录页分屏设计（一侧表单、一侧品牌视觉）
7. 仪表盘添加图表/趋势可视化

P3 — 功能补全（对照 PLAN.md）

1. 订单状态机完整实现（接单→进行中→结单确认→完成，含超时机制）
2. 密封评价双方揭晓机制
3. 争议仲裁完整流程（双方举证→平台处理→结果→申诉）
4. 聊天持久化和实时通信（WebSocket 或轮询）
5. 钱包按身份分流视图
6. 身份认证完整状态机（提交→审核→通过/拒绝→补件→重新提交）
7. 搜索混合展示（店铺打手+独立打手）
8. 社区筛选排序（最新/最热/关注、标签/游戏筛选）