docs: update README with API overview

README.md

@@ -1,2 +1,120 @@
-# auv-locker-sdk
+# 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 |