银河超市收银系统 (Supermarket POS System)

一个前后端分离的超市收银系统，后端使用 Node.js + SQLite，前端为原生 HTML/CSS/JS。

已完善能力

• 安全
  • JWT 密钥改为环境变量管理（服务重启后 token 不会全部失效）
  • 登录接口增加内存限流（防暴力破解）
  • CORS 支持白名单配置
  • reset-admin 改为: 仅开发环境 + 仅 admin 可调用
• 数据与业务
  • 商品字段严格校验（条码/商品ID/价格/库存）
  • 价格使用 price_cents（分）保存，避免浮点误差
  • 增加库存字段与库存流水
  • 增加结算落库（订单表 + 订单明细表）
• 权限与用户
  • 角色细化: cashier / manager / finance / admin
  • 用户支持: 创建、改角色、禁用/启用、重置密码、删除（保护 admin）
• 工程
  • 新增 /healthz
  • 统一错误响应格式 { success:false, code, message, details? }
• 前端
  • 统一 API 请求封装，token 失效自动清会话并跳登录
  • POS 支持连扫、结算调用后端订单接口
  • 商品管理支持分页、CSV 导出、库存调整
  • 员工管理独立页面（不再和商品管理混合）
  • 销售统计页面（订单列表、汇总、详情）
  • 库存管理页面（库存流水、筛选、汇总）
  • 日志中心页面（系统操作日志查询与筛选）
  • 插件商店页面（插件浏览、筛选、下载安装/卸载）

项目结构

pos/
├── node/
│   ├── package.json
│   └── server.js
├── db/
│   ├── products.db
│   ├── private.db
│   └── users.db
├── docs/
│   └── API.md
├── www/
│   ├── login.html
│   ├── dashboard.html
│   ├── pos.html
│   ├── productsmanagement.html
│   ├── employeemanagement.html
│   ├── sales.html
│   ├── transactions.html
│   ├── inventory.html
│   ├── setting.html
│   └── js/
│       ├── api.js
│       ├── login.js
│       ├── core/
│       │   └── app.js
│       └── pages/
│           ├── dashboard.js
│           ├── employeemanagement.js
│           ├── inventory.js
│           ├── pos.js
│           ├── productsmanagement.js
│           ├── sales.js
│           └── setting.js
└── .env.example

快速启动

1. 安装依赖

cd node
npm install

2. 配置环境变量

将仓库根目录 .env.example 中的变量导入环境，至少设置 JWT_SECRET。

示例（bash）：

export JWT_SECRET="replace-with-a-long-random-secret-at-least-32-chars"
export NODE_ENV="development"
export PORT="3000"
export ALLOWED_ORIGINS="http://localhost:3000"

3. 启动

cd node
npm start

开发模式：

npm run dev

4. 访问

• 登录页: http://localhost:3000/login.html
• 仪表板: http://localhost:3000/dashboard.html
• 收银台: http://localhost:3000/pos.html
• 商品管理: http://localhost:3000/productsmanagement.html
• 员工管理: http://localhost:3000/employeemanagement.html
• 销售统计: http://localhost:3000/sales.html
• 交易记录: http://localhost:3000/transactions.html
• 库存管理: http://localhost:3000/inventory.html
• 健康检查: http://localhost:3000/healthz

页面与角色访问矩阵

页面	admin	manager	finance	cashier
dashboard.html	✅	✅	✅	✅
pos.html	✅	✅	❌	✅
productsmanagement.html	✅（可编辑）	✅（可编辑）	✅（只读）	❌
employeemanagement.html	✅	❌	❌	❌
sales.html	✅	✅	✅	❌
transactions.html	✅	✅	✅	❌
inventory.html	✅	✅	✅	❌
setting.html	✅	✅	❌	❌

首次登录

首次启动会在终端打印 admin 随机密码（只显示一次）。

如果你在开发环境忘记密码，可以用 admin token 调用：

curl -X POST http://localhost:3000/api/reset-admin \
  -H "Authorization: Bearer <admin_token>"

数据库说明

• users.db
  • users: 用户、角色、状态、密码哈希
• products.db
  • products: 商品主数据（price_cents + stock）
• private.db（私有业务数据）
  • inventory_movements: 库存变动流水
  • sales_orders: 销售订单
  • sales_order_items: 订单明细
  • order_receipts: XML 票据
  • system_logs: 系统日志
  • plugin_installs: 插件安装状态

API 说明

详细接口与示例见 docs/API.md。

开发者说明

• 前端统一请求入口：www/js/api.js
  • POSApi.request(...) 自动附带 token，并在 401/403 时自动清会话并跳转登录页
  • POSApi.requireAuth() 用于页面初始化鉴权
• 多语言入口：www/js/core/i18n.js
  • 语言包目录：www/i18n/
  • 当前内置：zh-CN.json、zh-CH.json、en-US.json、ug-CN.json
  • 你可以直接替换/新增语言 JSON（key 不变）来完成翻译
  • 设置页可直接切换语言（默认读取本地 pos_locale）
• 字体切换：
  • 把字体文件放进 www/fonts/（支持 .ttf/.otf/.woff/.woff2/.ttc）
  • 设置页会自动读取可用字体并允许切换
• 前端页面均做了角色守卫，但真正权限以服务端 node/server.js 为准
• 数据库迁移在服务启动时自动执行（补充 price_cents、stock、users.status 等字段）

技术栈

• 后端: Node.js, Express, better-sqlite3, bcryptjs, jsonwebtoken, cors
• 前端: HTML5, CSS3, JavaScript (ES6+), Fetch API

后续建议

• 增加自动化测试（鉴权、商品、结算、权限）
• 提供 Dockerfile 与备份恢复脚本
• 加入操作日志与审计面板