Add shared engineering rule contracts

- go-logging: slog, server-side only, structured attributes
- go-database: MySQL cursor safety, soft delete, GORM tags, fail-fast, N+1 prevention
- go-background-tasks: Task Manager pattern, polling, no SSE
- go-code-style: layering, error wrapping, startup sequence, config, templating
- import-export: CSV Excel-compatible rules (BOM, semicolon, decimal comma, DD.MM.YYYY)
- table-management: filtering and pagination rules added
- CLAUDE.template.md: updated to reference all shared contracts

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-01 16:39:39 +03:00
parent 8f28cfeac2
commit 40d1c303bb
7 changed files with 451 additions and 6 deletions

View File

@@ -5,7 +5,53 @@ Read and follow the project Bible before making any changes:
**[`bible/README.md`](bible/README.md)**
The Bible is the single source of truth for architecture, data models, API contracts, and UI
pattern conventions.
pattern conventions. Every significant architectural decision must be recorded in the Bible
decision log before or alongside the code change.
Every significant architectural decision must be recorded in the appropriate Bible decision log.
---
## Shared Engineering Rules
The following rules apply to ALL changes in this project.
They are maintained centrally in `tools/ui-design-code/kit/patterns/`.
### Go Code Style
See [`tools/ui-design-code/kit/patterns/go-code-style/contract.md`](tools/ui-design-code/kit/patterns/go-code-style/contract.md)
- Handler → Service → Repository layering
- Error wrapping with `fmt.Errorf("...: %w", err)`
- Startup sequence: connect DB → migrate → start server
- Business logic and status thresholds live on the server, not in JS
### Logging
See [`tools/ui-design-code/kit/patterns/go-logging/contract.md`](tools/ui-design-code/kit/patterns/go-logging/contract.md)
- Use `slog`, log to binary stdout/stderr only
- Never use `console.log` as a substitute for server-side logging
- Always log: startup, background task start/finish/error, export row counts, ingest results
### Database
See [`tools/ui-design-code/kit/patterns/go-database/contract.md`](tools/ui-design-code/kit/patterns/go-database/contract.md)
- **CRITICAL**: never execute SQL on the same tx while iterating a cursor — two-phase only
- Soft delete via `is_active = false`, not physical deletes
- Fail-fast DB check before starting the HTTP server
- No N+1 queries: use JOINs or batch `IN` queries
### Background Tasks
See [`tools/ui-design-code/kit/patterns/go-background-tasks/contract.md`](tools/ui-design-code/kit/patterns/go-background-tasks/contract.md)
- All slow operations: POST → task_id → client polls `/api/tasks/:id`
- No SSE — polling only
- Return `202 Accepted` when task is created
### Tables, Filtering, Pagination
See [`tools/ui-design-code/kit/patterns/table-management/contract.md`](tools/ui-design-code/kit/patterns/table-management/contract.md)
- Server-side filtering and pagination only
- Filter state in URL query params; applying a filter resets to page 1
- Response must include `total_count`, `page`, `per_page`, `total_pages`
- Display format: "51100 из 342"
### CSV Export
See [`tools/ui-design-code/kit/patterns/import-export/contract.md`](tools/ui-design-code/kit/patterns/import-export/contract.md)
- UTF-8 BOM required (`\xEF\xBB\xBF`)
- Semicolon delimiter (`;`), not comma
- Decimal separator: comma (`1 234,56`), not period
- Dates as `DD.MM.YYYY`
- `csv.Writer` with `Comma = ';'`