# DELIVERY PLATFORM API

**Part of:** craftlabs-authorization-sdk (暂合工作区)
**Stack:** Spring Boot 3.x + MyBatis-Plus + Flyway + MySQL
**Build:** Maven (JDK 17+), 153 Java 文件

## STRUCTURE

```
delivery-platform-api/
├── src/main/java/cn/craftlabs/platform/api/
│   ├── PlatformApplication.java     # Bootstrap entry
│   ├── config/                      # OpenApiConfig, SecurityConfig, MybatisPlusConfig, ApiExceptionHandler
│   ├── security/                    # JwtAuthenticationFilter, JwtService, InternalTokenAuth
│   ├── domain/                      # Status enums (Contract, Customer, Device, LicenseSn, etc.)
│   ├── persistence/{entity}/       # Entity + Mapper pairs (每领域一对)
│   ├── service/                     # Business logic (ContractService, LicenseSnService, etc.)
│   ├── {domain}/                    # Controllers (contract, license, device, audit, todo, etc.)
│   └── web/dto/                     # 47 Request/Response DTOs
├── src/main/resources/db/migration/ # Flyway SQL migrations
└── pom.xml
```

## DOMAINS

| Domain | Controller | Service | Entities |
|--------|-----------|---------|----------|
| Contract | `ContractController` | `ContractService` | Contract, ContractLine, ContractChange |
| License SN | `LicenseSnController` | `LicenseSnService` | LicenseSn, License, LicenseKey, Activation |
| Delivery | `DeliveryBatchController` | `DeliveryBatchService` | DeliveryBatch, DeliveryLine |
| Device | `DeviceController` | `DeviceService` | Device, DeviceSnBinding, DeviceSwapRequest |
| Customer | `CustomerController` | `CustomerService` | Customer |
| Audit | `AuditController` | `AuditService` | AuditEvent |
| Todo | `TodoController` | `TodoService` | TodoItem, NotificationConfig |
| Project | `ProjectController` | `ProjectService` | Project, ProjectStakeholder |
| Integration | `IntegrationCatalogController` | `IntegrationCatalogService` | SkuMapping, ProductLine, Env, BitanswerId, JsonTemplate |
| Callback | `CallbackInboxController` | `CallbackInboxService` | CallbackInbox |
| Report | `ReportController` | `ReportService` | — |
| Dictionary | `DictionaryController` | `DictionaryService` | Dictionary |

## WHERE TO LOOK

| Task | Location |
|------|----------|
| REST endpoints | `*/.../api/{domain}/*Controller.java` |
| Business logic | `*/.../api/service/*Service.java` |
| Data access | `*/.../api/persistence/{domain}/` |
| Request/response DTOs | `*/.../api/web/dto/` |
| DB migrations | `src/main/resources/db/migration/` |
| Security filters | `*/.../api/security/` |
| Global error handling | `*/.../api/config/ApiExceptionHandler.java` |

## CONVENTIONS

- **Controller**: `@RestController` + `@RequestMapping("/api/v1/...")` per domain
- **Persistence**: 实体 `Platform{Entity}` + `Platform{Entity}Mapper` (MyBatis-Plus), 一对一下同包
- **Service**: 每个 domain 一个 Service 接口+实现, 调用 Mapper + 跨域调其它 Service
- **DTO**: 每个 domain 一对 Request/Response 类, 47 个 DTO 集中 `web/dto/`
- **Error**: 统一 `ApiExceptionHandler` + 自定义业务异常
- **Security**: JWT filter + internal token filter

## ANTI-PATTERNS

- **Do not** import/copy SDK classes (`cn.craftlabs.auth.*`) into the platform — use published artifacts
- **Do not** repackage platform as boot JAR outside `bootstrap` module