项目仓库地址：https://github.com/hlx-statistics/RetailLog
开源协议：MIT
当前版本：v1.0.0

在零售经营越来越智能化的今天，很多社区便利店、杂货铺依然为没有趁手的记账工具而头疼。本文将带你全方面体验一款完全离线、免费开源、扫码即用的零售管理应用——RetailLog，手摸手教你如何从0到1武装你的门店经营数字助手。

一、前言：社区小店的真实痛点

在连锁便利店全面拥抱数字化的时候，大量社区杂货店、花店、文具店、小超市，仍然处于“手工记账”或者“被迫使用复杂进销存软件”的尴尬境地。

常见的痛点是：动辄上万的 SaaS 年费、需要时刻在线的云端服务、国内网络环境下的加载延迟，以及令人抓狂的复杂商品建档流程……很多小店老板不禁感慨：“我就想用手机扫个码记个账，有那么难吗？”

RetailLog（零售日志） 这个开源项目正是为了解决这一困局而诞生。它的核心理念非常克制且明确：轻量、离线、扫码即用，适合单人打理的小商铺。不需要服务器、不需要注册账号，所有数据完全安全地存储在你的手机上。

它的设计哲学是：“日常卖货以手机连续扫码、看合计金额、一键确认售出为主；顾客付款由店主出示支付宝/微信收款码线下完成，不在 App 内对接支付” 。

二、项目简介：RetailLog 是什么？

RetailLog 是一款面向便利店、杂货店等小商铺的轻量、离线、移动端零售商品与销售管理应用。用手机摄像头扫码建档、连续扫码凑单结账，数据保存在本机，无需服务器。

核心功能一览

• 📷 扫码即用：销售页连续扫码加购，实时合计，一键确认售出并扣库存
• 📦 商品管理：扫码/手动建档，分类筛选、搜索，入库与非销售出库
• 📴 完全离线：IndexedDB 本地存储，无账号、无云服务
• 💾 数据备份：导出/导入 JSON，换机可恢复
• 📱 双端交付：Android APK（推荐店主使用）或 PWA（浏览器/添加到主屏幕）

这个项目最与众不同的点在于它的克制设计：

1. 不做支付：RetailLog 只负责记账与库存扣减，支付完全交给微信/支付宝线下收款码；
2. 一条码 = 一类商品：不做“一物一条码”的复杂追踪，简单实用；
3. 完全离线优先：即使在信号极差的地下商铺、电梯间，也不会影响正常使用。

如果你正在寻找一款无需服务器的本地化零售管理方案，RetailLog 可能是当前开源社区最贴合实际的选择之一。

三、系统架构与技术栈：麻雀虽小，五脏俱全

虽然 RetailLog 定位轻量，但技术选型相当扎实且现代。

技术栈总览

层级	技术选型
前端框架	Vue 3 + TypeScript + Composition API
构建工具	Vite
状态管理	Pinia
路由	Vue Router
本地存储	IndexedDB（idb 库）
扫码引擎	ZXing（@zxing/browser）
原生壳	Capacitor 8（Android）
PWA 支持	vite-plugin-pwa
代码语言	Vue 60%、TypeScript 33.1%、CSS 2.7%

为什么是 IndexedDB？

对于一款完全离线的应用，选对本地存储方案至关重要。IndexedDB 是浏览器原生的非关系型数据库，具备异步读写、支持索引、存储空间大（远超 LocalStorage 的 5MB 限制）等优势。RetailLog 使用 IndexedDB 来存储商品、库存、销售记录、操作日志等数据，实现了不依赖服务器的完整增删改查操作。

为什么是 Capacitor？

Capacitor 是 Ionic 团队推出的跨平台原生应用封装方案。通过将 Vue 构建的 Web 应用嵌入 Capacitor 容器，RetailLog 可以调用原生摄像头（扫码）、文件系统（备份导出）、震动反馈等能力，并直接构建为标准 Android APK。

