基于 Vue 3、Express、TypeScript、MySQL 8 与 Apache IoTDB 的前后端分离库存管理项目。系统把商品、用户、订单、地址、库存当前值等强事务业务数据存放在 MySQL，把库存变动和销量趋势写入 IoTDB，用于后台分析图表展示。

这个仓库已经不是“纯方案骨架”，而是一个可直接运行、可演示的最小闭环实现：

• 客户端支持客户/管理员注册、登录、退出、地址管理、浏览商品、下单、模拟支付、查看订单
• 管理端支持商品增删改查、上下架、图片上传、条形码查看、库存调整、库存预警、订单处理、IoTDB 趋势分析
• 后端已实现操作日志、CSV/Excel 导出、备份恢复、登录失败锁定、页面权限配合接口权限控制
• 启动时会自动补充演示数据，并将 MySQL 中的库存/销量记录回填到 IoTDB

• 用户注册、管理员注册、登录、退出、JWT 鉴权、登录失败锁定
• 客户地址管理、商品浏览、库存展示、低库存提醒
• 客户下单、模拟支付、查看订单详情
• 管理员商品新增、编辑、删除、上下架、图片上传、条形码查看
• 管理员库存录入/调整、库存日志查询与导出
• 管理员订单搜索、分页、筛选、详情查看、状态流转
• 管理员系统参数配置、操作日志查看、数据备份恢复
• 基于 IoTDB 的销量趋势、库存变化趋势、饼图展示与导出

• 管理员注册采用注册码模式，避免公开放开管理员账号创建
• 图片上传采用前端读取后以 Base64 JSON 提交，未引入 multipart 中间件
• Excel 导出采用 Excel 可直接打开的 .xls 制表格式，适合课程设计场景
• 备份恢复以业务数据 JSON 为主，恢复后会自动重建 IoTDB 时序数据

详细对照说明见 docs/requirements-gap.md。

• Vue 3
• Vite 8
• Vue Router 5
• Pinia 3
• Element Plus 2
• ECharts 6

• Node.js 20+
• Express 5
• TypeScript 6
• Zod 参数校验
• JWT 鉴权
• bcryptjs 密码加密
• mysql2 数据访问

• MySQL 8 保存业务主数据
• Apache IoTDB 1.3.x 保存库存与销量时序数据
• Docker Compose 负责本地一键启动数据库与容器化服务
• Nginx 用于前端生产构建产物分发

MySQL 保存强事务与关系型主数据，当前表结构定义在 database/schema.sql：

• users：用户、角色、账号状态
• addresses：收货地址
• categories：商品分类
• products：商品信息、当前库存、预警阈值、上下架状态
• orders / order_items：订单头与订单明细
• inventory_logs：库存变动日志
• system_configs：系统配置
• operation_logs：操作日志预留

IoTDB 保存时序事件，当前按商品维度建库：

• root.lotdb_inventory.product_{productId}
  • change_qty
  • current_stock
  • operator_id
  • event_type
• root.lotdb_sales.product_{productId}
  • sold_qty
  • sales_amount
  • order_id

• 库存调整成功后，写 MySQL inventory_logs，再写 IoTDB 库存事件
• 订单创建成功后，更新 MySQL 订单与库存，再写 IoTDB 销量事件和出库事件
• 订单取消时，回补 MySQL 库存，并向 IoTDB 写入回补库存与负销量记录
• 服务启动时会扫描 MySQL 中已有的库存日志和已支付订单，自动回填到 IoTDB

• controllers：处理请求与响应
• services：聚合业务逻辑
• middlewares：JWT 鉴权、RBAC、异常处理
• utils/db.ts：SQL 查询、事务与连接封装
• services/iotdb.service.ts：IoTDB REST 调用、建库、写入、查询

• 订单创建与库存调整都通过 MySQL 事务执行
• 订单支付与库存调整会对涉及商品做 FOR UPDATE 行锁，避免并发超卖
• IoTDB 属于分析侧存储，采用事务后异步补写策略

后端启动时会执行 initializeApplication()，在空库场景下自动完成：

• 初始化商品分类
• 初始化 3 个演示商品
• 初始化客户账号 buyer
• 为 buyer 预置默认收货地址
• 初始化库存日志
• 创建 1 笔演示订单
• 将库存与销量事件回填到 IoTDB

• /login：登录
• /register：客户/管理员注册
• /customer/products：商品列表与创建待支付订单
• /customer/addresses：地址管理
• /customer/orders：订单列表、详情、模拟支付

• /admin/products：商品增删改查、上下架、图片上传、条形码查看
• /admin/inventory：库存调整、低库存预警、库存日志导出
• /admin/orders：订单搜索、分页、详情、状态流转、导出
• /admin/analytics：IoTDB 销量趋势、库存变化趋势、饼图、数据导出
• /admin/settings：系统设置、操作日志、备份恢复

所有后端接口基于 /api/v1，统一响应格式如下：

{
  "code": 0,
  "message": "success",
  "data": {}
}

鉴权接口使用：

Authorization: Bearer <token>

当前接口分组：

