games_app/.cursor/rules/backend-documentation.mdc
2026-06-29 15:01:23 +02:00

55 lines
2.2 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
description: Documentation standards for backend TypeScript code (JSDoc comments)
globs: backend/src/**/*.ts
alwaysApply: false
---
# Backend documentation conventions
Every new or modified backend file must include clear JSDoc comments so maintenance stays easy (Spring Boot–style readability).
## Required comments
1. **File / module** — One block at the top describing the layer and responsibility:
- `models/` → entity mapped to a DB table
- `dto/` → API/query projection (not a full entity)
- `repositories/` → data access (SQL)
- `services/` → business logic
- `controllers/` → HTTP handlers (thin; delegate to services)
- `middleware/` → Express pipeline hooks
## Layer dependencies (Spring Boot style)
- **Controller → Service only** — never import repositories or run SQL in controllers.
- **Service → Repository (+ other services when needed)** — business logic, decryption, orchestration.
- **Repository → Models / DTO row types** — SQL and data mapping only; no HTTP concerns.
- **Exceptions kept as-is** when justified: background jobs (`depositMonitorService`), `authService` reading `settingsRepository` directly for token policy, `middleware` calling `authService.verifyToken`.
2. **Every exported function** — JSDoc with:
- What it does (one sentence)
- `@param` for non-obvious parameters
- `@returns` when the return value is not obvious
- `@throws` when the function throws domain errors
3. **Non-exported helpers** — Comment when logic is non-obvious (crypto, blockchain, ledger locking, etc.).
4. **Interfaces / types in models & dto** — Brief description of what they represent and which table/view they map to.
## Style
- Write comments in **English** (matches existing codebase).
- Prefer **why** over **what** when the code is self-explanatory.
- Do not restate obvious one-liners (`return rows[0] || null` needs no comment).
- Keep comments up to date when changing behavior.
## Example
```typescript
/**
* Finds a user by email hash (used for login and uniqueness checks).
* @param emailHash SHA-256 hash of normalized email
* @returns User row or null if not found
*/
export async function findByEmailHash(emailHash: string): Promise<User | null> {
```