REA这个名字最初只是项目文件夹里随手敲的三个字母没想到后来成了我们团队内部叫得最顺口的代号。它不是某个开源框架也不是什么商业产品而是一个我从零开始搭起来的跨端应用方案——Real-time Experience Assistant实时体验助手。简单说就是让现场工作人员用手机或平板就能快速记录体验数据、实时查看统计结果同时能忍受各种不稳定的网络环境。如果你的工作里也有现场数据收集实时反馈这种需求或者你就是想看看一个小项目从想法到落地需要踩多少坑这篇文章应该对你有用。写这篇文章的初衷很朴素我翻了翻之前做REA时留下的笔记发现太多细节当时没记录现在回忆起来已经模糊了。所以想趁着还有印象把整个设计思路、技术选型、核心代码和排查过程都整理出来既是对自己的复盘也希望能给准备做类似工具的朋友一点参考。项目本身不算复杂但麻雀虽小五脏俱全从前端交互到后端接口从离线缓存到数据同步该遇到的问题一个都没少。1. 为什么是REA项目需求与目标拆解很多项目失败不是因为技术不行而是因为一开始就没想清楚要解决什么问题。REA这个项目能顺产下来靠的恰恰是先花了大量时间做需求拆解。1.1 从一个痛点出发现场数据收集为什么难当时面对的实际情况是这样的每次做现场活动或门店巡检都需要工作人员拿着纸质表格或者用通用表单工具去收集数据。纸质表格的问题不用多说后期录入费时费力还容易出错。通用表单工具虽然解决了电子化记录的问题但有几个绕不过去的坎。第一个坎是实时性。通用表单工具提交完数据后想看统计结果通常需要登录后台导出或者等系统刷新现场负责人根本无法在第一时间看到现在收集了多少条哪些选项被选得最多。第二个坎是网络依赖。活动现场的网络环境往往比想象中差地下室、户外广场、人多的会场手机信号忽好忽坏表单提交经常失败。第三个坎是数据分散。每个工作人员各填各的同一个场地不同入口收集的数据是割裂的事后汇总要花大量时间。我需要的不是一个大而全的客户管理系统而是一个足够轻、足够快、能容忍网络故障的小工具。REA的雏形想法就是这么来的。1.2 REA的核心定位与功能边界REA的全称是Real-time Experience Assistant翻译过来就是实时体验助手。名字听起来有点大实际功能却很克制只有三个核心模块。第一个是快速记录。工作人员打开页面选择场景类型、填写少量必填信息、点提交整个操作控制在十秒以内。第二是实时统计。所有提交成功的记录会立刻汇总到统计面板按时间、按场景类型、按评价等级进行热更新展示。第三是离线容灾。当网络不可用时提交操作不会直接失败而是先存在本机缓存里网络恢复后自动同步到服务器。功能边界从一开始就划得很清楚不做账号权限分级不做复杂的报表导出不做消息推送不搞移动端原生App。所有东西都通过浏览器访问这样省掉了安装和版本更新的麻烦。事实证明这种少即是多的思路帮了大忙开发周期从预期的一个月压缩到了两周。1.3 用户画像与典型使用场景我把目标用户分成两类一类是现场的普通工作人员他们只需要完成提交动作用的设备是手机或手持终端另一类是现场的管理人员他们需要看统计面板用的设备可能是平板或电脑。第一个典型场景是商场或展会活动。入口处的工作人员引导顾客完成体验评价提交数据实时汇总到大屏负责人能随时看到各时段的客流反馈。第二个典型场景是门店巡检。巡检员每到一个门店记录商品陈列、卫生状况、服务态度等几个维度的状态总部实时掌握巡查进度。这两个场景有共同点移动端为主、操作要快、网络不稳定、管理人员需要实时数据。REA的所有设计决策几乎都是从这两个场景倒推出来的。2. 技术选型用尽量轻的工具搭出能用的系统技术选型这件事很多人喜欢追新什么热门用什么。我的原则恰恰相反在满足需求的前提下选最熟、最稳、最容易维护的方案。REA的选型过程是这样走下来的。2.1 前端框架为什么没有选更复杂的方案前端部分当时在Vue3和React之间犹豫了一阵最终选了Vue3。原因很实际团队成员对Vue的熟悉度更高单文件组件的写法让模板、脚本、样式放在一起小项目里维护起来特别直观。而且Vue3的响应式系统处理大量的实时数据更新时性能表现足够好不需要额外引入状态管理库。我没有选择原生JavaScript虽然这个项目的页面数量不多逻辑也不算复杂但考虑到后续可能会加功能用框架能少写很多DOM操作的代码。也没考虑React不是因为它不好纯粹是团队熟悉度问题。选型这种事没有绝对的对错只有适不适合当前团队和项目。前端只需要一个入口页面加上两个视图记录表单和统计面板。我用Vue Router做了简单的路由切换没有搞复杂的动态路由因为场景就这两类不需要各种权限控制。2.2 后端与数据存储单机部署的务实选择后端选型是REA项目里最纠结的部分。有人建议上微服务有人建议用容器编排都被我拦住了。一个日均提交量最多几千条的小工具完全不需要那些重武器。后端我用的是一个轻量级的Node.js框架部署在一台普通的小服务器上。数据库选择SQLite理由非常简单它就是一个文件不需要单独安装数据库服务备份只需要复制文件对于这个量级的数据完全够用。接口设计遵循RESTful风格总共只有五个端点分别对应提交记录、获取统计、同步离线数据、查询单条记录、健康检查。有些朋友可能会问不用MySQL或PostgreSQL这类数据库是不是不够专业我的回答是要看你处理什么规模的数据。SQLite在千万级数据量以内性能都不成问题对于REA这种现场采集工具它是最省心的选择。我见过太多项目动不动就上集群、上消息队列结果一半的时间都在处理基础设施的问题而不是业务本身。2.3 离线能力一开始就当作核心功能来设计离线容灾不是后期补上的功能而是REA从一开始就在架构层面考虑的事情。设计思路分三层。第一层是浏览器本地缓存。提交数据时先写入本地的IndexedDB然后再发起网络请求。第二层是同步队列。网络请求成功就把本地这条标记为已同步失败则保留在队列中等待重试。第三层是定期重试机制。页面会监听网络状态变化断网重连后自动触发同步同时每隔一段时间也会做一次兜底重试。这个设计有一个关键点本地写入和服务器写入不能走同一个成功判定。有些方案是等服务器返回成功才写本地这在弱网环境下几乎每次都会卡住。REA的做法是本地先落库界面立即反馈成功后台再慢慢同步。代价是可能出现短暂的数据不一致但对这种收集工具来说用户体验优先而且最终一致性的模型完全够用。3. 从零实操REA项目的搭建与落地理论部分说了不少下面进入真正的实操环节。我会按照当时的实施顺序把每一步的关键操作、配置命令和核心代码都列出来你可以直接照着做。3.1 环境准备与项目初始化首先确认本机已经安装了Node.js运行环境。版本要求不需要很高16以上就足够我当时用的是某个长期支持版本。包管理器推荐使用npm它随Node一起安装不需要额外配置。前端项目用Vite来初始化命令如下npm create vitelatest rea-web -- --template vue cd rea-web npm install npm install vue-router4 npm run dev执行完这几条命令浏览器打开终端输出的本地地址就能看到Vite的默认页面。我习惯先把默认的组件清理掉只保留根组件和路由出口。后端项目单独建一个目录不跟前端混在一起方便后续独立部署。mkdir rea-server cd rea-server npm init -y npm install express better-sqlite3这里用了better-sqlite3而不是sqlite3区别在于它是同步API写代码的时候不用纠结回调或Promise对于这个项目来说足够方便而且性能也不错。3.2 数据模型与接口设计REA的数据模型不复杂核心就一张记录表和一张场景表。记录表存每次提交的内容场景表存可选的场景类型。记录表的核心字段包括主键ID、场景ID、评价等级、备注内容、设备编号、创建时间、同步状态。其中同步状态是离线设计的关键字段取值为pending或synced。评价等级我设计成1到5的整数方便统计平均值和分布。场景表就比较简单了就是场景名称和启用状态。有些场景临时不用了通过状态字段软禁用不需要真的删除数据。接口设计遵循RESTful风格核心是三个主要端点POST /api/records提交新记录参数为场景ID、评价等级、备注、设备编号。GET /api/records/stats获取统计结果支持按时间范围和场景筛选。POST /api/records/sync批量同步离线数据参数为一个记录数组。特意说明一下为什么提交接口和同步接口是分开的。在线提交是单条实时请求数据量小适合用户交互批量同步是网络恢复时的一次性补偿操作可能一次带几十条甚至几百条数据逻辑上必须独立。如果混在一起会出现某条数据同步失败导致整个请求失败的情况。3.3 前端页面与核心逻辑实现前端部分核心在三个地方表单提交逻辑、IndexedDB缓存、统计视图渲染。先说表单提交逻辑。页面加载时先获取场景列表用户选择场景、输入评价、点击提交后页面不直接发起网络请求而是先把记录写入IndexedDB。写入成功后立即显示提交成功然后在后台发起网络请求。// 提交表单处理 async function handleSubmit() { const record { sceneId: selectedSceneId.value, rating: selectedRating.value, note: noteText.value, deviceId: getDeviceId(), createdAt: Date.now(), syncStatus: pending }; // 先写入 IndexedDB保证本地有备份 await saveToLocalDB(record); // 显示提交成功更新 UI showToast(提交成功); // 后台尝试同步 syncQueue(); }这里的代码逻辑关键点是界面的成功反馈来源于本地写入成功而不是服务器响应。用户几乎感知不到网络延迟也不会因为网络抖动看到提交失败的报错体验提升非常明显。然后是IndexedDB封装。直接在项目里引了一个轻量的封装库或者自己写也行。我选择了自己写一个简单的封装因为CRUD操作不多不用引入额外的依赖。核心就四个方法插入、查询所有未同步记录、标记同步成功、清除已同步记录。// 打开数据库 function openDB() { return new Promise((resolve, reject) { const request indexedDB.open(rea-db, 1); request.onupgradeneeded (e) { const db e.target.result; if (!db.objectStoreNames.contains(records)) { const store db.createObjectStore(records, { keyPath: id, autoIncrement: true }); store.createIndex(syncStatus, syncStatus, { unique: false }); } }; request.onsuccess () resolve(request.result); request.onerror () reject(request.error); }); }写IndexedDB的时候有个易错点索引的创建必须在onupgradeneeded版本变更事件里完成如果你在数据库打开成功后再去创建索引会直接报错。我第一次做的时候就踩了这个坑排查半天才反应过来。统计视图的渲染用到了Vue3的computed计算属性。每当新的记录同步成功数据源变化后统计面板自动重算。展示的内容包括总记录数、平均评分、按评价等级分布、按时间段趋势。由于是移动端页面我用了最简单的CSS Flex布局没有引入图表库而是用色块和进度条展示分布情况加载速度快看起来也直观。3.4 部署与日常使用配置开发完成之后部署环节同样有不少细节。前端构建命令是npm run build构建产物在dist目录是一个纯静态目录。我用的是一个极轻量的静态文件服务器来托管前端资源和提供后端API。前后端通过反向代理配置关联前端请求的接口路径统一用/api开头代理到本机后端端口。SQLite数据库文件放在服务器的数据目录下权限设置为仅服务账户可读写避免暴露在公网访问路径上。备份策略是每天凌晨用定时任务复制一份数据库文件到备份目录保留最近三十天的备份。数据量不大这个策略足够可靠。环境变量配置需要设置的有服务端口、数据库文件路径、允许跨域的来源列表。跨域只允许正式域名访问测试的时候单独开一个临时的跨域配置防止线上环境被未知来源刷接口。启动服务不需要特别复杂的进程守护工具我直接用了终端面板的守护方式配置了开机重启策略。4. 现场踩坑与排查实录纯理论讲得再多都不如实际踩坑来得深刻。REA上线后遇到的这些问题每一个都是真实发生的排查过程也很有代表性。4.1 网络错误处理提交失败后的数据丢失REA上线后的第一次小范围测试就翻车了。现场网络状况很差有工作人员反映明明页面提示提交成功后台却没有数据。排查发现问题出在我的同步逻辑上同步请求失败后我捕获了异常但是只是打印了日志没有把记录重新加入待同步队列导致这批记录留在本地却永远不会再次尝试。修复方案很简单在catch块里只要网络错误是暂时的比如超时、断网就保留syncStatus为pending等待下一轮重试。只有服务器明确返回数据格式错误这类永久性错误时才把记录标为failed避免无限重试浪费资源。这个问题的教训是任何涉及到离线存储的功能都要把失败后的状态流转画出来不能只考虑成功路径。你以为的兜底逻辑往往在异常分支里悄悄漏掉了。4.2 时间统计跨日问题时区和日期选择统计功能上线后有管理员反馈凌晨查看统计时数据走势图不对。排查后发现是时区问题。前端页面运行时使用的Date对象是基于用户本机的时区而后端存储和查询用的是服务器的默认时区。当服务器是UTC时区、访问者是东八区时凌晨零点前提交的数据会被归到前一天。解决方案是统一时间标准。所有数据在写入时都先将时间转换为ISO字符串用UTC格式存储前端展示时再转换为本地时区。具体到统计查询参数传的是ISO格式的时间戳后端按UTC处理。这样无论访问者在哪里看到的时间趋势都是基于同一套时间轴的。顺手也写了个工具函数处理今日0点这类常见需求避免每次都需要写时区转换代码。4.3 多人同时提交的数据一致性问题墙面管理面板有时会出现统计数字突然跳动的情况比如总记录数先增加后减少。刚开始以为是自己代码算错了后来排查发现是并发带来的幂等性问题。问题出在设备编号上离线队列重试时如果用户连续提交了两条一模一样的记录由于IndexedDB的自动增量ID在每次重试时可能会重新生成服务器端找不到唯一标识就会把这两条当成不同记录处理出现重复数据。解决方式是在前端生成一个全局唯一的记录ID在首次提交时就生成好无论是本地缓存还是服务端存储都以这个ID为准。服务端接口增加一个去重判断如果ID已存在直接返回已保存的状态。这个改动解决了重复计数的问题。4.4 性能调优大数据量下的卡顿使用一个月后有一台设备的记录数突破了二十万条。统计面板开始出现明显的卡顿。排查发现卡顿的根源是统计接口返回全量数据前端再逐一计算分布。数据量小的时候没问题数据量大了执行时间线性增长。优化思路分了两步。第一步是后端在SQL查询阶段就完成分组统计前端只需要接收聚合结果而不是原始明细。第二步是给记录表添加了时间字段的索引让按时间范围的过滤查询走索引而不是全表扫描。这两步操作之后统计接口的响应时间从一点几秒降到了几十毫秒。顺便也把主列表的分页做上了避免一次性返回大量明细数据。4.5 常见问题速查表整理了几个反复被问到的问题做成速查表方便现场人员自查。问题现象可能原因处理办法提交后提示成功但没有数据同步未触发或失败检查网络连接刷新页面后查看待同步队列统计数字重复增加重复提交了相同记录服务器端去重检查记录ID凌晨统计的日期错位时区未统一确认前后端时间均用ISO字符串处理页面加载很慢统计接口全量查询后端改为聚合统计前端分页展示本地数据库写入失败IndexedDB容量不足或被清理主动清理三个月前的已同步记录这个表看上去简单但每一条背后都对应过一次真实的故障和一段排查过程。我后来把它打印出来贴在运维手册里新同事遇到类似问题时能直接对照排查。说到实战心得我的体会是做小项目的时候最容易犯的错误是低估异常处理和边界情况的复杂度。功能路径走通了只是起点数据一致性、状态流转、时区、并发这些看似不起眼的细节才是真正消耗时间的地方。另外还有一个小技巧值得分享给所有接口都加上一个简单的日志中间件记录请求路径、耗时和状态码。REA遇到的大部分问题排查的第一步都是翻日志。没有日志就只能靠猜测效率会低很多。日志不用很复杂一行JSON就够用但一定要有。