git:20260916.b334104 to git:20260928.32163ae

5 added, 0 removed. Audit A to A.

---

name: backend-code

description: Backend Java production code, Spring Boot controllers/services/repositories, controller return values, imports, schema ERD pointer. Use when editing backend production Java.

paths:

- "backend/src/main/**/*.java"

---

# Backend Code Rules

Migrations: `db-migration` skill.

## Commands

Run backend verification from the repo root:

```bash

CURSOR_DEV=true nix develop -c pnpm backend:verify

```

When no database migration is involved, this is faster:

```bash

CURSOR_DEV=true nix develop -c pnpm backend:test_only

```

## Relational Schema

The `docs/database-erd.md` Mermaid diagram documents tables, foreign keys, and key columns. After Flyway migrations change the schema, regenerate it with the `database-erd` skill:

```bash

CURSOR_DEV=true nix develop -c pnpm export:database-erd

```

+ ## HTTP Sessions

+ - HTTP sessions are stored in MySQL (Spring Session JDBC) and must stay serializable: they hold only the signed-in security context (and, in production, the OAuth2 authorization request). Do not add `@SessionScope` beans or session attributes; controllers are singletons, and per-request state uses `@RequestScope`.

+ - Non-prod Basic sign-in keeps its user in the session, like production's GitHub login; there is no remember-me cookie.

## Controller Return Values

- Prefer returning entities, or other types already used as API bodies, from controllers when the JSON shape fits.

- Narrow the serialized surface with `@JsonIgnore`, `@JsonView`, and similar mechanisms already used in the codebase.

- Introduce a response DTO only when necessary, such as a different wire shape, aggregating multiple sources, or decoupling from persistence without overloading the entity.

## Import Style

- Always use import statements at the top of files.

- Do not use inline fully qualified class names in code.

- Use fully qualified names only when there is a naming conflict between classes with the same simple name from different packages.

Avoid:

```java

ObjectMapper mapper = new com.odde.donut.configs.ObjectMapperConfig().objectMapper();

List<com.theokanning.openai.completion.chat.ChatMessage> messages = ...;

```

Prefer:

```java

import com.odde.donut.configs.ObjectMapperConfig;

import com.theokanning.openai.completion.chat.ChatMessage;

ObjectMapper mapper = new ObjectMapperConfig().objectMapper();

List<ChatMessage> messages = ...;

```