Mikhail ChusavitinandClaude Opus 5
59e3107197
- task-discipline: require explicit target platform/language before implementation - go-api: bounded context deadline on every outbound network/DB call - controls-selection: visible busy state for any control triggering such a call - import-export: enumerate real format variants before writing a parser - app-binary: embedded assets do not hot-reload; verify rebuild before diagnosing Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2.2 KiB
2.2 KiB
Contract: Import / Export Workflows
Version: 1.1
See README.md for the reference export handler and locale examples.
Import Rules
- Recommended flow:
Upload -> Preview / Validate -> Confirm -> Execute -> Result summary. - Validation preview must be human-readable.
- Warnings and errors should be visible per row and in aggregate.
- The confirm step must communicate scope and side effects clearly.
Parsing Real-World Formats
- Before writing a parser for a third-party text export (1C, CSV, vendor reports), enumerate the actual format variants present in a real sample file: delimiters, encodings, decimal and date formats, header repetitions, multi-line and merged records, trailing summary rows.
- Write the parser against the enumerated variant list. Do not assume a single convention and repair it reactively per bug report.
- Record the enumerated variants next to the parser (test fixtures or a short comment) so later changes know which shapes must keep working.
- Unrecognized lines must be reported as explicit per-row errors, never silently skipped.
Export Rules
- The user must explicitly choose export scope when ambiguity exists, such as
selected,filtered, orall. - Export format must be explicit.
- Download responses must set
Content-TypeandContent-Dispositioncorrectly.
CSV Rules
- For spreadsheet-facing CSV, write UTF-8 BOM as the first bytes.
- Use semicolon
;as the CSV delimiter. - Use comma as the decimal separator for user-facing numeric values.
- Use
DD.MM.YYYYfor user-facing dates. - Use
encoding/csvwithcsv.Writer.Comma = ';'so quoting and escaping stay correct.
Streaming Rules
- Large exports must stream rows directly to the response. Do not load the full dataset into memory first.
- Use the canonical flow:
Handler -> Service -> Repository callback -> csv.Writer - Repository queries should avoid N+1 by using JOINs or another batched shape.
- Always call
csv.Writer.Flush()after writing rows.
Error Handling
- Import errors must map to clear user-facing messages.
- Once streaming has started, export failures are logged server-side only. Do not try to change the HTTP status after headers/body bytes were already sent.