comun/skills/roa-oracle-migration/SKILL.md

name: roa-oracle-migration description: Scrie si publica scripturi de migrare Oracle pentru suita ROA: script nou de schema (tabela, view, procedura, functie, pachet), coloana noua, numerotare YYYY_MM_DD_NN, incheiere cu UpdateVersiune + commit, import in UPD_DATABASE si arhiva lunara catre clienti, plus re-exportul sursei unui pachet PL/SQL. Foloseste skill-ul cand auzi "scrie un script de migrare pentru...", "publica scripturile catre clienti", "am nevoie de o coloana noua pe...", "exporta sursa pachetului Y", "modific un pachet", "adaug o optiune de meniu", "rulez scripturile la client". Acopera exact capcanele care nu dau nicio eroare: o instructiune fara ; e aruncata tacut de SQL*Plus, un NN refolosit colizioneaza intre prefixe, iar o constructie 11g+ pica doar la clientul pe Oracle 10.2. Cere compatibilitate 10.2, idempotenta si sursa de referinta MARIUSM_AUTO.

roa-oracle-migration

Scrie scripturi de migrare Oracle si publica-le catre clienti. Detalii de context: vezi Referinta, doar cand ramura o cere.

Cand se foloseste

• schimbi schema: tabela, view, procedura, functie sau pachet;
• iti trebuie o coloana noua / index / constrangere pe un obiect existent;
• scrii un script nou in D:\ROA\DATABASE\SCRIPTURI_CLAR;
• adaugi o optiune de meniu sau un drept (co_..._OBIECTE.sql);
• publici scripturile catre clienti (import in UPD_DATABASE + arhiva lunara);
• re-exporti sursa unui pachet PL/SQL sau citesti un corp de pachet (oracle_export.md).

Un agent scrie scriptul, nu il aplica. Rularea pe o schema se face doar la cererea explicita a lui Marius.

Pasi

1. Confirma ca sursa de referinta MARIUSM_AUTO (pe ROA_CENTRAL) e la zi: compara scripturile din SCRIPTURI_CLAR cu inregistrarile din VERSIUNE. Daca lipseste vreunul, opreste-te si semnaleaza-i lui Marius. Nu porni de la sursa citita dintr-o schema de client.

2. Alege numele <prefix>_YYYY_MM_DD_NN_<subiect>.sql. Prefixe in uz: ff, co, sys, ris, rf. NN e o secventa unica pe zi, comuna tuturor prefixelor.

3. Scrie scriptul ASCII, CRLF, scoped pe cazul tratat si idempotent (merge, where <coloana> is null). Un pachet sta singur in scriptul lui, fara alt DDL/DML alaturi.

4. Termina fiecare instructiune explicit cu ; (sau / pentru blocurile PL/SQL).

5. Scrie la nivel Oracle 10.2 - numitorul comun al parcului de clienti. Proba se face pe serverul cel mai vechi (ROMCONSTRUCT), nu pe dev.

6. Incheie scriptul cu:

   exec pack_migrare.UpdateVersiune('<nume_script>');
   commit;
   

   Numele se da fara .sql (extensia o adauga UpdateVersiune). UpdateVersiune e DML: fara commit explicit, versiunea nu se inregistreaza si VERSIUNE minte.

7. Publica: intai -DryRun, apoi fara, conform publicare-scripturi-db.md:

   powershell -File D:\ROA\ROAFACTURARE\COMUN\utile\publicare_scripturi.ps1 -DryRun
   powershell -File D:\ROA\ROAFACTURARE\COMUN\utile\publicare_scripturi.ps1
   

   Publicarea = import al fiecarui .sql in CONTAFIN_ORACLE.UPD_DATABASE (pe ROA_CENTRAL) si regenarea arhivei lunare in Y:\ROAUPDATE\_UPDATE\. Directorul e live.

8. Dupa publicare, strange dovezile din "Criterii de acceptare si dovada".

Capcane