Capacitor 相较 Cordova 更现代化，原生插件生态更好，支持热更新，是 Web 前端向移动端“靠拢”的不错选择。

四、业务需求深度解析：设计哲学

一个真正好用的工具，必然基于对用户真实工作流的深刻理解。RetailLog 的需求文档十分详尽（300+ 行），我们剖析几个核心设计决策。

4.1 扫码体验：连续扫、防抖、视觉反馈

RetailLog 的销售页顶部常驻摄像头预览，这是整个应用使用频率最高的交互路径。核心逻辑如下：

• 每扫一次：若商品已存在 → 销售单对应行数量 +1；若不存在 → 询问是否跳转建档；
• 同条码防抖 1000ms：防止同一商品被连续误扫多次；
• 扫码成功反馈：短震动 + 全屏闪白效果，给予清晰的操作确认；
• 支持 EAN-13、EAN-8、UPC-A、UPC-E、CODE_128：覆盖市面上绝大多数零售商品条码格式。

4.2 库存模型：简单即高效

RetailLog 遵循“一条码 = 一类商品（SKU）”的简化原则。例如同一品牌矿泉水，瓶身条码相同，扫码一次代表将一件加入销售单，可多次扫描累加数量。售出后直接扣减对应商品的 stock 数量，不维护单件商品的“已售/未售”状态。

这种简化方案有效避免了复杂的批次管理需求，非常适合品种少、周转快的社区小店。

4.3 数据备份：JSON 全量导出，换机不慌

数据安全是离线应用的生命线。RetailLog 支持将商品、分类、销售记录、操作日志全部导出为一份 JSON 文件，文件名格式为 RetailLog_backup_YYYYMMDD_HHMMSS.json。换机时只需导入 JSON 文件即可恢复全部数据，全程无需联网。备份采用结构化 BackupData 格式（version: 2），数据结构清晰可读。

五、核心功能实现解析

5.1 商品管理闭环

RetailLog 商品管理支持完整链路：

• 手动添加：填写名称、条码、售价、分类、库存等字段
• 扫码添加：弹窗取景 → 识别条码 → 打开表单并自动预填条码
• 扫码查找：扫描已有商品条码，定位到对应商品卡片
• 编辑/删除：支持修改全部字段，删除前二次确认

商品列表按 updatedAt 倒序排列，库存 ≤ 0 显示为空库存特殊样式，< 5 显示低库存警告色，让店主一眼识别需要补货的商品。

5.2 销售结账流程（核心场景）

销售结账是 RetailLog 的“心脏”，完整流程如下：

1. 扫码加购：进入“销售”Tab，顶部摄像头常驻预览区，每次扫码成功，对应商品数量 +1；
2. 手动调整：每行商品支持 +/− 调整数量，减至 0 自动删除该行，支持清空整单；
3. 实时合计：底部实时显示合计件数和合计金额，一目了然；
4. 确认售出：点击“确认售出” → 二次确认件数与金额 → 提交前校验库存，任意行库存不足则整单不提交并提示明细 → 成功后写销售记录、扣减库存、写操作日志、清空购物车。

值得一提的是，整个流程不触发任何支付界面，收款由顾客扫店主的支付宝/微信收款码线下完成。

5.3 库存进出操作

入库操作从商品列表卡片直接触发，输入入库数量后自动写入库存日志；出库操作同样从卡片操作，超库存时抛出 INSUFFICIENT_STOCK 错误，保障库存不会被错误扣至负数。

5.4 离线存储与数据恢复

RetailLog 的所有业务数据完全存储在 IndexedDB 中。应用启动时初始化默认分类（食品、饮料、日用品、其他），若无商品数据则写入示例数据，确保开箱即用。数据恢复流程为先清空四表后导入，保障恢复后数据状态的一致性。

六、本地部署与实战指南

无论你是想直接使用，还是想基于此二次开发，下面的步骤都能帮到你。

6.1 普通用户：下载 APK 直接使用

如果你是店主，直接下载 APK 安装最方便。去项目的 Releases 页面 下载最新版 RetailLog-*.apk。

