Backend Guidelines

Scope

Applies to files under backend/.
Inherit the root AGENTS.md and only override backend-specific expectations here.

Spring Boot 2.7 + Java 11 + Spring Security + JWT + JDBC + SQLite.
Runtime configuration lives in backend/src/main/resources/application.properties.
The primary business database is the SQLite file referenced by application.properties. Keep product images and label templates in file_asset BLOB fields.

Run commands from backend/ and use the Maven Wrapper instead of a global Maven install.
Run tests from backend/: .\mvnw.cmd test
Start the backend locally from backend/: .\mvnw.cmd spring-boot:run "-Dspring-boot.run.arguments=--server.port=8081"
Prefer port 8081 for local runs because 8080 is commonly occupied in this environment.
Run backend tests after any change under backend/.

Preserve the current package split under backend/src/main/java/com/teapot/system: auth, catalog, order, statistics, user, config, and common.
Keep the controller/service/repository layering intact. New persistence logic should generally live in focused JDBC repositories, not in controllers or ad hoc utility classes.
Keep JSON APIs wrapped in the common response model, while file downloads may continue using ResponseEntity<byte[]> where appropriate.
Keep security enforced through Spring Security and method-level authorization. Do not weaken backend permission checks because the frontend already hides an action.
Keep persistence SQLite-friendly: avoid introducing heavyweight ORM abstractions or storage patterns that assume another database engine.
Asset list endpoints should return metadata only; binary file retrieval remains a dedicated download path.
Tests must stay isolated from the real business database and should continue using target/ or other temporary SQLite files.

Pending orders can be edited or deleted; completed orders are read-only.
Completing an order requires express number handling and must keep stock deduction consistent with order item quantities.
Label downloads are generated by the backend from current order items and quantities, using the latest label template data stored in SQLite.
Product image primary/cover behavior, stock validation, and permission checks must stay consistent with frontend expectations.
Categories that do not require a detail page should not be forced into standard product-detail business logic.