fuquanapi/README.md

# 福泉WebAPI - 智能物流管理系统

## 📋 项目简介

基于SpringBoot的智能物流管理系统后端API，提供车辆管理、称重记录、供应商管理等核心功能，支持AK/SK签名认证。

## ✨ 核心功能

- 🚛 **物流管理**: 车辆信息、转运记录、称重记录
- 👥 **用户管理**: 供应商、运输公司管理
- 📊 **数据管理**: 品种信息、供应关系、图片管理
- 🔐 **安全认证**: AK/SK签名验证、时间戳防重放

## 🛠 技术栈

- **Spring Boot** 2.7.18
- **Spring Data JPA**
- **SQL Server**
- **Maven**
- **Java 8+**

## 🚀 快速开始

### 1. 环境要求
- JDK 1.8+
- Maven 3.6+
- SQL Server 2012+

### 2. 配置数据库
```yaml
spring:
  datasource:
    url: jdbc:sqlserver://localhost:1433;databaseName=fuquan_db;encrypt=false;trustServerCertificate=true
    username: your_username
    password: your_password
```

### 3. 配置API密钥
```yaml
api:
  client:
    ak: your_access_key_here
    sk: your_secret_key_here
```

### 4. 启动应用

#### 方式一：Maven启动（开发环境）
```bash
mvn spring-boot:run
```

#### 方式二：JAR包启动（生产环境）
```bash
# 编译打包
mvn clean package

# 快速启动
chmod +x run.sh
./run.sh

# 或直接运行JAR
java -jar target/webapi-0.0.1-SNAPSHOT.jar
```

#### 方式三：Linux服务部署
```bash
# 安装脚本
chmod +x install.sh
./install.sh

# 启动服务
sudo systemctl start fuquan-webapi
sudo systemctl enable fuquan-webapi

# 查看状态
sudo systemctl status fuquan-webapi
```

访问地址: `http://localhost:8806/fuquanapi`
API文档: `http://localhost:8806/fuquanapi/swagger-ui.html`

## 🔐 安全认证

### 请求头要求
```http
ak: your_access_key
timestamp: 1640995200000
signature: calculated_signature
```

### 签名计算
```java
// 签名 = MD5(ak + sk + timestamp)
String signature = MD5(accessKey + secretKey + timestamp);
```

**注意**: 时间戳与服务器时间差不能超过10分钟

## 📚 主要API

### 数据同步API

#### 基础同步接口
- `POST /api/sync/single` - 同步单条数据
- `POST /api/sync/batch` - 批量同步指定ID的数据
- `POST /api/sync/unuploaded` - 同步所有未上传的数据
- `POST /api/sync/incremental` - 增量同步数据（基于皮重时间）
- `POST /api/sync/all` - 全量同步所有数据

#### 分批处理接口（推荐用于大数据量）
- `POST /api/sync/unuploaded/batch?batchSize=500` - 分批同步未上传数据
- `POST /api/sync/incremental/batch?batchSize=500` - 分批增量同步
- `POST /api/sync/all/batch?batchSize=500` - 分批全量同步

**分批处理优势**：
- 🚀 **性能优化**: 避免一次性加载大量数据到内存
- 💾 **内存友好**: 每批处理500条记录，减少内存占用
- 🔄 **错误恢复**: 单批失败不影响其他批次
- 📊 **进度监控**: 实时显示每批处理进度
- ⚡ **仅插入模式**: 不进行更新检查，直接插入新记录，提高性能

### 供应商管理
```http
POST /api/supplier/page/conditions
```

### 运输公司管理
```http
POST /api/transport-company/page/conditions
```

### 转运记录管理
```http
POST /api/transfer-record/page/conditions
```

### 称重记录管理
```http
POST /api/weighing-record/page/conditions
```

## 📁 项目结构

```
src/main/java/com/example/webapi/
├── controller/          # 控制器层
├── service/            # 服务层
├── repository/         # 数据访问层
├── entity/            # 实体类
├── dto/               # 数据传输对象
├── interceptor/       # 拦截器
└── util/              # 工具类
```

## 🐧 Linux部署脚本

### 脚本说明

| 脚本 | 用途 | 适用场景 |
|------|------|----------|
| `run.sh` | 快速启动 | 开发测试 |
| `start.sh` | 完整管理 | 生产环境 |
| `install.sh` | 自动安装 | 首次部署 |

### 使用示例

```bash
# 快速启动（开发环境）
./run.sh

# 生产环境管理
./start.sh start      # 启动应用
./start.sh stop       # 停止应用
./start.sh restart    # 重启应用
./start.sh status     # 查看状态
./start.sh logs       # 查看日志

# 自动安装部署
./install.sh
```

### 系统服务管理

```bash
# 启动服务
sudo systemctl start fuquan-webapi

# 停止服务
sudo systemctl stop fuquan-webapi

# 重启服务
sudo systemctl restart fuquan-webapi

# 查看状态
sudo systemctl status fuquan-webapi

# 开机自启
sudo systemctl enable fuquan-webapi

# 查看日志
sudo journalctl -u fuquan-webapi -f
```

## 🐛 常见问题

1. **数据库连接失败**: 检查数据库服务和连接配置
2. **签名验证失败**: 确认AK/SK配置和时间戳格式
3. **分页查询异常**: 验证分页参数和查询条件
4. **端口被占用**: 修改配置文件中的端口号
5. **权限不足**: 确保脚本有执行权限 `chmod +x *.sh`

## 📞 联系方式

- **项目地址**: [GitHub Repository]
- **邮箱**: [your.email@example.com]

---

**福泉WebAPI** - 让物流管理更智能！ 🚀