• POST /auth/register
• POST /auth/register-admin
• POST /auth/login
• POST /auth/logout
• GET /auth/profile
• GET /addresses
• POST /addresses
• PUT /addresses/:id
• DELETE /addresses/:id
• GET /products
• POST /products/upload-image
• GET /products/:id/barcode.svg
• GET /products/:id
• POST /products
• PUT /products/:id
• PATCH /products/:id/status
• DELETE /products/:id
• GET /inventory/logs
• GET /inventory/logs/export
• POST /inventory/adjust
• POST /orders
• POST /orders/:id/pay
• GET /orders/export
• GET /orders
• GET /orders/:id
• PATCH /orders/:id/status
• GET /analytics/sales/export
• GET /analytics/sales
• GET /analytics/inventory/export
• GET /analytics/inventory
• GET /settings/logs
• GET /settings/logs/export
• GET /settings/backup
• POST /settings/restore
• GET /settings
• PUT /settings

更详细的请求示例见 docs/api.md。

.
├── backend/
│   ├── src/
│   │   ├── config/          # 环境变量与 MySQL 连接
│   │   ├── controllers/     # 控制器
│   │   ├── middlewares/     # 认证、鉴权、错误处理
│   │   ├── repositories/    # 预留目录
│   │   ├── routes/          # 路由入口与模块路由
│   │   ├── services/        # 核心业务逻辑与 IoTDB 读写
│   │   ├── types/           # 扩展类型声明
│   │   └── utils/           # DB、鉴权、通用工具
│   ├── Dockerfile
│   ├── package.json
│   └── tsconfig.json
├── frontend/
│   ├── src/
│   │   ├── api/             # fetch 封装与接口模块
│   │   ├── components/      # 复用组件
│   │   ├── layouts/         # 客户端 / 管理端布局
│   │   ├── router/          # 路由定义
│   │   ├── stores/          # Pinia 状态
│   │   ├── styles/          # 全局样式
│   │   └── views/           # 页面视图
│   ├── Dockerfile
│   ├── nginx.conf
│   ├── package.json
│   └── vite.config.ts
├── database/
│   └── schema.sql           # MySQL 初始化脚本
├── docs/
│   ├── api.md
│   └── implementation-plan.md
├── docker-compose.yml
├── package.json
└── pnpm-workspace.yaml

• Node.js 20 或更高版本
• pnpm 10
• Docker Desktop 与 Docker Compose

建议先启用 Corepack：

corepack enable

后端会按以下顺序读取配置：

1. backend/.env.example
2. backend/.env
3. 进程环境变量

推荐先复制：

cp backend/.env.example backend/.env

关键变量如下：

推荐复制：

cp frontend/.env.example frontend/.env

关键变量：

注意：当前 Docker Compose 与 Dockerfile 默认使用的是示例环境文件。若你要调整容器中的配置，需要同步修改 backend/.env.example、frontend/.env.example 或直接修改 docker-compose.yml。

适合开发前后端代码，数据库依赖使用 Docker。

docker compose up -d mysql iotdb

pnpm install

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

pnpm run dev:backend

pnpm run dev:frontend

• 前端开发服务：http://localhost:5173
• 后端健康检查：http://localhost:3000/health
• 后端 API 基址：http://localhost:3000/api/v1
• IoTDB REST：http://localhost:18080

适合快速演示整套系统：

docker compose up -d --build

启动后可访问：

• 前端：http://localhost:5173
• 后端：http://localhost:3000
• MySQL：localhost:3306
• IoTDB：localhost:6667
• IoTDB REST：http://localhost:18080

• docker-compose.yml 已将 database/schema.sql 挂载到 MySQL 初始化目录
• 当 MySQL 数据卷为空时，容器首次启动会自动建库建表并写入默认管理员账号
• 如果你使用的是本机已有 MySQL，需要手动执行：

mysql -uroot -p123456 < database/schema.sql

如需彻底重置演示数据，可删除容器卷后重新启动：

docker compose down -v
docker compose up -d mysql iotdb

• 管理员：admin / Admin@123
• 管理员手机号：13800000001
• 演示客户：buyer / Admin@123
• 演示客户手机号：13800000002
• 管理员注册码：LOTDB_ADMIN

• 3 个演示商品
• 3 个演示分类
• buyer 默认地址 1 条
• 初始化库存日志
• 已支付演示订单 1 笔

这意味着首次成功启动后，管理员可以直接看到库存日志和分析图表，客户也可以直接查看订单。

pnpm run build:backend
pnpm run build:frontend

对应工作区脚本：

• pnpm run dev:backend
• pnpm run dev:frontend
• pnpm run build:backend
• pnpm run build:frontend

1. 使用 admin / Admin@123 登录
2. 查看商品列表
3. 在库存管理页做一次入库或出库调整
4. 查看库存日志和低库存预警
5. 打开分析页查看销量与库存变化趋势

1. 使用 buyer / Admin@123 登录
2. 浏览商品列表
3. 点击“立即下单”
4. 查看“我的订单”
5. 再切换管理员查看库存与图表变化

• 当前更偏课程设计/演示系统，支付、图片上传和 Excel 导出均采用轻量实现
• 自动化测试目前以无外部依赖的单元测试为主，尚未补齐数据库集成测试
• 备份恢复走业务 JSON 方案，适合演示和小规模数据恢复，不是生产级备份系统

• 增加独立支付页、退款流转和更细粒度的订单状态机
• 将图片上传切换为 multipart 文件流并增加对象存储适配
• 为商品、订单、日志补充更复杂的筛选器与统计看板
• 增加 MySQL / IoTDB 的自动化集成测试与压测脚本

• 接口说明：docs/api.md
• 初始实现方案：docs/implementation-plan.md
• 需求对照与缺口分析：docs/requirements-gap.md