# order

**Repository Path**: lopinx/order

## Basic Information

- **Project Name**: order
- **Description**: 电子烟订单系统
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-24
- **Last Updated**: 2025-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 订单管理系统 (MVC架构版本)

这是一个重构为MVC架构的订单管理系统，具有以下特点：

## 🏗️ 项目架构

```bash
orders/
├── app.py                 # 应用入口点（整合了订单同步功能和用户初始化功能）
├── config.py              # 配置文件
├── requirements.txt       # 依赖包列表
├── .env                   # 环境变量配置
├── README_MVC.md          # MVC架构说明文档
│
├── models/                # 数据模型层
│   ├── __init__.py
│   ├── database.py        # 数据库配置和连接
│   ├── order.py           # 订单相关数据模型
│   └── user.py            # 用户权限数据模型
│
├── controllers/           # 控制器层
│   ├── __init__.py
│   ├── auth.py            # 认证相关控制器
│   ├── user_auth.py       # 用户认证和权限控制
│   ├── order_controller.py # 订单相关控制器
│   ├── customer_controller.py # 客户相关控制器
│   └── api_controller.py  # API相关控制器
│
├── services/              # 业务逻辑层
│   ├── __init__.py
│   └── order_service.py   # 订单相关业务逻辑
│
├── utils/                 # 工具函数
│   └── __init__.py
│
└── templates/             # 视图模板
    ├── login.html         # 登录页面
    ├── orders.html        # 订单列表页面
    ├── order_detail.html  # 订单详情页面
    ├── customers.html     # 客户列表页面
    ├── customer_detail.html # 客户详情页面
    ├── users.html         # 用户管理页面
    ├── add_user.html      # 添加用户页面
    └── edit_user.html     # 编辑用户页面
```

## 📁 目录说明

### models/
存放所有的数据模型和数据库相关代码：
- `database.py`: 数据库连接和会话管理
- `order.py`: 订单、状态历史、同步日志等数据模型
- `user.py`: 用户权限数据模型

### controllers/
存放所有的控制器，处理HTTP请求和响应：
- `auth.py`: 认证相关功能（保持向后兼容）
- `user_auth.py`: 用户认证和权限控制
- `order_controller.py`: 订单相关操作
- `customer_controller.py`: 客户相关操作
- `api_controller.py`: API接口
- `user_controller.py`: 用户管理相关操作

### services/
存放业务逻辑代码：
- `order_service.py`: 订单相关的业务逻辑，如国家代码转换、手机号格式化等

### utils/
存放通用工具函数

### templates/
存放前端模板文件

## 🚀 快速开始

### 1. 安装依赖
```bash
pip install -r requirements.txt
```

### 2. 配置环境变量
复制 `.env.example` 文件为 `.env` 并根据需要修改配置：
```bash
cp .env.example .env
```

主要配置项：
- `ADMIN_USERNAME`: 管理员用户名（默认: admin）
- `ADMIN_PASSWORD`: 管理员密码（默认: admin）
- `SYNC_ON_STARTUP`: 启动时是否自动同步订单数据（默认: true）
- `SYNC_INTERVAL_HOURS`: 自动同步间隔（小时，默认: 1）
- `DINGTALK_WEBHOOK`: 钉钉机器人Webhook（可选）
- `DINGTALK_SECRET`: 钉钉机器人签名密钥（可选，用于安全验证）
- `SMTP_*`: 邮件告警配置（可选）

### 3. 配置WooCommerce站点
在 `config.py` 文件中配置需要同步的WooCommerce站点：
```python
SITES = [
    {
        "user": "站点用户名",
        "domain": "域名",
        "url": "站点URL",
        "consumer_key": "API消费者密钥",
        "consumer_secret": "API消费者密钥"
    }
]
```

### 4. 启动应用
```bash
python app.py
```

### 5. 访问应用
打开浏览器访问 `http://localhost:39500`

## 🔐 用户权限系统

系统支持三种用户角色：

### 角色权限说明

1. **root（超级管理员）**
   - 可以查看所有国家的订单和客户
   - 可以添加/编辑订单和客户
   - 可以管理用户（添加/编辑/删除）
   - 拥有所有系统权限

2. **manager（管理员）**
   - 可以查看所有国家的订单和客户
   - 可以添加/编辑订单和客户
   - 不能管理用户

3. **user（普通用户）**
   - 只能查看指定国家的订单和客户
   - 不能添加/编辑订单和客户
   - 只能访问被分配国家的数据

### 默认用户账户

系统初始化时会创建以下默认用户账户：

| 角色 | 用户名 | 密码 | 权限 |
|------|--------|------|------|
| root | admin | admin | 超级管理员 |
| manager | manager | manager123 | 管理员 |
| user | user_pl | user123 | 波兰数据访问 |
| user | user_cn | user123 | 中国数据访问 |

## 🔄 订单同步功能

### 自动同步
应用在启动时会自动同步订单数据，具有以下特性：

