comun/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

ROAACNPRO is a **Visual FoxPro 9** desktop application (Romanian-language) for port/lock
operations billing on the Danube. It invoices the service types defined in
`Include/roaacnpro.h`: `TRANZIT` (transit), `CHEIAJ` (wharfage), `APA` (water), `CHIRII`
(rentals), `PILOTAJ` (pilotage), `PENALITATI` (penalties), `ALTE`/`DIVERSE` (other). It is one
member of the larger "ROA" suite (ROAGEST, ROACONT, ROACASA, ROADEF, etc.) and reads vessel/
voyage/lock data from the external **RORIS Oracle** system.

The code, comments, menus, and changelog are all in Romanian — match that language when editing
user-facing strings, comments, and changelog entries.

## Build, run, version control

- **Build/run requires the Visual FoxPro 9 IDE on Windows.** There is no command-line build.
  Open `roaacnpro.pjx` in the VFP IDE and use *Build > Build Executable* to produce
  `roaacnpro.exe`. The startup program is `Programe/roaacnpro.prg` (set as the project main).
- **`.prg` files are source; `.fxp` are compiled, `.bak` are backups.** Edit the `.prg`. The
  `.scx/.sct` (forms), `.vcx/.vct` (class libraries), `.frx/.frt` (reports), and `.mnx/.mpr`
  (menus) are VFP binary/generated artifacts — **edit them in the VFP IDE, not by hand.** `.mpr`
  is GENMENU-generated from `.mnx`; never hand-edit `.mpr`.
- **Version control is Subversion** (`.svn/`), not git. `COMUN/` is its own SVN working copy.
- **`config.fpw`** sets the runtime environment (CODEPAGE 1252, `EXCLUSIVE=OFF`, `SAFETY=OFF`,
  `MULTILOCKS=ON`). Don't enable SAFETY — the code relies on silent overwrite.
- The compiler error log is `roaacnpro.ERR`; the runtime log is `log.txt`. Many entries in
  `roaacnpro.ERR` are benign cross-references resolved at runtime from `COMUN` libraries.

## The COMUN shared framework

