---
title: 前端与业务实现踩坑及沟通教训
type: experience
permalink: main/projects/d44c219a-0b31-4de1-b160-323eb34a4c6a/前端与业务实现踩坑及沟通教训
stable_id: 67a86e88-a750-4cd8-9650-c1b7cfbf22b9
scope: project
project_id: d44c219a-0b31-4de1-b160-323eb34a4c6a
memory_type: experience
status: active
revision: 1
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
created_at: '2026-09-23T15:07:35.309098+00:00'
updated_at: '2026-09-23T15:07:35.309164+00:00'
tags:
- frontend
- communication
- pitfall
- lesson
---

前端：
- PC 点击轮播卡片打不开查看器：`pointerdown` 即 `setPointerCapture` 会把后续 click 改派到容器，改为确认横向拖动后才捕获。
- 轮播无缝循环：首尾各加克隆张，`transitionend` 时无动画跳回真实张。
- 上传 FormData 不要手动设 Content-Type（交由 axios 设边界）。
- C 端切换短码不刷新：需 watch route param。
- 上链状态前端 `rowIsOnchain` 要认 ONCHAIN/CONFIRMING/PENDING（确认中即已上链不可重触），仅 FAILED 可重试。
- 接口入参：多处 `BigInt(id)` 非法入参会 500，统一用 `parseBigId` 返回 400。

业务实现：
- 首扫激活必须条件更新 `updateMany(where:{id,status:INACTIVE})`，“读后写”并发会双重首扫且丢增量。
- 备份恢复端必须校验 app/版本/模型全集，否则残缺包会清库（先清后写）。
- “先写库后入队”需入队失败补偿（回写 FAILED/回滚），Redis 抖动否则留悬挂记录。
- `hashData` 必须稳定序列化（JSON.stringify 受 key 顺序影响）。
- `void promise` 无 catch 会 unhandled rejection（操作日志拦截器曾中招）。
- ZIP 解析：倒序定位真实 EOCD/ZIP64，按实际解压字节流计数，不能信任中央目录声明大小；`100002` 条目是防恶意内存耗尽的技术阈值非业务上限。

沟通教训：
- 用户描述“显示 X 而不是 Y”大概率是吐槽现状 X、想要 Y（AppKey 掩码事件连错两轮），拿不准先确认。
- UI 布局任务必须附截图级验收标准，否则容易做成“能编译但难看”。
- 甲方“不做 NFT”、“SKU”等用词与技术含义不同（实为不做二级交易 / 一款档案），关键口径必须反复澄清后再动模型。
- QA 后彻底清理测试数据（档案/修订/日志/查询计数/上传文件），回滚到种子基线。