Formate de import și export

Fișierul e contractul. Exportul scoate fișiere CSV cu coloane fixe, documentate mai jos coloană cu coloană, care se deschid în orice program de calcul tabelar — nu doar în al nostru. Importul citește fișierele pe care le produc deja alte aplicații și aparatele de cronometrare. Dacă formatul tău nu e încă în listă, trimite-ne un fișier: ultima secțiune spune exact ce să trimiți și ce facem cu el.

Toate fișierele încep cu marcajul care spune programelor de calcul tabelar că textul e UTF-8, ca diacriticele să apară corect fără să configurezi nimic. Datele sunt AAAA-LL-ZZ, orele HH:MM:SS cu milisecunde opționale, iar numerele zecimale folosesc punctul.

Punctul nu e o preferință. Fișierul e separat prin virgulă, așa că o virgulă zecimală ar rupe un număr în două coloane. packages/core/src/csv.ts scrie fiecare zecimală cu toFixed(3), care dă punct în orice limbă ai citi — același fișier, octet cu octet, pentru un crescător român și pentru unul englez:

Race Name,Release Date,Distance (km),Bird Ring,Bird Name,Position,Field Size,Velocity (m/min),Ace Points,Clock Time,Designated
Oradea,2099-05-18,342.000,RO 2099 900021,,37,397,1030.120,93.199,11:47:00,

Ce exportăm

Din Setări, un buton pentru fiecare fișier. Gratuit, cu abonament sau fără. Poți verifica asta singur — pașii 5 și 6 din Datele tale.

Fotografiile nu sunt incluse în export. Un CSV conține înregistrări, iar o fotografie nu e o înregistrare — ar transforma fișierul în ceva ce nu se mai deschide într-un program de calcul tabelar.

thatpigeon-birds.csv — porumbeii

Constanta din cod e BIRD_HEADERS, în packages/core/src/csv.ts.

Părinții se exportă ca inele, nu ca identificatori interni. De asta fișierul se poate reimporta în orice crescătorie, la noi sau altundeva: un inel înseamnă ceva pentru oricine, un identificator intern nu înseamnă nimic pentru nimeni. Un părinte care nu e în listă se exportă ca celulă goală, niciodată ca un cod pe care nu ai ce să-l faci.

thatpigeon-results.csv — rezultatele de cursă

Coloana Designated e goală, nu no, când porumbelul n-a fost nominalizat — pentru că no arată ca un steag într-un program de calcul tabelar, iar o celulă goală înseamnă în tot fișierul ce înseamnă peste tot: „nu”.

Cum se calculează viteza și coeficientul, și de ce uneori numărul e al federației și nu al nostru: Cum calculăm.

thatpigeon-journal.csv — jurnalul de crescătorie

Constanta e JOURNAL_HEADERS. Patru coloane de identificare — Loft, Date, Slot (morning sau evening), Compartment — apoi cele unsprezece câmpuri ale jurnalului (Feed, Feed Supplements, Water Supplements, Grit, Minerals, Flight, Nostrils, Plumage, Droppings, Loft Conditions, Weather) și Notes.

Compartment gol înseamnă toată crescătoria, nu „lipsă”. Cele unsprezece câmpuri sunt cuvintele tale, nu ale noastre: nu există o listă din care trebuie să alegi, iar fișierul le scoate exact cum le-ai scris.

Antetul pe care îl scrie exportul e antetul pe care îl citește importul, prin construcție: aceeași hartă din cod produce ambele direcții, deci nu pot ajunge să difere pentru că cineva a editat un fișier și a uitat celălalt.

thatpigeon-health.csv — evenimente de sănătate

Bird Ring, Loft, Type (vaccination, medication, treatment sau note), Product, Batch No, Occurred On, Next Due, Notes.

Bird Ring și Loft pot fi ambele goale pe același rând: un tratament poate fi al unui porumbel, al unei crescătorii întregi, sau al niciunuia dacă l-ai notat fără să precizezi. Sunt trei stări reale, iar fișierul le păstrează pe toate trei.

thatpigeon-breeding.csv — perechi și pui

Season, Cock Ring, Hen Ring, Nest Box, Paired On, Ended On, Clutch Laid, Eggs, Hatched, Clutch Notes.

