# 订单发货管理系统 v2.0

> 高效的订单物流全流程管理平台 —— 集中管理订单发货、物流追踪、批量导入导出，实时掌握每一笔订单状态。

---

## 设计初衷

本系统面向电商/礼品卡业务场景，解决以下核心痛点：

- **订单分散难管理**：大量订单散落在不同批次，缺乏统一的查询和筛选手段
- **物流导入效率低**：传统手工逐条录入物流信息耗时易错，需要批量导入能力
- **状态追踪不透明**：订单从"待处理"到"已发货/已导入"的状态流转缺乏可视化
- **操作无审计**：多人协作时无法追溯谁在什么时候做了什么操作
- **界面体验差**：传统后台系统界面老旧，操作效率低

基于以上需求，设计并实现了本系统，提供从订单查询、物流批量导入、状态管理到操作审计的一站式解决方案。

---

## 功能模块

### 1. 用户认证
- 多账号登录（管理员 / 普通用户）
- Token 鉴权机制
- 登录日志自动记录

### 2. 订单管理
- **统计看板**：总订单数、待处理、已导入、已取消 四大 KPI 卡片
- **多维筛选**：按订单状态、下单日期、批次号、卡号、订单号组合查询
- **数据表格**：批次号、订单号、物流公司、物流单号、订单状态等 17 个字段
- **自定义状态标签**：待处理(橙)、已完成(绿)、已取消(红)、已发货(蓝)、已导入(青)
- **Excel 导出**：按筛选条件导出订单列表，物流公司列带下拉验证
- **分页浏览**：支持 20/50/100 条每页

### 3. 物流导入
- **拖拽上传**：支持拖拽或点击选择 Excel 文件（.xlsx / .xls）
- **批量处理**：自动去重、逐条校验、事务保障
- **校验规则**：
  - 物流公司必须从下拉列表选择（中文名或代码）
  - 物流单号不能为空或占位符（`-`、`—`、`--`）
  - 订单必须存在于数据库
  - 已发货(status=3)、已完成(status=1)、已导入(status=4)的订单禁止重复导入
- **结果展示**：成功/失败/总计统计 + 失败详情列表
- **模板下载**：提供标准导入模板（含物流公司下拉验证）

### 4. 操作日志（仅管理员可见）
- 记录所有用户操作：登录、查询、导出、导入、下载模板
- 支持按用户名、操作类型、日期范围筛选
- 用户头像 + 操作类型标签 + 等宽时间/IP 显示
- 分页浏览

### 5. 主题切换
- 亮色 / 暗色主题一键切换
- 主题偏好本地持久化
- 基于 OKLCH 色彩空间的完整设计令牌系统

---

## 技术栈

| 层级 | 技术 | 版本 |
|------|------|------|
| 前端框架 | Vue 3 (Composition API) | ^3.4.0 |
| 构建工具 | Vite | ^5.0.0 |
| UI 组件库 | Element Plus | ^2.5.0 |
| 图标库 | @element-plus/icons-vue | ^2.3.2 |
| HTTP 客户端 | Axios | ^1.6.0 |
| 后端框架 | Node.js + Express | ^5.2.1 |
| 数据库驱动 | pg (PostgreSQL) | ^8.22.0 |
| Excel 处理 | ExcelJS | ^4.4.0 |
| 文件上传 | Multer | ^2.2.0 |
| 跨域处理 | CORS | ^2.8.6 |
| 进程管理 | PM2 | - |
| 反向代理 | Nginx | - |

---

## 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                      用户浏览器                           │
│                  (Vue 3 SPA 前端)                         │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTP/HTTPS
                       ▼
┌─────────────────────────────────────────────────────────┐
│                     Nginx (:80)                          │
│          静态资源缓存 + Gzip + 反向代理                    │
└──────────────────────┬──────────────────────────────────┘
                       │ proxy_pass
                       ▼
┌─────────────────────────────────────────────────────────┐
│              Node.js + Express (:3000)                   │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐ │
│  │  静态文件托管  │  │  RESTful API │  │  SPA 兜底路由  │ │
│  └──────────────┘  └──────┬───────┘  └─────────────── │
└───────────────────────────┼─────────────────────────────┘
                            │
               ┌────────────┼────────────
               ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ PostgreSQL│ │ 本地日志  │  文件上传  │
        │  数据库   │ │  文件    │  (Multer)  │
        └────────── └──────────┘ └──────────
