Project Guidelines

Scope

This repository uses a root AGENTS.md as the workspace-wide instruction file. Do not add a parallel .github/copilot-instructions.md unless this file is being intentionally replaced.
The workspace is organized around four top-level areas: frontend, backend, sql, and root-level business/design documents.
Project context and business rules are documented in 商品详情与订单页面设计文档.md, 前端页面UI方案.md, 铜壶管理系统开发任务计划书.md, and 详细实施任务拆分.md. Update those docs when core behavior changes.

frontend: Vue 3 + Vite + TypeScript + Vue Router + Pinia + Element Plus.
backend: Spring Boot 2.7 + Java 11 + Spring Security + JWT + JDBC + SQLite.
data: SQLite is the only database in this project. Product images and label templates must remain in SQLite BLOB fields in the file_asset table; do not move them to local disk paths or object storage unless requirements change.
product detail uses a dedicated route, not a modal. The left-side category tree is part of the core workflow and should remain available during detail navigation.
permissions are enforced in two places: frontend visibility and backend API authorization. Do not rely on frontend hiding alone.
order processing is a closed loop: create, edit pending orders, complete with express number, deduct stock, and download labels generated by the backend from order quantities.

Frontend install: cd frontend && npm install
Frontend dev: cd frontend && npm run dev
Frontend build: cd frontend && npm run build
Frontend local API target is configured through frontend/.env.local. Local development currently points VITE_API_BASE_URL to http://localhost:8081.
Backend test: cd backend && .\mvnw.cmd test
Backend run: cd backend && .\mvnw.cmd spring-boot:run "-Dspring-boot.run.arguments=--server.port=8081"
Run backend commands from the backend directory. Do not assume mvn is installed globally; use the Maven Wrapper in backend.
Prefer port 8081 for local backend runs because 8080 is frequently occupied in this environment.
After frontend changes, run the frontend build. After backend changes, run backend tests.

Preserve the existing split between frontend service files, Pinia stores, view components, and backend controller/service/repository packages.
Keep Vue route components lazily loaded in frontend/src/router/index.ts.
Keep Element Plus on-demand loading configured in frontend/vite.config.ts. Do not reintroduce global Element Plus registration or full library CSS import in frontend/src/main.ts.
Frontend HTTP calls should continue to go through the service layer under frontend/src/services rather than ad hoc fetch logic inside views.
Backend persistence should stay SQLite-friendly and simple; prefer focused JDBC repository methods over adding heavyweight persistence abstractions.
The project is delivered as source code, SQL scripts, and deployment notes. Do not add Git-flow-specific assumptions to docs or workflow guidance.

The system supports two user types: administrator and normal user. Normal-user permissions are assigned by an administrator.
Pending orders can be edited or deleted. Completed orders are read-only.
Label downloads are generated by the backend based on current order items and quantities.
If a category does not require a detail page, do not force it into the standard product-detail workflow.
Keep stock validation and permission checks consistent across frontend and backend when changing order or catalog behavior.