Android 安装步骤：

1. 打开 最新发行版，在 Assets 中下载 APK（例如 RetailLog-v1.0.0.apk）；
2. 将文件传到手机（微信、网盘、数据线等），点击安装；
3. 若系统提示“未知来源”，在系统设置中允许该来源安装应用。

6.2 开发者：从源码运行

环境要求

• Node.js 18+
• npm 9+（或兼容的包管理器）

Web 开发模式

git clone https://github.com/hlx-statistics/RetailLog.git
cd RetailLog
npm install
npm run dev

浏览器访问 http://localhost:5173 即可看到运行效果。

构建 Android APK

构建 APK 需要先准备好 Android Studio 与 Android SDK，具体步骤参见仓库文档中的 Android 打包指南。

npm install
npm run cap:sync      # 构建并同步到 android/
npm run cap:android   # 用 Android Studio 打开并 Build APK

调试包输出路径为：android/app/build/outputs/apk/debug/app-debug.apk。正式发布请在 Android Studio 中配置签名并构建 release 包。

七、项目结构与源码导读

RetailLog 的工程结构清晰简洁，便于阅读理解与二次开发：

RetailLog/
├── src/                  # Vue 应用源码
├── public/               # 静态资源
├── android/              # Capacitor Android 工程
├── docs/                 # 需求与规范文档
├── capacitor.config.ts   # Capacitor 配置
└── package.json

关键源码入口：

• 扫码销售页：核心交互逻辑位于 SaleView，顶部常驻摄像头预览，支持连续扫码加购
• 商品管理模块：goodsService 负责 IndexedDB 中的商品增删改查，按 updatedAt 倒序列表展示
• 库存操作：stockService.stockIn / stockService.stockOut，出库时检查库存充足性
• 数据备份恢复：导出使用 BackupData 格式（version: 2），通过 Capacitor 文件系统或浏览器下载实现

建议开发者重点阅读 docs/01.需求文档.md 了解完整业务逻辑，再结合源码对照理解。

八、适用场景与未来展望

当前最适合的使用场景

• 🏪 社区便利店：快速扫码结账，实时库存管理
• 🌸 花店、文具店：品种简单，单人经营
• 🛒 集市摊位：可离线使用，不受场地网络限制
• 💡 学生/自由职业者：管理少量商品库存，完全免费

未来可能的扩展方向（社区共建）

• 📊 销售统计图表与趋势分析
• 👥 多店员协作（多设备同步）
• ☁️ 可选的云端同步备份
• 🖨️ 小票打印支持
• 🌐 多语言国际化

项目当前为 v1.0.0 版本，已完整实现核心业务闭环。欢迎社区开发者通过 Issue 反馈问题或通过 Pull Request 提交改进。

九、总结与思考：离线应用在零售场景中的价值

RetailLog 是一个小而美的技术实践范例。作为2026年5月最新发布的开源项目，它的技术栈非常现代化——Vue 3 Composition API + TypeScript + Vite + Capacitor——为希望学习移动端 Web 应用开发的开发者，提供了一个理想的项目参考模板。

从市场角度看，这个项目也很有价值。全球零售分析市场预计到2026年将达113.1亿美元，年复合增长率约12.8%，零售终端正从“经验依赖”向“数据驱动”转变。RetailLog 这样的轻量工具，让最基层的零售从业者也能享受到数字化带来的效率提升。

从架构哲学上讲，RetailLog 也给我们带来了一个很有价值的示范：“离线优先”不应该被视为一种妥协，而应当是一种重要的产品设计策略。在网络环境不确定的场景下（如地下商铺、偏远地区），真正的离线可用性带来的用户体验优势，是任何基于云端的方案都无法替代的。

如果你正在寻找一个开源的零售管理工具，或者想学习移动端前端开发的最佳实践，不妨给这个项目点个 Star，一起参与建设：hlx-statistics/RetailLog。

版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。文中部分内容参考自 RetailLog 项目 README 及需求文档。