Add 'fiscal/' from commit '102ba84500dbd9655a0471288c3e278652593ca9'
git-subtree-dir: fiscal git-subtree-mainline:d95165fc8fgit-subtree-split:102ba84500
This commit is contained in:
gti
@@ -0,0 +1,130 @@
|
||||
# GTI Discovery
|
||||
|
||||
**Primeira leitura obrigatória, antes de qualquer missão fiscal nova**: `docs/PROJECT_STATE.md`
|
||||
(versões Hub/Agent, migration head de cada branch, status do Reference Data Registry, decisões
|
||||
ADMIN pendentes, o que já foi feito e o que falta, riscos abertos). Mantê-lo atualizado ao final
|
||||
de cada missão que mude esse estado.
|
||||
|
||||
This project is strictly read-only. Discovery code must use a database-level
|
||||
read-only account or transaction/driver mode; lexical SQL validation is only
|
||||
defense-in-depth. Discovery code must not perform DML or DDL,
|
||||
modify database objects or permissions, or store credentials and other secrets.
|
||||
|
||||
Run the offline tests with:
|
||||
|
||||
```text
|
||||
# Suíte completa canônica (1160+ testes: raiz + Hub + Agent):
|
||||
python -m pytest tests central/tests agent/tests -q
|
||||
|
||||
# Apenas testes unitários offline da raiz:
|
||||
python -m pytest tests -q
|
||||
```
|
||||
|
||||
|
||||
## Firebird write policy
|
||||
|
||||
Default policy:
|
||||
- All client/production Firebird databases are STRICTLY READ-ONLY.
|
||||
- Never perform INSERT, UPDATE, DELETE, DDL, permission changes, or destructive operations
|
||||
against any client/production ERP database unless explicitly authorized in a future policy change.
|
||||
|
||||
Explicit development exception:
|
||||
|
||||
The following database is a disposable TEST DATABASE and is explicitly authorized for writes:
|
||||
|
||||
```
|
||||
D:\PROJETOS\GTISISTEMAS\Projeto\TESTESOFICIAIS.FDB
|
||||
```
|
||||
|
||||
For this exact file only, the agent MAY perform:
|
||||
|
||||
- SELECT
|
||||
- INSERT
|
||||
- UPDATE
|
||||
- DELETE
|
||||
- DDL
|
||||
- transactional tests
|
||||
- rollback/recovery tests
|
||||
- destructive development experiments when necessary
|
||||
|
||||
This database has external intact backups and can be restored.
|
||||
|
||||
Safety requirement:
|
||||
|
||||
Before ANY Firebird write, the code must verify that the canonical absolute database path is exactly:
|
||||
|
||||
```
|
||||
D:\PROJETOS\GTISISTEMAS\Projeto\TESTESOFICIAIS.FDB
|
||||
```
|
||||
|
||||
If the path differs in any way, writes must fail closed.
|
||||
|
||||
Never infer write authorization from filename alone.
|
||||
Never enable writes to other Firebird databases.
|
||||
|
||||
Secrets:
|
||||
- credentials remain local in ignored environment files;
|
||||
- never log, commit, or expose passwords.
|
||||
|
||||
Development priority:
|
||||
- TESTESOFICIAIS.FDB may be modified freely as needed to validate the MVP.
|
||||
- Do not over-engineer rollback protections for this disposable test database unless they are part
|
||||
of the product behavior being validated.
|
||||
|
||||
## GTI Fiscal write-target rule
|
||||
|
||||
The SGV keeps its fiscal defaults in the canonical product record (`C000025`); every other routine consumes them.
|
||||
GTI Fiscal therefore writes ONLY to the canonical product record, and only fields whose mapping is proven
|
||||
(`docs/SGV_PRODUCT_FISCAL_UI_MAP_V1.json`, `write_target=true`). It never writes to NFCE, NFCE_ITENS, item tables,
|
||||
issued documents or any other transactional/historical table; those are read-only evidence for validation.
|
||||
Company context (UF, CRT) is read from `C000004` at run time — never hardcoded.
|
||||
|
||||
## Local completion mission — exact write allowlist (operator-authorized)
|
||||
|
||||
For the "GTI FISCAL LOCAL COMPLETION V1" mission the operator explicitly authorized writes to the disposable COPIES listed, by exact canonical path, in
|
||||
`docs/LOCAL_WRITE_ALLOWLIST_V1.json` (CONSTRUCAO, MMMODAS, RINCAO, UNIAO under `Projeto\Banco\`, plus TESTESOFICIAIS.FDB). Authorization is by exact
|
||||
path only — never by directory or `.FDB` extension. Any other Firebird under `D:\PROJETOS\GTISISTEMAS` stays strictly READ-ONLY. Writes go through the
|
||||
guarded executor (path allowlist, company-context guard, schema/type/length guard, compare-before-write, rowcount, transaction, audit) and only to
|
||||
`C000025` fields whose contract in `docs/FISCAL_FIELD_CONTRACT_V1.json` has `WRITE_ALLOWED=true`. This authorization does not extend to production or client databases.
|
||||
|
||||
## Production deploy rule (Hub)
|
||||
Normal deploy = `powershell -ExecutionPolicy Bypass -File .\scripts\deploy_hub.ps1 [-PublishAgent -Version X]` (docs/DEPLOY_HUB.md). Do not recreate ad-hoc deploy scripts (deploy115.py etc.) and do not improvise SSH/docker against 10.0.10.117. The script handles VPN/SSH retry, backup, upload, migrations, rebuild, health, release publish, download verification, and automatic rollback; the real error is in `logs/last_deploy_result.json` and the log.
|
||||
|
||||
## Versioning (adopted standard, see docs/VERSIONING.md)
|
||||
|
||||
Hub and Agent are versioned and released independently — never assume they share a version
|
||||
number, and never make the Hub's `GTI_FISCAL_VERSION` bump touch the Agent's own version files
|
||||
(`agent/pyproject.toml`, the `AGENT_VERSION` defaults) or vice versa. The panel's "Atualização
|
||||
disponível" already compares an Agent's reported version against the highest **PUBLISHED**
|
||||
Windows `AgentRelease`, never against the Hub's version — see `docs/VERSIONING.md` for the exact
|
||||
mechanism and the current (informal) compatibility matrix.
|
||||
|
||||
## Permanent mission rules (fiscal completion missions, recorded 2026-09-28)
|
||||
|
||||
- No AI/LLM/embeddings, no paid API, no scraping — every rule/decision is derived from real ERP
|
||||
evidence or an explicit, audited operator/ADMIN decision (`FiscalContextEntry`), never inferred
|
||||
or guessed.
|
||||
- No Firebird triggers or schema changes, ever, for any discovery/completion mission. All queries
|
||||
against any Firebird database (client, lab copy, or disposable test DB) are read-only unless the
|
||||
exact path is on an explicit, mission-scoped write allowlist (see above) — writes still go only
|
||||
through the guarded executor.
|
||||
- Deploy only via `scripts\deploy_hub.ps1` (see "Production deploy rule" above) — never ad-hoc
|
||||
SSH/docker/psql against 10.0.10.117.
|
||||
- If the Agent (agent/) changes in a way that affects its runtime behavior: bump the single-source
|
||||
version, build a new installer, validate it in a fresh Windows Sandbox (install, upgrade in-place,
|
||||
identity preserved), and never overwrite an already-published release. A pure version-label sync
|
||||
bump (release/VERSION, pyproject.toml files, the `AGENT_VERSION` default string) that changes no
|
||||
Agent behavior is not itself an "Agent change" requiring a new installer.
|
||||
- Never reenroll an existing installation (never mint a new `installation_id`/token for a machine
|
||||
that already has one) — an in-place upgrade always preserves identity and local SQLite state.
|
||||
- No remote-execution channel to any client's Agent host, ever (by design — see
|
||||
`docs/rtc_auto_apply.md`). An Agent version upgrade on a real client machine is always performed
|
||||
by a human operator on-site; the assistant never attempts RDP/WinRM/SSH/PowerShell-remoting into
|
||||
a client host, and never asks for or accepts a production `AGENT_TOKEN`/admin session credential
|
||||
pasted in chat to work around that — live validation of a real installation, when needed, comes
|
||||
from the operator (a panel screenshot, or a value they read and paste themselves).
|
||||
- No real client/production data (CNPJ, razão social, product names/descriptions, per-product NCM)
|
||||
is ever published in a location a non-admin can reach (e.g. `central/static/`). Any evidence
|
||||
artifact referenced from a UI card must either be served through an authenticated ADMIN-only
|
||||
route, or be anonymized (generic client labels, no names/documents/descriptions) before being
|
||||
published as a static file.
|
||||
Reference in New Issue
Block a user