Initial: flux text FoxBin2Prg (git urmareste .??2 in-arbore, binarele VFP git-ignored)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
214
CLAUDE.md
Normal file
214
CLAUDE.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## What this is
|
||||
|
||||
ROACONT ("ROA Financiar Contabilitate") is a Visual FoxPro 9 desktop accounting
|
||||
application, one product in the ROA business-software suite built by ROA Romfast SRL.
|
||||
It is a thick client: VFP source (`.prg`, `.scx`, `.vcx`, `.mnx`, `.frx`) compiled to an
|
||||
`.exe`, talking to an Oracle backend over ODBC/native connections. There is no web
|
||||
front-end and no package-manager-based build.
|
||||
|
||||
This directory (`D:\ROA\ROACONT`) is one working copy inside a much larger `D:\ROA`
|
||||
tree that holds dozens of sibling ROA products (ROAGEST, ROACASA, ROAAUTO, ROAMANAGER,
|
||||
ROAEFACTURA, ROASAL, etc.) plus a suite-wide shared library at `D:\ROA\COMUNROA`.
|
||||
Changes to shared code can ripple into other products — see "Shared code" below.
|
||||
|
||||
## Version control
|
||||
|
||||
This is primarily an **SVN** working copy (`svn info` → `^/ROACONT/Trunk`,
|
||||
repository root `http://svnroa:3001/svn/ROA`). Use `svn status`, `svn diff`, `svn commit`,
|
||||
`svn log`, etc. for the day-to-day legacy workflow.
|
||||
|
||||
A **git** mirror also runs in parallel, pushed to `gitea.romfast.ro:romfast/roacont.git`.
|
||||
SVN remains the "live" source of truth; git is synced to it manually, not the other way
|
||||
around. `.svn/` is git-ignored. `COMUN/` is excluded from this repo's git (see `.gitignore`)
|
||||
because it's shared by every ROA product and is versioned by its **own separate git repo**,
|
||||
`gitea.romfast.ro:romfast/comun.git` (same remote used by ROAACNPRO and other siblings) —
|
||||
run git commands for `COMUN/` from inside that directory, not from the ROACONT root.
|
||||
|
||||
Git tracks the **FoxBin2Prg text versions** of the VFP binaries
|
||||
(`.vc2/.sc2/.fr2/.mn2/.lb2/.pj2/.dc2/.db2`), generated in-tree next to each binary — not the
|
||||
binaries themselves. The binaries and regenerable indexes (`.cdx/.dcx`) are git-ignored (SVN
|
||||
stays the EOL authority), so git diffs are readable text. Refresh those text versions with
|
||||
`git_sync.ps1` (folder-mode recursive over the whole tree incl. `COMUN\`, incremental):
|
||||
```
|
||||
powershell -ExecutionPolicy Bypass -File D:\ROA\UTIL\foxbin2prg\git_sync.ps1 -ProjectRoot D:\ROA\ROACONT
|
||||
```
|
||||
Run it **at the start of every session and before any `git commit`** so the text matches the
|
||||
binaries. It converts in a temp staging area and copies back only the text (never touches the
|
||||
SVN working-copy binaries), continues past per-file failures, and exits nonzero on any failure:
|
||||
**do not commit while `git_sync` reports unexplained failures.** Then search the `.??2` files
|
||||
in-tree with Grep (e.g. `PROCEDURE do_salvare`), citing `file:line`.
|
||||
|
||||
Editing: write-back text→binary via `txt2vcx.ps1` is supported **only for `.vc2/.sc2`**
|
||||
(vcx/scx); `.frx/.mnx/.lbx/.pjx/.dbc/.dbf` are editable **only in the VFP IDE** (no write-back).
|
||||
See `D:\ROA\UTIL\foxbin2prg\CLAUDE.md` and `COMUN\docs\flux-editare-vfp-text.md`.
|
||||
|
||||
Orphan cleanup: on each full run `git_sync` deletes `.??2` text whose binary was removed from
|
||||
SVN (and `.db2` whose table left the per-project list) and reports it, so git records the
|
||||
deletion.
|
||||
|
||||
SVN ignores the `.??2` files via `global-ignores` in the machine's local Subversion config
|
||||
(`%APPDATA%\Subversion\config`, `[miscellany]`), together with `*.dbf.cfg`. Limitation:
|
||||
global-ignores only covers *unversioned* files — if a `.??2` ever gets `svn add`-ed, remove it
|
||||
with `svn rm --keep-local`. The `.dbf.cfg` files (per-table export config that makes `.db2`
|
||||
carry data, not just structure) are committed to git but sit in SVN global-ignores.
|
||||
|
||||
### Branching (git)
|
||||
|
||||
Two lanes in the git mirror:
|
||||
- **`main` = SVN mirror**: receives ONLY `sync SVN rN` commits, made from a clean tree (right
|
||||
after `svn update`, before local work). `git diff main..claude/<subiect>` then shows exactly
|
||||
and only Claude's work.
|
||||
- **Claude works on a branch** (`claude/<subiect>`) and commits only there.
|
||||
- Once the changes land in SVN (user runs `svn commit`), the branch is closed (merged into
|
||||
`main` at the next sync, or deleted).
|
||||
- Hygiene: sync `main` only from a clean tree — an `svn update` mid-work mixes binaries on disk
|
||||
(nature of SVN).
|
||||
|
||||
## Building / running
|
||||
|
||||
There is no CLI build tool. The project is compiled from inside the Visual FoxPro 9 IDE:
|
||||
|
||||
- Project file: `roacont.PJX` / `roacont.PJT` (open in VFP, then Project > Build / Rebuild
|
||||
to produce `roacont.exe`).
|
||||
- Every `.prg`/`.scx`/`.vcx`/`.mnx` source file has a compiled sibling (`.FXP`/`.SCT`/`.VCT`/`.MPR`).
|
||||
**Always edit the source file, never the compiled binary companion** — the binaries are
|
||||
regenerated by the VFP compiler and are not meant to be hand-edited or diffed.
|
||||
- `.BAK` files scattered throughout `Programe/`, `Clase/`, etc. are VFP's own editor backups,
|
||||
not something to restore from manually.
|
||||
- There are no automated tests. `COMUN/utile/Teste/test.prg` and `teste_roacont.prg` are
|
||||
ad hoc manual test scripts, not a test runner.
|
||||
|
||||
## Entry point and startup flow
|
||||
|
||||
`Programe/roacont.prg` is the application entry point (`PARAMETERS tparam` — a semicolon-
|
||||
delimited connection string when launched by the ROA "Start" launcher). It:
|
||||
|
||||
1. Sets the VFP environment (`SET PATH`, `SET CLASSLIB`/`SET PROCEDURE ... ADDITIVE`) —
|
||||
this is effectively the dependency-injection root: dozens of `.vcx` class libraries and
|
||||
`.prg` procedure files are registered here in a fixed order, and later code assumes they're
|
||||
all loaded. New shared `.prg`/`.vcx` files must be registered here to be reachable app-wide.
|
||||
2. Verifies the license/serial (`PORNIRE()` — disk serial + `comdir.snr` + registry key check)
|
||||
and that the app was launched via the suite's start mechanism (`Verific_Start`), unless a
|
||||
local `debug.txt` marker is present.
|
||||
3. Reads `settings.ini` (via `getini`/`setini`, `COMUN` ini helpers) for local machine config
|
||||
(report behavior, keepalive interval, error-reporting host, locale).
|
||||
4. Instantiates global singleton objects that the rest of the app depends on as `PUBLIC`/module
|
||||
globals: `goConn` (Oracle connect/disconnect wrapper), `goExecutor` (SQL exec wrapper with
|
||||
error handling), `goExport` (report/Excel export), `goLocale` (i18n), `poLog`/`goLog`
|
||||
(`Log_Mesaje` logging object), `goApi`/`goMyXMLHTTP` (remote error/update HTTP calls).
|
||||
5. Sets `ON ERROR ErrorHandler(...)` and `ON SHUTDOWN` handlers — uncaught errors are logged via
|
||||
`goLog`, posted to a remote error endpoint (`goMyXMLHTTP.postError`, host from
|
||||
`settings.ini` `[errors] host`), and shown via `AMESSAGEBOX`.
|
||||
6. Creates the main `cApplication` object (`goApp`) and shows the login form
|
||||
(`COMUN\ferestre\frm_login.scx`), which resolves the target company (`goFirma`), Oracle
|
||||
schema (`gcS`, e.g. `'CONTAFIN'`), and fiscal period (`gnAn`/`gnLuna`) before handing off to
|
||||
the main menu (`Meniuri\cont2000.mpr`).
|
||||
|
||||
Key long-lived globals to know when reading code: `gcS` (current Oracle schema/company),
|
||||
`gnAn`/`gnLuna` (current fiscal year/month), `goFirma`/`gnIdFirma` (current company object/id),
|
||||
`gcAppPath`/`DIRGEN` (app root paths), `glLunaInchisa` (period-closed flag that disables edit UI).
|
||||
|
||||
## Directory layout
|
||||
|
||||
- `Programe/` — top-level `.prg` business-logic modules registered via `SET PROCEDURE ...
|
||||
ADDITIVE` in `roacont.prg` (e.g. `proceduri.prg`, `oproceduri_*.prg` per functional area:
|
||||
incasari, casademarcat, conversie, decont, import, facturare, etc.).
|
||||
- `Clase/` — `.vcx`/`.vct` VFP class libraries: base UI classes (`cont2000`, `contab`, `baza`),
|
||||
Oracle-domain classes prefixed `o*` (`oparteneri`, `ovanzcump`, `ocasabanca`, `orapoarte_*`,
|
||||
`oconversii`, `saft_d406`, `anaf_efactura`, ...).
|
||||
- `Ferestre/` — `.scx`/`.sct` forms (data entry screens, dialogs).
|
||||
- `Meniuri/` — `.mnx`/`.mnt`/`.mpr` menus; one `.mpr` per top-level menu context
|
||||
(`cont2000.mpr` is the main menu; `casa1`, `banca1`, `capitaluri1`...`8`, etc. are
|
||||
module-specific submenus/menus).
|
||||
- `Rapoarte/` — `.frx`/`.frt` report definitions (balances, journals, declarations like
|
||||
`rap_declaratia100`, D394/D406/SAF-T exports, invoices).
|
||||
- `Include/` — third-party OCX controls and reference docs (SAF-T guide, D394 spec).
|
||||
- `Initializari/` — `.tmpl` templates for generated XML/receipt files.
|
||||
- `Locale/` — DBF-based i18n tables (`locale*.dbf`) and `locale.dbc` database container;
|
||||
Romanian is the built-in default (see Localization below).
|
||||
- `DATE/` — local machine/company option tables (`Optiuni_FIRMA/LOCAL/PROGRAM.dbf`).
|
||||
- `Grafice/` — icons/bitmaps used by forms and toolbars.
|
||||
- `Help/` — DBF-based in-app help content tables.
|
||||
- `Alte/` — scratch/example data files (bank statement exports, import templates); not part
|
||||
of the shipped app.
|
||||
- Root `.sql` files (`roacont1/2/3.sql`, `anaf_efactura.sql`, `vanzari*.sql`, `mfinante.sql`) —
|
||||
hand-run Oracle DDL/DML migrations, not applied automatically.
|
||||
- `changelog_roacont.txt`, `bug_registru.txt` — human-maintained change logs (see Changelog
|
||||
convention below).
|
||||
- `versiune_db.txt` — a manually bumped `YYYY_MM_DD_NN` marker used to track the last applied
|
||||
DB migration.
|
||||
|
||||
### Shared code (`COMUN/` vs. `COMUNROA`)
|
||||
|
||||
- `COMUN/` inside this project is ROACONT's *local* copy of shared assets (`clase`, `ferestre`,
|
||||
`programe`, `rapoarte`, `meniuri`, `utile`), mirroring the same substructure as the app root.
|
||||
`COMUN/utile/` holds cross-cutting utilities: `web` (`WWUTILS.PRG`, `WWAPI.PRG`, `wwhttp`,
|
||||
http/xml helpers), `excel`, `hpdf` (PDF export), `nfjson`/`nfXml`, `calendar`, `ctl32`,
|
||||
`email`, `chatbot`, `GridExtras`.
|
||||
- `D:\ROA\COMUNROA` (outside this working copy) is the suite-wide shared library referenced
|
||||
from `roacont.prg`'s `SET PATH` (`...COMUNROA\`) and used by every sibling ROA product —
|
||||
treat edits there as cross-project and higher-blast-radius than edits under this project's
|
||||
own `COMUN/`.
|
||||
- `COMUN/Drepturi utilizatori/` holds the per-product SQL that defines user permission objects
|
||||
(subfolders per product: `ROACONT`, `ROAGEST`, `ROACASA`, `ROAAUTO`, ...) and
|
||||
`instructiuni drepturi.txt`, which documents the permission-object conventions used on forms
|
||||
(`ntip` values 0–5 for view/report/register/ledger-or-partner/view/custom access levels,
|
||||
`verifica_drepturi(...)` gating, `cbuton1..4` button wiring, `glLunaInchisa` read-only lock).
|
||||
|
||||
## Changelog convention
|
||||
|
||||
`changelog_roacont.txt` is a flat file of HTML-comment blocks, newest first, one per release:
|
||||
|
||||
```
|
||||
<!--
|
||||
DD/MM/YYYY
|
||||
ROACONT - X.Y.Z
|
||||
|
||||
:tag:
|
||||
Description of the change.
|
||||
-->
|
||||
```
|
||||
|
||||
Tags in use: `:nou:` (new feature), `:modificare:` (change/fix to existing behavior),
|
||||
`:eroare:` (bug fix), `:adaugare:` (addition). Version numbers increment per entry (current
|
||||
series is `2.11.x`). When asked to log a change, follow this exact format/tag set rather than
|
||||
inventing a new one. In-code change comments follow a similar per-block convention:
|
||||
`*!* DD.MM.YYYY` followed by `*!* author.name` and a short description, directly above the
|
||||
code being changed — preserve this style when editing existing modules.
|
||||
|
||||
## Localization
|
||||
|
||||
`gcLocale` defaults to `'Romana'`, in which case `goLocale` is a `Locale_dummy` pass-through
|
||||
(no translation lookup). Any other locale value loads the real `Locale` class (`Locale.vcx`)
|
||||
backed by the `locale*.dbf` tables under `Locale/`. Most in-app strings and comments are
|
||||
Romanian; keep new user-facing strings and code comments in Romanian to match the existing
|
||||
codebase unless told otherwise.
|
||||
|
||||
## Reguli de lucru si testare
|
||||
|
||||
Obligatoriu la modificari de cod si testare: `COMUN\docs\reguli_lucru.md`
|
||||
(diff ca fisier + aprobare inainte de write-back; comentarii max o linie;
|
||||
testare headless cu `COMUN\utile\Teste\test_init_env_auto.prg`).
|
||||
Depanare detaliata: `COMUN\docs\depanare_testare_vfp.md`.
|
||||
|
||||
## Skill routing
|
||||
|
||||
When the user's request matches an available skill, invoke it via the Skill tool. When in doubt, invoke the skill.
|
||||
|
||||
Key routing rules:
|
||||
- Product ideas/brainstorming → invoke /office-hours
|
||||
- Strategy/scope → invoke /plan-ceo-review
|
||||
- Architecture → invoke /plan-eng-review
|
||||
- Design system/plan review → invoke /design-consultation or /plan-design-review
|
||||
- Full review pipeline → invoke /autoplan
|
||||
- Bugs/errors → invoke /investigate
|
||||
- QA/testing site behavior → invoke /qa or /qa-only
|
||||
- Code review/diff check → invoke /review
|
||||
- Visual polish → invoke /design-review
|
||||
- Ship/deploy/PR → invoke /ship or /land-and-deploy
|
||||
- Save progress → invoke /context-save
|
||||
- Resume context → invoke /context-restore
|
||||
Reference in New Issue
Block a user