• O instructiune fara ; final e ARUNCATA fara nicio eroare. Prima linie goala inchide bufferul SQL*Plus; scriptul continua pana la UpdateVersiune, se marcheaza aplicat, iar obiectul ramane cel vechi. WHENEVER SQLERROR EXIT nu prinde cazul.
• ; la capatul unei linii dintr-un comentariu -- din interiorul unei instructiuni termina instructiunea acolo: restul CREATE VIEW-ului se interpreteaza linie cu linie (SP2-0734, ORA-00936 derutant). Pune . in loc de ; in comentariu. Comentariile de dinaintea instructiunii nu sunt afectate.
• NN se colizioneaza intre prefixe: acelasi numar nu se reia intr-un alt prefix in aceeasi zi. Un script deja in VERSIUNE nu se reaplica; corectia se livreaza ca script nou, cu data si NN noi - nu prin republicarea aceluiasi fisier.
• Constructiile 11g+/12c+ trec pe dev dar pica la clientul 10.2 (REGEXP_COUNT, CONTINUE, LISTAGG, PIVOT, FETCH FIRST, identificatori peste 30 de caractere...). Detalii in scripturi-migrare-db.md.
• Un obiect nu se poate referi la ceva creat de un script ulterior. Daca un script creeaza tabela si altul pachetul care o foloseste, tabela are NN mai mic.
• LF in loc de CRLF sparge parsarea pe client (ALINES pe CHR(13)+CHR(10)): tot fisierul devine un rand. Publicarea refuza fisierele LF.
• DDL neprefixat merge pe schema conexiunii. Rularea manuala se face conectat pe schema tinta (CONTAFIN_ORACLE pentru co_, schema firmei pentru ff_), niciodata pe un user de lucru. PACK_UPDATE face singur CONNECT pe schema corecta.
• linesize prea mic corupe tacut exportul: SQL*Plus rupe liniile lungi, inclusiv prin mijlocul unui identificator. Foloseste linesize 32767; exportul e pentru citit, nu baza pentru un script de migrare.
• Niciodata select de raportare in script, insert fara ID_OBIECT explicit, sau ID_GRUP fix (grupurile difera per client).

Criterii de acceptare si dovada

Fara dovada nu se spune "gata". Ruleaza si pastreaza iesirea:

• fisierul e ASCII pur (0 octeti > 127), fara BOM, cu CRLF;
• ultima linie a fiecarui CREATE/ALTER/MERGE se termina cu ;;
• scriptul se termina cu UpdateVersiune('<nume_fara_.sql>') urmat de commit;;
• NN e liber: nu exista rand in VERSIUNE si nici fisier cu acelasi data||NN;
• dupa aplicare, select script_final from versiune where script_final = '<nume>.sql'; intoarce randul si nu ..._.sql.sql;
• publicare_scripturi.ps1 -DryRun listeaza scripturile fara sa scrie; arhiva generata se citeste inapoi si se compara lungime + MD5 per fisier;
• importul compara CLOB-ul citit inapoi octet cu octet cu fisierul.

Verificarea de ASCII + CRLF (trebuie sa intoarca 0 si True):

$b = [IO.File]::ReadAllBytes('D:\ROA\DATABASE\SCRIPTURI_CLAR\<script>.sql')
($b | Where-Object { $_ -gt 127 }).Count
($b -join ',').Contains('13,10')

Scripturi

• D:\ROA\ROAFACTURARE\COMUN\utile\publicare_scripturi.ps1 - publicare (import + arhiva). Optiuni: -DryRun, -Luna YYYY-MM, -Fisier a.sql,b.sql, -DoarImport, -DoarArhiva, -Toate. Nu copia scriptul - vezi publicare-scripturi-db.md.

• Incheierea obligatorie din fiecare script de migrare:

  exec pack_migrare.UpdateVersiune('<nume_script_fara_.sql>');
  commit;
  

• Export sursa pachet: linesize 32767, apoi verifica sa nu existe linii la exact linesize (oracle_export.md).

Referinta (doar la nevoie)

• Doar daca scrii un script nou sau ai dubii despre scheme si conectare, citeste COMUN\docs\scripturi-migrare-db.md si COMUN\docs\conventie_mediu_oracle.md.