# Copilot Instructions for Jiscuss

## Build, test, and run commands

This repository is a Maven Spring Boot project (Java 17+).

- Full compile: `mvn -DskipTests compile`
- Full test suite: `mvn test`
- Run one test class: `mvn -Dtest=ClassName test`
- Run one test method: `mvn -Dtest=ClassName#methodName test`
- Run app (default H2 profile): `mvn spring-boot:run`
- Run app (MySQL profile): `mvn spring-boot:run -Dspring-boot.run.profiles=mysql`
- Run app on a non-80 port: `mvn spring-boot:run -Dspring-boot.run.arguments="--server.port=8080"`

There is currently no dedicated lint plugin configured in `pom.xml` (no Checkstyle/SpotBugs/PMD task).

## High-level architecture

Jiscuss is a Spring Boot monolith with a server-rendered web UI plus REST APIs:

- **Web MVC + templates**: `controller/` classes return FreeMarker views from `src/main/resources/templates/`, with frontend assets under `src/main/resources/static/` (Semantic UI + custom JS).
- **REST APIs**: `controller/api/` exposes JSON endpoints (`/user_api/**`, `/other_api/**`) and is documented by SpringDoc OpenAPI (`/swagger-ui.html`, `/v3/api-docs`).
- **Domain and persistence**: `entity/` models map to relational tables; `repository/` uses Spring Data JPA (plus a few native queries); `service/impl/` contains business logic and transaction boundaries.
- **Security and RBAC**: `WebSecurityConfig` wires Spring Security 6; auth uses `UserDetailServiceImpl`; path checks delegate to `RbacPermission`; roles come from `rbac_role` / `rbac_user_role` (Flyway migration `V4__rbac_admin_console.sql`).
- **Admin console and auditing**: `/admin/**` endpoints in `AdminSystemController` manage users/roles/content and write operation history via `AuditLogService`.
- **Database lifecycle**: Flyway owns schema/data evolution (`src/main/resources/db/migration/*`), with profile-specific datasource config in `application-h2.yml` and `application-mysql.yml`.

## Key repository conventions

- **Flyway is the source of truth for DDL**: keep schema changes in new migration files; do not reintroduce `schema.sql`/`data.sql` initialization paths.
- **Boot 3 / Jakarta imports only**: use `jakarta.*` APIs (not legacy `javax.*` servlet/validation/persistence types).
- **Password handling is BCrypt-only**: DB passwords are expected to be BCrypt hashes (`UserDetailServiceImpl`, migration notes in `V2__security_updates.sql`); do not add plaintext comparisons in SQL/repositories.
- **Role naming convention**: security authorities are `ROLE_*`; database role codes are plain (`ADMIN`, `USER`) and are prefixed in the auth layer.
- **Controller split matters**:
  - `controller/` for page flows and model population
  - `controller/api/` for REST endpoints
  - `AdminSystemController` for admin workflows under `/admin/**`
- **Current user lookup pattern**: controllers extending `BaseController` use `getUserInfo(HttpServletRequest)` (reads `SPRING_SECURITY_CONTEXT` from session).
- **Response wrappers are mixed**: newer global exception flow returns `ApiResponse`; legacy endpoints still return entities or `ResponseResult`. Keep changes consistent with the style already used in the touched controller package.
- **Caching is selective**: user read paths in `UsersServiceImpl` use cache names (`user`, `userList`) backed by Ehcache JCache (`ehcache3.xml`).
- **Profile behavior**:
  - default/dev flow is H2 profile
  - MySQL requires explicit profile activation and datasource credentials
  - admin-only tooling endpoints include `/admin/**`, `/actuator/**`, `/druid/**` (and H2 console when enabled)