refactor: comentarii strict functionale, fara referinte PRD/stories

Curatare globala a comentariilor si docstring-urilor (app, tools, teste,
scripturi): eliminate referintele la PRD-uri, US-xxx, task-uri istorice si
review-uri; pastrata doar informatia functionala, formulata scurt. Regula
adaugata in CLAUDE.md (sectiunea Stil). Fara modificari de cod sau comportament.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

app/api/v1/import_router.py

@@ -1,4 +1,4 @@
-"""Router import Treapta 2 — upload fisier xlsx/csv, preview, commit, export.
+"""Router import — upload fisier xlsx/csv, preview, commit, export.
 
 Endpointuri:
   POST   /v1/import                     — upload fisier, staging in import_batches/import_rows
@@ -190,7 +190,7 @@ def _resolve_row_for_preview(
         denumire = str(denumire_val).strip() if denumire_val not in (None, "") else str(operatie_val)
         mapped["prestatii"] = [{"cod_op_service": str(operatie_val), "denumire": denumire}]
 
-    # obs derive-on-empty (D7/E3 PRD 5.15): daca obs e gol si avem operatie,
+    # obs derive-on-empty: daca obs e gol si avem operatie,
     # copiem denumirea operatiei in obs (nu o mutam — op_service ramane neatins).
     # DERIVE-ON-EMPTY: doar cand obs e gol, ca sa fie idempotent la re-preview/re-editare.
     obs_curent = str(mapped.get("obs") or "").strip()
@@ -236,7 +236,7 @@ def _resolve_row_for_preview(
     if all_flags and not reviewed:
         # needs_review: validarea a trecut, dar flagurile (date ambigue, formule) cer confirmare manuala.
         # Daca reviewed=True (operatorul a confirmat explicit valorile in modal), sarim
-        # acest return si continuam spre ok/needs_data (US-007, PRD 5.12).
+        # acest return si continuam spre ok/needs_data.
         return {
             "resolved_status": "needs_review",
             "resolved": mapped,
@@ -244,8 +244,6 @@ def _resolve_row_for_preview(
             "flags": all_flags,
         }
 
-    # US-001 (PRD 5.11): ramura auto_send eliminata din preview.
-
     if errors:
         return {
             "resolved_status": "needs_data",
@@ -361,7 +359,7 @@ def apply_row_override(
 
     new_override = _merge_override(current, fields)
     enc = encrypt_creds(new_override) if new_override else None
-    # D#9 (PRD 5.12): resetam reviewed=0 la orice schimbare de valoare — operatorul
+    # Resetam reviewed=0 la orice schimbare de valoare — operatorul
     # trebuie sa reconfirme dupa editare. NU conditionam pe reviewed curent: orice override
     # (chiar si revert la valoarea initiala) anuleaza confirmarea implicita.
     conn.execute("UPDATE import_rows SET override_json=?, reviewed=0 WHERE id=?", (enc, row["rid"]))
@@ -965,7 +963,7 @@ def commit_import(
         if batch["status"] == "committed":
             raise HTTPException(status_code=409, detail="batch deja comis")
 
-        # D#8 (PRD 5.12): gate commit derivat din DB `reviewed` pe AMBELE canale.
+        # Gate commit derivat din DB `reviewed` pe AMBELE canale.
         # API: reviewed_rows pastrat (contract stabil) dar seteaza reviewed=1 in DB inainte
         # de interogare. Randurile needs_review cu reviewed=1 sunt incluse in comit.
         if req.reviewed_rows:
@@ -1032,7 +1030,7 @@ def commit_import(
         if n_total_ok == 0:
             raise HTTPException(status_code=422, detail="Niciun rand ok de confirmat.")
 
-        # Rezolva mediul RAR tinta al lotului (US-009): cerut > default cont > ancora globala.
+        # Rezolva mediul RAR tinta al lotului: cerut > default cont > ancora globala.
         try:
             env = rezolva_rar_env(conn, account_id, req.rar_env)
         except ValueError as e:
@@ -1044,8 +1042,8 @@ def commit_import(
                 "disponibile": e.disponibile,
             })
 
-        # T3 (PRD 5.17): enforce volum plan — INAINTE de enqueue (invariant idempotenta).
-        # Decizie #21: respingere TOTALA a lotului (nu enqueue partial tacut).
+        # Enforce volum plan — INAINTE de enqueue (invariant idempotenta).
+        # Respingere TOTALA a lotului (nu enqueue partial tacut).
         from ...config import get_settings as _get_settings
         from ...plans import PLANS, effective_tier, monthly_usage
         from ...observ import log_event as _log_event_plan
@@ -1126,7 +1124,7 @@ def commit_import(
         conn.execute("BEGIN IMMEDIATE")
         try:
             purge_after_sql = "datetime('now', '+90 days')"
-            # PRD 5.19 US-002: snapshot `held` din comutatorul contului (chokepoint unic
+            # Snapshot `held` din comutatorul contului (chokepoint unic
             # held_for_account) — 0 daca Auto ON, 1 daca Auto OFF. Per-cont -> o data.
             held_val = held_for_account(conn, acct)
 
@@ -1162,7 +1160,7 @@ def commit_import(
                     denumire = str(denumire_val).strip() if denumire_val not in (None, "") else str(operatie_val)
                     mapped["prestatii"] = [{"cod_op_service": str(operatie_val), "denumire": denumire}]
 
-                # obs derive-on-empty (D7/E3 PRD 5.15): copiere denumire in obs daca obs e gol.
+                # obs derive-on-empty: copiere denumire in obs daca obs e gol.
                 # Identic cu logica din _resolve_row_for_preview (override aplicat tot ultimul).
                 obs_curent = str(mapped.get("obs") or "").strip()
                 if not obs_curent and operatie_val:
@@ -1272,7 +1270,7 @@ def commit_import(
 class RandEditIn(BaseModel):
     """Campuri de continut editabile in preview. None = ne-trimis (neschimbat);
     "" = sterge override-ul (revine la valoarea din fisier).
-    obs = text liber fara validare de continut (US-005 PRD 5.15)."""
+    obs = text liber fara validare de continut."""
     vin: str | None = None
     nr_inmatriculare: str | None = None
     data_prestatie: str | None = None

app/api/v1/integrare_router.py

@@ -57,7 +57,7 @@ def ping(
             conn.close()
         autentificat_cu_cheie = acct is not None
 
-    # Verificam daca contul are creds RAR stocate (per-env, US-013).
+    # Verificam daca contul are creds RAR stocate (per mediu).
     aid = account_or_default(account_id)
     conn = get_connection()
     try:

app/api/v1/router.py

@@ -88,7 +88,7 @@ def _erori_nemapate(unmapped: list[dict]) -> list[dict]:
     ]
 
 
-# PRD 5.19 US-010: mesaj uman pentru un rand tinut manual (queued AND held=1).
+# Mesaj uman pentru un rand tinut manual (queued AND held=1).
 # Reutilizeaza vocabularul existent AUTO_SEND_OPRIT (errors.py) — nu inventam al treilea
 # vocabular "auto_send". Onestitate: raspunsul NU trebuie sa arate un "queued" curat fals.
 MOTIV_HELD = (
@@ -107,8 +107,7 @@ def _motiv_clasificare(cl: dict) -> str | None:
 
     None cand status='queued'. Acopera ramurile de blocaj: erori de continut
     (needs_data) si coduri fara mapare RAR (needs_mapping).
-    Dupa US-001: needs_mapping apare EXCLUSIV cand unmapped e non-gol
-    (ramura auto_send_oprit era inaccesibila si a fost eliminata).
+    needs_mapping apare EXCLUSIV cand unmapped e non-gol.
     """
     if cl["status"] == "queued":
         return None
@@ -127,7 +126,7 @@ def _rezultat_enqueue(submission_id: int | None, cl: dict, held: int = 0, **extr
 
     Populeaza erori (validare continut), nemapate (coduri fara mapare) si motiv (uman)
     pentru orice status != 'queued'. Aditiv: pe 'queued' toate raman goale/None, EXCEPTAND
-    randurile tinute manual (PRD 5.19 US-010: `held=1` -> held=true + motiv non-null).
+    randurile tinute manual (`held=1` -> held=true + motiv non-null).
     """
     tinut = bool(held)
     motiv = _motiv_clasificare(cl) or _motiv_held(cl["status"], tinut)
@@ -179,7 +178,7 @@ def create_prezentari(
     conn = get_connection()
     results: list[SubmissionResult] = []
     try:
-        # load_mapping_meta incarca maparea op->cod RAR; dupa US-001, auto_send nu mai tine randuri.
+        # load_mapping_meta incarca maparea op->cod RAR; auto_send nu mai tine randuri.
         mapping_meta = load_mapping_meta(conn, acct)
         mapping = {op: meta["cod_prestatie"] for op, meta in mapping_meta.items()}
         # Validare cod_prestatie fata de nomenclator + modul la cod necunoscut/nemapat.
@@ -189,12 +188,12 @@ def create_prezentari(
         text_rules = load_text_rules(conn, acct)
         error_mode = _effective_on_unmapped_error(conn, acct, req.on_unmapped_error)
 
-        # US-005: rezolva mediul RAR tinta (cerut > default cont > ancora globala).
+        # Rezolva mediul RAR tinta (cerut > default cont > ancora globala).
         # MediuIndisponibil -> 422 inainte de orice enqueue (respinge tot lotul).
         try:
             env = rezolva_rar_env(conn, acct, req.rar_env)
         except MediuIndisponibil as e:
-            # US-012: audit blocare mediu indisponibil (tip='rar_env_blocat').
+            # Audit blocare mediu indisponibil (tip='rar_env_blocat').
             log_event(
                 "rar_env_blocat",
                 nivel="WARNING",
@@ -220,8 +219,8 @@ def create_prezentari(
                 detail=err_eroare("RAR_MEDIU_INDISPONIBIL", cauza="valoare invalida pentru rar_env"),
             )
 
-        # T3 (PRD 5.17): enforce volum plan — INAINTE de build_key/enqueue (invariant idempotenta).
-        # Decizie #21: respingere TOTALA a lotului (nu enqueue partial tacut).
+        # Enforce volum plan — INAINTE de build_key/enqueue (invariant idempotenta).
+        # Respingere TOTALA a lotului (nu enqueue partial tacut).
         from ...config import get_settings as _get_settings
         from ...plans import PLANS, effective_tier, monthly_usage
         _settings = _get_settings()
@@ -259,8 +258,8 @@ def create_prezentari(
                         ),
                     )
 
-        # PRD 5.19 US-002: snapshot `held` din comutatorul contului (chokepoint unic
-        # held_for_account). 0 daca Auto ON, 1 daca Auto OFF (tine randul). Depinde de
+        # Snapshot `held` din comutatorul contului (chokepoint unic held_for_account).
+        # 0 daca Auto ON, 1 daca Auto OFF (tine randul). Depinde de
         # cont, nu de rand -> calculat o data. NU intra in payload/idempotenta.
         held_val = held_for_account(conn, acct)
 
@@ -291,9 +290,8 @@ def create_prezentari(
                         # on_unmapped_error=True: nu reactivam; randul ramane 'error'.
                         results.append(_rezultat_respins(existing["id"], cl, rar_env=env))
                         continue
-                    # PRD 5.19 US-002 (Eng Finding A — bug de bypass): la reactivare
-                    # re-snapshot-am `held` din comutatorul contului. Fara asta randul
-                    # pastra held VECHI si se auto-trimitea desi contul e Auto OFF.
+                    # La reactivare re-snapshot-am `held` din comutatorul contului. Fara
+                    # asta randul pastra held VECHI si se auto-trimitea desi contul e Auto OFF.
                     cur = conn.execute(
                         "UPDATE submissions SET status=?, payload_json=?, rar_error=?, "
                         "rar_creds_enc=COALESCE(?, rar_creds_enc), retry_count=0, "
@@ -304,7 +302,7 @@ def create_prezentari(
                     )
                     if cur.rowcount == 1:
                         # Creds noi se propaga si in slotul durabil per-env al contului
-                        # — ambele canale converg pe parola corectata (US-013, env-aware).
+                        # — ambele canale converg pe parola corectata (env-aware).
                         if req.rar_credentials is not None:
                             conn.execute(
                                 f"UPDATE accounts SET rar_creds_{env}_enc=?, rar_{env}_enabled=1 WHERE id=?",
@@ -321,7 +319,7 @@ def create_prezentari(
                         "SELECT id, status, id_prezentare, held FROM submissions WHERE id=?",
                         (existing["id"],),
                     ).fetchone()
-                # Echo onest pe dedup (PRD 5.19 US-002/US-010): propaga `held` al randului
+                # Echo onest pe dedup: propaga `held` al randului
                 # existent — un rand tinut NU trebuie sa apara ca un "queued" curat fals.
                 dedup_held = bool(existing["held"])
                 results.append(
@@ -338,13 +336,13 @@ def create_prezentari(
                 continue
 
             # Helper pur partajat cu dry-run: reproduce EXACT clasificarea
-            # (canonicalize + mapare op->cod + validare; auto_send gate eliminat dupa US-001).
+            # (canonicalize + mapare op->cod + validare; fara gate auto_send).
             cl = _classify_modal(content, mapping, mapping_meta, valid_codes, error_mode, text_rules)
             if cl["blocked_error"]:
                 # on_unmapped_error=True: respinge fara enqueue (cod necunoscut/nemapat).
                 results.append(_rezultat_respins(None, cl, rar_env=env))
                 continue
-            # PRD 5.19 US-002: `held` = snapshot comutator cont (chokepoint held_for_account).
+            # `held` = snapshot comutator cont (chokepoint held_for_account).
             cur = conn.execute(
                 "INSERT INTO submissions (idempotency_key, account_id, status, payload_json, rar_error, rar_creds_enc, rar_env, held) "
                 "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
@@ -401,11 +399,11 @@ def valideaza_prezentari(
         text_rules = load_text_rules(conn, acct)
         error_mode = _effective_on_unmapped_error(conn, acct, req.on_unmapped_error)
 
-        # US-005 (DX F5): rezolva env identic ca trimiterea reala si ecou-ieste in raspuns.
+        # Rezolva env identic ca trimiterea reala si ecou-ieste in raspuns.
         try:
             env = rezolva_rar_env(conn, acct, req.rar_env)
         except MediuIndisponibil as e:
-            # US-012: audit blocare mediu indisponibil pe dry-run (tip='rar_env_blocat').
+            # Audit blocare mediu indisponibil pe dry-run (tip='rar_env_blocat').
             log_event(
                 "rar_env_blocat",
                 nivel="WARNING",
@@ -464,7 +462,7 @@ def list_prezentari(
         scope_sql, scope_params = account_scope_clause(account_id)
         # payload_json e plaintext (vezi submissions.payload_json); il citim doar ca
         # sa derivam campurile afisabile prin helper-ul partajat, nu il expunem.
-        # rar_env inclus (US-005): badge mediu in lista.
+        # rar_env inclus: badge mediu in lista.
         cols = (
             "id, status, id_prezentare, rar_status_code, retry_count, "
             "created_at, updated_at, payload_json, rar_env, held"
@@ -502,9 +500,9 @@ _PREZENTARE_FIELDS = frozenset({
     # erori din catalog (niciodata creds, ex. RAR_CREDS_INVALIDE poarta doar cauza
     # "credentiale RAR invalide", fara parola). Face recovery-ul observabil prin API.
     "rar_error",
-    # US-005: mediul RAR tinta (Test/Productie) — necesar pentru badge + ecou API.
+    # Mediul RAR tinta (Test/Productie) — necesar pentru badge + ecou API.
     "rar_env",
-    # PRD 5.19 US-010: flag `held` (tinut manual) — onestitate GET (dev vede ca NU a plecat).
+    # Flag `held` (tinut manual) — onestitate GET (dev vede ca NU a plecat).
     "held",
 })
 
@@ -589,7 +587,7 @@ def trimite_acum_prezentare(
     submission_id: int,
     account_id: int = Depends(resolve_account_id),
 ) -> dict:
-    """Elibereaza manual un rand tinut (PRD 5.19 US-010, paritate API cu /repune).
+    """Elibereaza manual un rand tinut (paritate API cu /repune).
 
     Scoped strict pe contul cheii API (account_id din sesiune/cheie, NICIODATA din body).
     404-before-leak pe id strain/inexistent. `held: 1 -> 0` DOAR daca randul e
@@ -639,7 +637,7 @@ AUDIT_COLUMNS = [
     "odometru_final",
     "prestatii",
     "rar_status_code",
-    # US-010 (PRD 5.20): mediul RAR tinta per trimitere.
+    # Mediul RAR tinta per trimitere.
     "rar_env",
     "created_at",
     "updated_at",
@@ -694,7 +692,7 @@ def _audit_rows(conn, date_from: str | None, date_to: str | None, status: str, a
             "odometru_final": p.get("odometru_final") or "",
             "prestatii": codes,
             "rar_status_code": r["rar_status_code"] or "",
-            # US-010 (PRD 5.20): mediul RAR tinta — coloana audit.
+            # Mediul RAR tinta — coloana audit.
             "rar_env": r["rar_env"] or "",
             "created_at": r["created_at"],
             "updated_at": r["updated_at"],
@@ -826,7 +824,7 @@ def set_rar_creds(
     req: RarCredsIn,
     account_id: int = Depends(resolve_account_id),
 ) -> dict:
-    """Seteaza creds RAR durabile per-cont, in slotul per-mediu (US-013, env-aware).
+    """Seteaza creds RAR durabile per-cont, in slotul per-mediu (env-aware).
 
     Slotul tinta: `req.rar_target` ('test'/'prod') sau ancora globala (AUTOPASS_RAR_ENV).
     Activeaza mediul selectat (`rar_{env}_enabled=1`). Worker-ul le foloseste ca
@@ -855,7 +853,7 @@ def delete_rar_creds(
     account_id: int = Depends(resolve_account_id),
     env: str | None = None,
 ) -> dict:
-    """Sterge creds RAR durabile per-cont (revenire la modelul efemer Treapta 1).
+    """Sterge creds RAR durabile per-cont (revenire la modelul efemer per submission).
 
     `env` (query param): 'test' | 'prod' -> sterge DOAR slotul acelui mediu + dezactiveaza-l.
     Absent -> sterge AMBELE sloturi (revenire completa). Schimbare aditiva (back-compat).