1. **智能同步控制**：
   - 默认情况下，应用启动时会自动同步一次订单数据
   - 通过环境变量 `SYNC_ON_STARTUP=false` 可以禁用此功能
   - 通过环境变量 `SYNC_INTERVAL_HOURS` 可以设置同步间隔（默认1小时）

2. **同步频率控制**：
   - 系统会记录上次同步时间，避免过于频繁的同步
   - 如果距离上次同步不足设定时间间隔，则跳过同步

3. **错误处理**：
   - 同步过程中出现错误不会影响应用启动
   - 详细的日志记录便于问题排查

### 手动同步
可以通过以下方式手动触发订单同步：

1. **通过Web界面**：在订单页面点击"手动同步"按钮
2. **通过API**：向 `/api/sync-orders` 发送POST请求
3. **通过命令行**：
   ```bash
   python -c "from app import sync_all; sync_all()"
   ```

## 📈 功能特性

- 多WooCommerce站点订单自动同步
- 订单状态变更自动更新
- 手动添加订单功能
- 客户信息管理
- 状态变更历史记录
- 敏感状态邮件告警
- 钉钉通知（支持签名验证）
- Web界面状态统计
- CSV导出功能
- Basic Auth安全保护
- 并发安全（文件锁）
- 网络重试和日志记录
- 使用SQLAlchemy ORM
- 客户姓名分开展示（名和姓）
- 国家代码转换为中文名称
- 完整客户联系信息和地址
- 商品详情展示
- 全球249个国家和地区支持
- 订单详情页面
- 实时搜索和筛选
- 用户权限控制系统
- 响应式Web界面
- 多语言支持（中文）

## 🌐 Web界面功能

### 认证和会话管理
- **登录**: 通过 [/login](file://e:\wwwroot\Orders\app.py#L458-L500) 页面进行用户认证
- **退出登录**: 通过 [/logout](file://e:\wwwroot\Orders\app.py#L502-L505) 路由退出当前会话
- **会话管理**: 支持会话超时和并发安全

### 订单管理
- 订单列表展示
- 订单详情查看
- 手动添加订单（仅manager和root用户）
- 多维度筛选（订单ID、国家、来源站点、状态）
- 实时搜索
- 分页加载
- 订单状态统计
- CSV导出

### 客户管理
- 客户列表展示
- 客户详情查看
- 客户订单历史
- 客户信息编辑
- 多维度筛选（客户姓名/邮箱、国家、城市、电话）
- CSV导出

### 用户管理（仅root用户）
- 用户列表管理
- 添加/编辑用户
- 用户权限分配
- 用户状态管理

## 🛠️ API接口

### 认证
所有API接口都需要认证，支持以下方式：
1. Session认证（登录后）
2. Basic Auth（用户名/密码）

### 主要API端点

| 端点 | 方法 | 描述 |
|------|------|------|
| `/api/orders` | GET | 获取订单列表 |
| `/api/customers` | GET | 获取客户列表 |
| `/api/customer-orders/<customer_id>` | GET | 获取客户订单 |
| `/api/format-phone` | POST | 格式化手机号 |
| `/api/format-phone-no-prefix` | POST | 格式化手机号（无前缀） |
| `/api/sync-orders` | POST | 手动同步订单 |

## 📊 技术栈

- **后端**: Python 3.12+, Flask 3.0
- **数据库**: SQLite (默认) / 支持其他SQL数据库
- **ORM**: SQLAlchemy 2.0
- **前端**: Bootstrap 5, HTML5, CSS3, JavaScript
- **HTTP客户端**: httpx
- **任务调度**: schedule
- **配置管理**: python-dotenv
- **错误重试**: tenacity
- **并发控制**: filelock

## 📦 依赖说明

查看 `requirements.txt` 文件了解详细依赖：

```
Flask==3.0.3
httpx[http2]==0.27.0
tenacity==8.2.3
filelock==3.16.1
python-dotenv==1.0.1
SQLAlchemy==2.0.34
schedule==1.2.2
psutil==7.1.1
Werkzeug==3.0.3
```

## 🐛 常见问题

### 1. 同步失败
- 检查WooCommerce API密钥是否正确
- 检查网络连接是否正常
- 查看日志文件 `sync.log` 获取详细错误信息

### 2. 登录失败
- 确认用户名和密码正确
- 检查 `.env` 文件中的认证配置

### 3. 数据库问题
- 确保有写入权限
- 检查磁盘空间是否充足

## 📝 开发指南

### 代码结构
遵循MVC架构模式：
- **Model**: 数据模型和数据库操作
- **View**: 前端模板和用户界面
- **Controller**: 业务逻辑和请求处理

### 扩展开发
1. 添加新功能时遵循现有代码结构
2. 新增API端点在 `api_controller.py` 中注册
3. 新增页面模板放在 `templates/` 目录下
4. 新增业务逻辑放在 `services/` 目录下

## 📄 许可证

本项目仅供学习和参考使用。