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:
@@ -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: "51–100 из 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 = ';'`
|
||||
|
||||
Reference in New Issue
Block a user