# Backend Guidelines

## Scope
- Applies to files under backend/.
- Inherit the root [AGENTS.md](../AGENTS.md) and only override backend-specific expectations here.

## Stack
- Spring Boot 2.7 + Java 11 + Spring Security + JWT + JDBC + SQLite.
- Runtime configuration lives in [backend/src/main/resources/application.properties](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.

## Build And Test
- 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/.

## Conventions
- Preserve the current package split under [backend/src/main/java/com/teapot/system](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.

## Backend Business Rules
- 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.