```

### 项目结构

```
shangyan_project/
├── server/                  # 后端服务
│   ├── index.js             #   入口（API + 静态文件托管）
│   ├── db.js                #   数据库连接池（支持环境变量）
│   ├── logistics.js         #   物流公司代码↔中文名映射
│   ├── routes/
│   │   └── orders.js        #   订单相关 API 路由
│   └── logs/                #   本地日志目录（按月分文件）
── web/                     # 前端项目
│   ├── src/
│   │   ├── App.vue          #   主应用组件
│   │   ├── main.js          #   入口
│   │   ├── api/
│   │   │   └── orders.js    #   API 请求封装
│   │   ├── components/      #   通用组件
│   │   │   ├── Sidebar.vue  #     侧边栏导航
│   │   │   └── AppHeader.vue#     顶栏
│   │   ├── views/           #   页面组件
│   │   │   ├── LoginPage.vue       # 登录页
│   │   │   ├── OrderManagement.vue # 订单管理
│   │   │   ├── LogisticsImport.vue # 物流导入
│   │   │   └── OperationLogs.vue   # 操作日志
│   │   └── styles/          #   样式系统
│   │       ├── tokens.css   #     设计令牌（OKLCH色彩）
│   │       └── global.css   #     全局样式 + Element Plus 主题覆盖
│   ├── index.html
│   ├── vite.config.js
│   └── package.json
├── deploy/
│   └── nginx.conf           # Nginx 配置模板
├── ecosystem.config.js      # PM2 进程配置
├── deploy.sh                # 一键部署脚本
── package.json             # 后端依赖
└── .gitignore
```

---

## 核心页面截图

### 登录页

左右分屏设计，左侧品牌视觉区展示系统定位与实时统计数据，右侧登录表单。

![登录页](docs/images/login.png)

### 订单管理

四大 KPI 统计卡片 + 多维筛选栏 + 数据表格 + 自定义状态标签。

![订单管理](docs/images/dashboard.png)

### 物流导入

拖拽上传区域 + 导入结果统计（成功/失败/总计）+ 失败详情 + 导入说明文档。

![物流导入](docs/images/import.png)

### 操作日志

管理员专属页面，支持按用户名/操作类型/日期筛选，用户头像 + 操作标签 + 分页。

![操作日志](docs/images/logs.png)

---

## 快速开始

### 开发环境

```bash
# 1. 克隆项目
git clone https://code.mizentech.com/chenmingtao/SY_project.git
cd SY_project

# 2. 安装后端依赖
npm install

# 3. 安装前端依赖
cd web && npm install && cd ..

# 4. 启动后端（端口 3000）
cd server && node index.js

# 5. 启动前端（端口 5173，另开终端）
cd web && npm run dev
```

### 生产部署

```bash
# 首次部署：一键安装依赖 + 构建前端 + 安装 PM2
bash deploy.sh install

# 启动服务
bash deploy.sh start

# 配置 Nginx（修改 server_name 后）
sudo cp deploy/nginx.conf /etc/nginx/conf.d/order-shipping.conf
sudo nginx -t && sudo nginx -s reload
```

### 日常更新

每次代码推送到 Git 后，在服务器上执行以下任一方式更新：

```bash
# 方式一：使用部署脚本（推荐，自动拉代码 + 构建前端 + 重启）
bash deploy.sh update

# 方式二：手动执行
cd /opt/SY_project
git pull
cd web && npm run build && cd ..
pm2 restart order-shipping
```

### 数据库配置

通过环境变量或 [ecosystem.config.js](ecosystem.config.js) 配置：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `DB_HOST` | 数据库主机 | 121.37.183.152 |
| `DB_PORT` | 端口 | 5432 |
| `DB_NAME` | 数据库名 | lp-card-test |
| `DB_USER` | 用户名 | postgres |
| `DB_PASSWORD` | 密码 | 123456 |

### 默认账号

| 用户名 | 密码 | 角色 | 权限 |
|--------|------|------|------|
| admin | admin123 | 管理员 | 全部功能 + 操作日志 |
| user | user123 | 普通用户 | 订单查询/导出/导入 |

---

## 版本记录

- **v2.0** — 全新 UI 重构，组件化架构，设计令牌系统，暗色主题，统计看板，本地日志持久化，PM2 + Nginx 部署支持，部署脚本增加 update 命令
- **v1.0** — 基础版本：订单查询、Excel 导出/导入、物流公司映射、用户账号、操作日志