docs initial

.claude/rules/coding-style.md

@@ -0,0 +1,78 @@
+# Coding Style (Extended)
+
+Extends the style guidelines in CLAUDE.md with patterns from ECC.
+
+## Immutability
+
+Create new objects — never mutate existing ones:
+
+```typescript
+// WRONG: mutation
+user.name = newName;
+items.push(newItem);
+
+// RIGHT: immutable update
+const updated = { ...user, name: newName };
+const updatedItems = [...items, newItem];
+```
+
+```python
+# WRONG: mutation
+user["name"] = new_name
+items.append(new_item)
+
+# RIGHT: immutable (when it matters)
+updated = {**user, "name": new_name}
+updated_items = [*items, new_item]
+```
+
+Exception: Pydantic models and SQLAlchemy ORM objects are designed for mutation — use them as intended.
+
+## File Organization
+
+- 200-400 lines typical, 800 max per file
+- High cohesion, low coupling — one concept per file
+- Backend: module structure is fixed (models, schemas, repository, service, router) — don't add extra files
+- Frontend: FSD layers are fixed — don't add files outside the layer structure
+
+## Error Handling
+
+### Frontend
+- API errors: handle in TanStack Query `onError` callbacks or error boundaries
+- Form validation: `react-hook-form` with inline `register()` validation rules and `Controller` for controlled components. Error messages in Russian.
+- Never show raw error strings to users — map to user-friendly Russian messages
+
+### Backend
+- Raise `HTTPException` with appropriate status codes in routers
+- Service layer returns data or raises domain exceptions
+- Repository layer lets SQLAlchemy exceptions propagate (service handles them)
+- Store error messages as named constants with `ERROR_` prefix
+
+## Input Validation
+
+- Frontend: TypeScript interfaces + `react-hook-form` inline rules for form data, OpenAPI-generated types for API responses
+- Backend: Pydantic schemas validate all request bodies — never trust raw input
+- File uploads: validate extension + MIME type in files module
+- Never construct SQL from user input — SQLAlchemy handles parameterization
+
+## Named Constants
+
+```python
+# WRONG
+if status == "completed":
+    ...
+
+# RIGHT
+JOB_STATUS_COMPLETED = "completed"
+if status == JOB_STATUS_COMPLETED:
+    ...
+```
+
+```typescript
+// WRONG
+if (job.status === "completed") { ... }
+
+// RIGHT
+const JOB_STATUS_COMPLETED = "completed" as const;
+if (job.status === JOB_STATUS_COMPLETED) { ... }
+```