33 lines
2.5 KiB
Markdown
33 lines
2.5 KiB
Markdown
|
# 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.
|