craftlabs-authorization-sdk/services/delivery-platform-api/AGENTS.md

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