MemRelay/projects/d44c219a-0b31-4de1-b160-323eb34a4c6a/前端与业务实现踩坑及沟通教训.md

title, type, permalink, stable_id, scope, project_id, memory_type, status, revision, restored_from_commit, created_at, updated_at, tags

title	type	permalink	stable_id	scope	project_id	memory_type	status	revision	restored_from_commit	created_at	updated_at	tags
前端与业务实现踩坑及沟通教训	experience	main/projects/d44c219a-0b31-4de1-b160-323eb34a4c6a/前端与业务实现踩坑及沟通教训	67a86e88-a750-4cd8-9650-c1b7cfbf22b9	project	d44c219a-0b31-4de1-b160-323eb34a4c6a	experience	active	1	6a6a895eaf	2026-09-23T15:07:35.309098+00:00	2026-09-23T15:07:35.309164+00:00	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 后彻底清理测试数据（档案/修订/日志/查询计数/上传文件），回滚到种子基线。