# AUV 智能取餐柜 Java SDK

Java SDK for AUV Smart Locker API. Maven + JDK 8 + Apache HttpClient 4.5 + Jackson.

## Quick Start

```java
AuvClient client = AuvClient.builder()
    .appId("66666")
    .secretKey("mySecret")
    .build();

// 存取业务 API
CreateOrderResponse resp = client.storage().createOrder(request);

// 辅助功能 API
DeviceStatusResponse status = client.aux().queryDeviceStatus(request);

client.close();
```

## Project Structure

```
auv-locker-sdk/
├── src/main/java/com/auv/locker/
│   ├── AuvClient.java              # Unified entry point
│   ├── config/
│   │   ├── AuvConfig.java          # Configuration (appId, secretKey, timeouts)
│   │   └── GatewayType.java        # Gateway enum (STORAGE / AUX)
│   ├── http/
│   │   ├── AuvHttpClient.java      # Apache HttpClient wrapper
│   │   └── HmacMD5Util.java        # HmacMD5 signature utility
│   ├── model/
│   │   ├── common/                 # AuvRequest, AuvResponse
│   │   ├── storage/                # Storage API request/response models (11 pairs)
│   │   └── aux/                    # Aux API request/response models
│   └── service/
│       ├── StorageApiService.java  # Storage API interface (11 endpoints)
│       ├── StorageApiServiceImpl.java
│       ├── AuxApiService.java      # Aux API interface (4 endpoints)
│       └── AuxApiServiceImpl.java
└── src/test/java/com/auv/locker/
    ├── HmacMD5UtilTest.java        # Signature tests
    └── AuvClientTest.java          # Builder & config tests
```

## API Overview

### Storage API (11 endpoints)

| method | Description |
|--------|-------------|
| `createOrder` | Create storage order |
| `addCell` | Add cell to existing order |
| `cancelOrder` | Cancel storage order |
| `createPreOrder` | Create pre-order |
| `changePreorderToFormal` | Convert pre-order to formal |
| `takeByOrder` | Take by order ID |
| `takeByCode` | Take by pickup code |
| `reOpenDoor` | Re-open door (within 60s of order) |
| `getDeviceInfo` | Get device info |
| `getCellList` | Get cell list |
| `getOrderList` | Query orders (paginated) |

### Aux API (4 endpoints)

| method | Description |
|--------|-------------|
| `device.cell.op` | Single cell operation |
| `device.cells.ops` | Batch cell operations (Android only) |
| `device.status.query` | Query device status & cell details |
| `device.list.query` | Paginated device list |

### Gateway URLs

| API | HTTP | HTTPS |
|-----|------|-------|
| Storage | `http://plat.58auv.com/OpenApi` | `https://plat.58auv.com/OpenApi` |
| Aux | `http://openapi.58auv.com/gateway.do` | `https://openapi.58auv.com/gateway.do` |

### Success Codes

- **Storage API**: `code == 10000`
- **Aux API**: `code == 1 && success == true`

### Error Codes

| Code | Description |
|------|-------------|
| 10000 / 1 | Success |
| 10010 | Missing parameters |
| 10011 | bizData parameter error |
| 10012 | Device not exists / offline |
| 10013 | Order already exists |
| 10014 | No available cell |
| 10015 | Invalid order |
| 10016 | Unsupported operation |
| 10020 | Signature error |
| 10021 | Duplicate pickup code, use takeByOrder |
| 10027 | Please complete previous order first |
| 10029 | Non-existent cell |
| 10030 | Same request in progress |
| 30002 | Cell allocation failed |

### Signature Algorithm (HmacMD5)

1. Collect all request parameters (except `digest`)
2. Sort keys by ASCII order, join with `&` as `key=value` pairs
3. Compute HmacMD5 with `secretKey`
4. URL-encode `bizData` before sending

## Notifications (Callbacks)

| notifyType | Source | Description |
|------------|--------|-------------|
| `orderCompleted` | Storage API | Order completed |
| `orderCancel` | Storage API | Order cancelled |
| `cell_status_sync` | Aux API | Cell status change |
| `device_status_sync` | Aux API | Device online/offline |