Un rând pe fiecare pontă, cu datele perechii repetate — forma pe care un program de calcul tabelar o poate grupa. Două lucruri pe care le-am ales explicit:

• O pereche fără nicio pontă apare oricum, cu coloanele pontei goale. O pereche formată care n-a scos nimic e un fapt despre sezon; un fișier care ar sări peste ea ar fi o listă de reușite, nu o evidență.
• Zero ouă nu e același lucru cu nicio pontă. O pontă de zero se scrie 0; lipsa unei ponte se scrie gol. Altfel n-ai putea deosebi o rundă ratată de una neînregistrată.

thatpigeon-listings.csv — anunțuri de vânzare

Ring Number, Price, Currency, Note, Opened, Closed, Reason.

Toate anunțurile pe care le-ai pus, deschise și închise. Un anunț închis nu se vede nicăieri în aplicație, așa că fișierul acesta e locul unde îi găsești prețul și nota.

• Contactul nu e o coloană. Când un anunț se închide, contactul se șterge; un fișier care l-ar păstra ar ține, într-un telefon și într-un mesaj, exact ce am încetat noi să ținem.

Ce importăm

Fiecare importator e testat pe un fișier real, nu pe unul inventat de noi. Un importator fără fișier de probă nu se publică, pentru că un importator care n-a văzut niciodată un fișier adevărat e o presupunere.

Importatoarele sunt module separate, înregistrate într-un singur loc (packages/core/src/importers/registry.ts), iar aplicația recunoaște singură ce fișier i-ai dat. Un format nou se adaugă fără să se atingă nimic din restul.

Pentru sănătate și pentru perechi există deocamdată doar export, nu și import. Se va adăuga; până atunci pagina asta n-o să pretindă altceva.

Ce face importul din Columba

Rezultatele din clasamentele federației sunt publice și sunt ale tale. Felul în care le luăm e limitat de reguli pe care ni le-am impus înainte să scriem prima linie de cod, și pe care le poți verifica după comportamentul aplicației:

• Se cere doar când apeși tu. Nu există sarcini programate, nu se face nimic în fundal, nu se citește nimic „în avans”. O cerere către site-ul federației e întotdeauna rezultatul direct al unei apăsări.
• Ne prezentăm cinstit. Fiecare cerere spune cine suntem și lasă o adresă de contact. Nu ne dăm drept un browser.
• Se păstrează doar rândurile tale. Foaia de clasament se citește întreagă, în memorie, și apoi se reduce: rândurile tale, plus date despre cursă care nu numesc pe nimeni. Numele, codurile și localitățile celorlalți crescători se aruncă înainte să se scrie ceva.
• Nu republicăm nimic. Rezultatele importate rămân în contul tău. Nu reconstruim clasamente, nu oferim o pagină „vezi toate cursele” și nu lăsăm pe nimeni să caute pe site-ul federației prin noi.
• Când ceva nu merge, ne oprim politicos. Dacă site-ul refuză, primești o eroare cinstită. Nu insistăm, nu reîncercăm în buclă și nu ocolim nimic.

Ce ceri o dată e citit de mai multe ori: răspunsurile se păstrează, așa că zece crescători care au zburat aceeași cursă înseamnă o singură cerere către federație, nu zece.

Trimite-ne un export

Dacă federația ta sau aparatul tău scot un format pe care nu-l citim încă, trimite-ne un fișier la contact@thatpigeon.app. Ăsta e tot procesul.

Ce să trimiți: fișierul așa cum îl scoate programul, nemodificat, plus o propoziție despre ce este — ce aparat sau ce aplicație l-a produs și ce ar trebui să conțină.

Ce facem cu el. Îl folosim ca să scriem un importator și un test care rulează pe el la fiecare modificare. Un fișier ajunge în cod doar dacă e al tău și ne-ai spus explicit că îl putem folosi — altfel rămâne o probă pe care o citim și o ștergem. Regula asta e verificată automat la fiecare check: un document netrecut prin acordul respectiv nu poate intra în depozit.

Dacă fișierul conține numele altor crescători, spune-ne — putem lucra și pe o variantă din care ai șters ce nu e al tău.

Mai departe

• Datele tale — ce colectăm, unde stau datele, și pașii cu care verifici singur exportul.
• Cum calculăm — formulele din spatele numerelor din fișierul de rezultate.