# Copilot Instructions

## Build, test, and lint commands

### Backend (`backend`)
- Install/build: `mvn clean package`
- Run tests: `mvn test`
- Run one test class: `mvn -Dtest=ApprovalApplicationServiceTest test`
- Run one test method: `mvn -Dtest=ApprovalApplicationServiceTest#handleActionApprovePublishesApprovedEventWhenFlowCompletes test`
- Run locally: `mvn spring-boot:run`
- Run with local profile: `mvn spring-boot:run -Dspring-boot.run.profiles=local`

### Admin frontend (`frontend-admin`)
- Install: `npm install`
- Dev server: `npm run dev`
- Production build: `npm run build`
- Preview build: `npm run preview`

### H5 frontend (`frontend-h5`)
- Install: `npm install`
- Dev server: `npm run dev`
- Production build: `npm run build`
- Preview build: `npm run preview`

### Uni-app mini program (`yuyueMiniProgram`)
- Install: `pnpm install`
- WeChat mini-program dev: `pnpm dev:mp-weixin`
- H5 dev: `pnpm dev:h5`
- WeChat mini-program build: `pnpm build:mp-weixin`
- H5 build: `pnpm build:h5`
- Type-check: `pnpm type-check`
- Lint: `pnpm lint`
- Auto-fix lint: `pnpm lint:fix`
- Regenerate Alova API definitions: `pnpm alova-gen`

## High-level architecture

- This repository is a multi-app workspace:
  - `backend`: Spring Boot 3 modular monolith for admin APIs and mini-program APIs
  - `frontend-admin`: Vue 3 + Vite admin console
  - `frontend-h5`: separate Vite/Vue H5 client
  - `yuyueMiniProgram`: separate uni-app/Wot UI client with its own toolchain and conventions

- The backend is organized around **Controller -> ApplicationService -> Mapper/Mapper XML**:
  - controllers are thin request/response adapters
  - business orchestration lives in `*ApplicationService`
  - complex list/query SQL lives in `src/main/resources/mapper/*.xml`
  - MyBatis-Plus is used for CRUD plus pagination/optimistic locking

- The core backend business flow is reservation and approval orchestration:
  - `MiniAppointmentApplicationService` creates reservations
  - `ApprovalEngineService` resolves approval node chains, assignees, and task transitions
  - `ApprovalApplicationService` and `MiniHandlerApprovalApplicationService` process approvals
  - approval completion publishes events consumed by `AppointmentLifecycleEventListener`
  - `PostApprovalOrchestrationService` performs post-approval work such as QR-code generation and notifications

- There are **two auth systems** sharing the `Authorization` header but not the same login/session logic:
  - admin APIs use `StpUtil` with `/api/auth/**`
  - mini-program APIs use `StpLogic("mini")` via `/api/mini/**`
  - employee/visitor mini-program identity is stored in `mp_user`, not `sys_user`

- Backend responses use a uniform `Result` envelope. Admin and mini-program clients both expect that wrapper rather than raw DTOs.

- Backend persistence has a few important cross-cutting behaviors:
  - all entities inherit `BaseEntity` with `id`, `uuid`, `version`, audit fields, and `delFlag`
  - `MybatisPlusConfig` auto-fills `uuid`, timestamps, default `version`, and default `delFlag`
  - list-heavy screens rely on hand-written XML SQL (`AppointmentOrderMapper.xml`, `ApprovalTaskMapper.xml`) instead of only wrapper queries
  - SQL migrations in `backend/src/main/resources/db/migration/` are applied manually in version order; the app is not set up to auto-run them

- The admin frontend is permission-driven:
  - `src/router/index.ts` uses route `meta.permission`
  - `src/stores/auth.ts` persists token/display info/permissions in `localStorage`
  - navigation falls back to the first allowed route from `pagePermissionOrder`
  - `src/api/http.ts` injects the token and expects backend `Result` semantics for auth/error handling

- The admin login flow is coupled across frontend and backend:
  - `frontend-admin/src/utils/loginCrypto.ts` AES-encrypts username/password with a timestamp
  - `backend/.../AdminLoginCryptoService.java` decrypts and validates the same payload
  - keep frontend `VITE_ADMIN_LOGIN_AES_*` and backend `security.admin-login-crypto.*` aligned

- The uni-app client is a separate application, not just a skin on the admin frontend:
  - file-based pages/layouts under `src/pages` and `src/layouts`
  - Pinia stores in `src/store`
  - Alova API layer in `src/api`
  - Wot Design Uni components and UnoCSS are the default UI stack

## Key conventions

- **Do not inject Mapper directly into controllers.** This repository expects business logic in `*ApplicationService`.

- **Preserve the dual-auth split.** Admin and mini-program endpoints may both read `Authorization`, but they are validated by different Sa-Token logics and should not be merged casually.

- **When updating existing backend entities, keep `uuid` and `version` in mind.** `BaseEntity` validation groups and optimistic locking assume updates carry the current record identity/version.

- **Use the existing async executors for new async work.** The backend now has named thread pools in `AsyncConfig`:
  - `applicationTaskExecutor` for general async/event/logging work
  - `exportTaskExecutor` for export jobs

- **For admin list pages, check mapper XML before rewriting queries in Java.** Pagination, approval-status filtering, and visitor keyword filtering are already encoded in XML mappers.

- **If you add or rename admin pages, update both routing and permission fallbacks.** `pagePermissionOrder` and each route's `meta.permission` must stay aligned with backend permission codes.

- **Keep admin HTTP calls compatible with the `Result` wrapper.** The axios layer treats `code === 401` and `success === false` specially.

- **Do not bypass admin login encryption.** Changes to login requests usually require coordinated edits in both `loginCrypto.ts` and `AdminLoginCryptoService`.

- **For the uni-app app, follow the local project rules rather than the admin frontend style.**
  - use `pnpm`, not npm
  - prefer Pinia + Alova patterns already used under `src/store` and `src/api`
  - prefer Wot Design Uni / UnoCSS
  - use the existing global feedback components instead of direct `uni.showToast`

- **Current local ports are code-driven, not README-driven.**
  - backend currently listens on `8880` (`application.yml`)
  - `frontend-admin` proxies `/api` and `/uploads` to `http://localhost:8880`