Jiscuss/.github/copilot-instructions.md

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)