`COMUN/` (and the sibling `..\COMUNROA\`) is **shared, framework-level code used by every ROA
app** — it is not specific to ROAACNPRO. Treat it as a vendored library:

- A change in `COMUN/` affects all ROA applications. Prefer making app-specific changes in this
  repo's top-level `Programe/`, `Clase/`, `Ferestre/`, `Rapoarte/`, `Meniuri/` directories.
  Only touch `COMUN/` when the fix genuinely belongs to the shared framework.
- `SET PATH` (see `Programe/roaacnpro.prg` ~line 37) makes `COMUN\CLASE`, `COMUN\FERESTRE`,
  `COMUN\PROGRAME`, `COMUN\RAPOARTE`, and the `COMUN\UTILE\*` helper libraries (calendar, ctl32,
  hpdf PDF, web/HTTP, nfjson, nfxml, excel, GridExtras) resolvable by bare filename. So
  `SET PROCEDURE TO email.prg` resolves to `COMUN\PROGRAME\email.prg`.

## Application architecture

Startup flow (`Programe/roaacnpro.prg`):

1. Sets `gcAppPath`, builds `gcComunPath`, `SET PATH`, `SET PROCEDURE TO roa.prg`.
2. `goApp = CreateObject("oApp")` — `oApp` is a thin subclass of **`RoaApp`**
   (`COMUN/programe/roa.prg`, ~1200 lines). This is the application object and the backbone of
   the whole framework.
3. `goApp.initializeaza(...)` runs an ordered `initializeaza*` pipeline: program check, read
   login params, Win32 declares, env, paths, class libs, procedures, settings ini, **security**
   (Oracle host/credentials, decrypted from `roa_security.xml`), report previewer, locale,
   variables, and global objects.
4. `goApp.lanseazaAplicatie()` shows `_screen`, runs the startup menu + `fundal.scx` shell form.
5. `READ EVENTS` — VFP event loop. `onShutDown` handles exit.

**App-specific overrides** live in `oApp` at the bottom of `Programe/roaacnpro.prg`: the empty
hook methods `initializeazaAlteClassLib` / `initializeazaAlteProceduri` are where this app loads
its own class libraries (`oacnpro.vcx`, `ofacturare_comun.vcx`, `serii_numere.vcx`, …) and
procedure files (`proceduri_acnpro.prg`, `ofacturare.prg`, `xmlefactura.prg`, …). When adding a
new class library or procedure file to the app, register it in one of these two methods — that
is the canonical extension point.

### Globals convention

The framework promotes the `RoaApp` properties into **public global variables** in
`initializeazaVariabileGlobale` / `initializeazaObiecteGlobale`. These are used pervasively
throughout the codebase:

- `goApp` (the app object), `goConn`/`goExecutor` (Oracle connection + SQL executor),
  `goLog`/`poLog` (logger), `goCalendar`, `goExport`, `goFundal` (shell form), `goFirma`,
  `goUtilizator`.
- `gcS` = Oracle schema, `gnIdFirma`, `gnIdUtil`, `gnAn`/`gnLuna` (working year/month),
  `gcAppPath`, `gcDirMare` (suite root), `gcComunPath`.
- `g`-prefix = global, `gc`/`gn`/`gl` = char/numeric/logical, `m.` = memory-variable scoping.

### Data layer

- Backend is **Oracle**, reached via ODBC/SQL pass-through through `goConn`/`goExecutor`. Run
  queries with `SQLEXEC()` against the connection handle; results come back as VFP cursors.
- `database.txt` documents the Oracle setup: it creates **synonyms** (`ips_voyages`,
  `ips_berthings`, `ips_cargoes`, …) into the external `roris` schema and `GRANT`s to the app
  user. The `ips_*` tables are RORIS source data; `ips_*_vanzari` and the app's own tables hold
  billing data. `versiune_db.txt` tracks the DB schema version.
- App tables and report cursors carry Romanian/domain names (`tranzit`, `cheiaj`, `factura`,
  `recapitulatie`, `tarife`, `contracte`).

## Domain quick reference

- **Service-type constants** are in `Include/roaacnpro.h` (string `TIP_*` and numeric `NTIP_*`,
  e.g. `NTIP_TRANZIT 0`, `NTIP_CHEIAJ 1`). These same defines are repeated at the top of
  `Programe/proceduri_acnpro.prg`.
- **`Programe/proceduri_acnpro.prg`** — core billing procedures (`factura_salvare_db`,
  `calcul_cheiaj`, `salvare_cheiaj`, `make_factura_penalitati`, TVA/VAT handling, …). The file
  header is an append-only dated change journal; follow that style when adding procedures.
- **`docs/facturare.md`** — read this first for any **invoice/billing change**: it maps the
  invoice flow (form `frm_factura` → `factura_salvare_db` → `PACK_FACTURARE.pck` → reports/list),
  the `crsFactura` structure, the VAT formulas, and which files to touch for a given task. Key
  rule: `PACK_FACTURARE.pck` is the source of truth; the `frm_factura` preview must mirror its
  formulas, and reports/list only read package-computed values.
- **`Programe/proceduri_acnpro_rapoarte.prg`** — report-generation procedures feeding the
  `Rapoarte/*.frx` layouts (factura, recapitulatie_cheiaj/tranzit/penalitati, registru tranzit).
- **`Programe/importroris*.prg`** + `importroris.pjx` — a *separate* small executable
  (`importroris.exe`) that imports voyage/lock data from RORIS. `verificare_roris_ecluze.*` is
  another standalone verification tool. These build independently of the main project.
- **VAT/TVA** is first-class and time-sensitive: the app supports multiple concurrent VAT-rate
  regimes (e.g. 19/9/5% historical vs. 21/11% from 2025-08-01). Be careful that billing logic
  selects rates by the document's period, not "current" rates.

## Changelog & release convention

`changelog_roaacnpro.txt` is the user-facing release log. **Newest entry goes at the top**, in
this exact HTML-comment block format (Romanian, `DD/MM/YYYY`):

```
<!--
10/02/2026
ROAACNPRO - 2.0.3

:modificare:
  <what changed>
-->
```

Tags: `:nou:` (new feature), `:modificare:` (change), `:eroare:` (bug fix). Bump the
`MAJOR.MINOR.PATCH` version when you add an entry. The app auto-updates from
`https://www.romfast.ro/...` via `COMUN/programe/actualizare_aplicatie.prg`; the runtime reads
its version from the built `.exe`.