019fb836 DfxApproval-GSheets durch API-Workflow ersetzen

[TaprootFreak]

Purpose

Replaces the eight minute-interval personal DfxApproval GSheets with a fail-closed API workflow.
Context: DFXswiss/gsheet#9.

Sheets replaced

1. DfxApproval approval
2. DfxApproval risk flags
3. GwGFileCover
4. IdentificationForm
5. CustomerProfile
6. RiskProfile
7. FormA
8. DfxNameCheck

IdentReport and PersonalNameCheck stay in their existing KYC processes and remain part of the
approval gate. Organizations are not part of this personal migration.

Implementation

• minute-interval API cron with PostgreSQL advisory locks and an atomic approval
• separate candidate sets matching the productive Sheet queries (DfxApproval, FinancialData and
  personal accounts on level 30-40)
• the same country, risk, status, ident and document conditions as the productive Apps Scripts
• six PDF generators on unchanged exports of the productive Google Sheet templates, rendered with an
  embedded Unicode font
• exact file names, page counts, dynamic fields and checkbox logic
• idempotent WORM storage under a unique generationKey
• every document has exactly one generation path and one lock key: GwGFileCover, IdentificationForm
  and DfxNameCheck under the DfxApproval step lock, CustomerProfile under the FinancialData step
  lock, RiskProfile and FormA under the user-data lock
• per-document error isolation: one failing PDF does not block the independent documents
• default-off cutover switch and a separate process kill switch
• no change and no new dependency in DFXswiss/services

Corrections after review

Two loads could not work against a real database, and the mocked tests hid both. Every correction
below was reproduced and then re-verified against a real PostgreSQL 16 with the driver version this
repository pins.

• Approval never completed. The completion loaded the step without its user data relation.
  KycStep.userData is a ManyToOne without eager loading, so it stayed undefined and reading its
  ID threw for every case - caught by the cron and only logged. The step is now loaded through a
  query builder that joins the user data and locks the step alone.
• Risk data was never initialised. Locking user data through a plain find joins the eager,
  nullable relations of UserData, and PostgreSQL rejects FOR UPDATE on the nullable side of an
  outer join. It now locks through a query builder without those joins. Both lock aliases are lower
  case on purpose: the driver emits FOR UPDATE OF <alias> unquoted, so a camelCase alias is not
  found in the FROM clause.
• Documents failed for non-Latin-1 names. The overlay text used a PDF standard font, which is
  limited to WinAnsi and throws on Polish, Turkish, Baltic, Czech or Cyrillic characters - the case
  then waits forever without its evidence. The text is now set in an embedded Liberation Sans
  (metrically compatible with Arial/Helvetica, about 9 kB embedded per document); characters without
  a glyph are substituted instead of failing the document.
• RiskProfile and FormA skipped accounts. Both documents follow the account, not a KYC step, but
  the workflow required a DfxApproval or FinancialData step as an anchor. Measured against
  production, 82 of 355 current candidates have neither. They are now generated from user data alone.
• Missing NameCheck data blocked the whole case. The check ran before the loop, so a case without
  NameCheck evidence also lost its GwGFileCover and IdentificationForm. It now fails only the
  NameCheck document.
• Risk flags could be written during an open sanctions review. The batch that initialises empty
  risk fields assumed no name check was open. A new sanctioned hit does not refresh
  lastNameCheckDate - that only happens on a clean result - so the date was no proof. The flag is
  now queried per account.
• The same document could be written from two lock keys. CustomerProfile, RiskProfile and FormA
  were reachable from two entry points with different advisory-lock keys, so two instances could
  render and upload the same document concurrently, each with its own embedded document number. Each
  document now has a single path.
• The approval audit entry was incomplete. It recorded step status, KYC level and KYC status,
  while the same transaction also overwrites complexOrgStructure, highRisk, depositLimit and
  amlAccountType. A limit set by Compliance was therefore not recoverable from the database. All
  four previous values are now part of the entry, written before the columns change.

Smaller corrections: gate blockers are logged instead of discarded, so a waiting case is
distinguishable from one nobody looked at; the excluded account IDs moved from the source tree into
the dfxApprovalDocumentExclusions setting; the storage reuse path lists the key instead of
downloading the whole document and fails loudly when a document marked valid is gone; a regenerated
document keeps the file name of the first attempt, which is also printed into it as its document
number; values that do not fit their field are logged instead of being cut silently; the level log
keeps the wording of the existing approval path; the new cron job is in docs/cron-jobs.md; the
index name, import order and log helpers follow the repository conventions.

Cutover

The cron stays off after the deployment. Fill dfxApprovalDocumentExclusions with the productive
legacy exceptions, disable and verify all eight Apps Script triggers, then set
KYC_DFX_APPROVAL_WORKFLOW_ENABLED=true. Rollback and operational checks are in
docs/dfx-approval-migration.md.

Verification

• 147 tests in 10 suites for the KYC subdomain, including regression tests for each correction above
• SHA-256 golden tests for all six productive PDF templates
• both corrected loads executed against a real PostgreSQL 16; the previous versions fail there with
  TypeError and FOR UPDATE cannot be applied to the nullable side of an outer join
• npm run lint, npx nest build, and the built dist verified to contain the templates and fonts

Open questions for the operator

1. On approval, depositLimit is set to 100000 unconditionally, overwriting a different existing
   value. Is that the intended Sheet behaviour, or should an existing limit be preserved? The
   previous value is now recorded in kyc_log either way.
2. The gate requires a valid RiskProfile for every case, while the document is only generated for a
   FATF-enabled country of residence - the same combination the Sheet process had. An account outside
   such a country therefore stays with Compliance instead of being approved automatically. No country
   in the seed data has fatfEnable = false; a test pins the coupling so both sides can only be
   changed together. Leave as is, or make the requirement conditional?
3. The audit package documents the selection rules of the six document sheets from their layout tabs;
   the SQL header holding the where cell is not part of it, and six of the eight scripts could not
   be exported. The candidate sets should be compared against one live sheet before the cutover.
4. The sample PDFs in the audit package were rendered with the previous standard font and should be
   regenerated after this change.

[TaprootFreak]

Verification state after the review corrections:

• 144 tests in 10 suites for the KYC subdomain locally, all 13 GitHub checks green
• both corrected loads executed against a real PostgreSQL 16 with the pinned driver version: the
  previous versions fail there with TypeError: Cannot read properties of undefined (reading 'id')
  and FOR UPDATE cannot be applied to the nullable side of an outer join, the new ones return the
  locked rows
• the lock alias case is covered by a test: the driver emits FOR UPDATE OF <alias> unquoted, and a
  camelCase alias fails with relation "kycstep" in FOR UPDATE clause not found in FROM clause
• PDF rendering exercised with Polish, Turkish, Cyrillic and Baltic names plus a CJK substitution case
• npx nest build verified to place both the templates and the fonts into dist
• candidate counts measured against production: 355 accounts in scope for RiskProfile/FormA, 82 of
  them without any DfxApproval or FinancialData step

Three points in the PR description need an operator decision before the cutover.

[TaprootFreak]

Five review passes were needed before two independent reviews came back with no findings.

What the passes changed, beyond the corrections already listed in the description:

• Pass 1 — risk flags could be written while a sanctions review was still open; the same document
  could be generated from two different advisory-lock keys; the approval audit entry did not record
  the previous values of the four compliance columns the same transaction overwrites; the new cron
  job was missing from the job inventory; the unique index carried a hand-written name.
• Pass 2 — CustomerProfile turned out to have the same two-lock-key gap that RiskProfile and
  FormA had. Every generated document now has exactly one generation path and one lock key.
• Passes 3-4 — import order across the touched files.
• Pass 5 — no findings from either review.

Two reported points were deliberately not applied, with the reasoning recorded in the pull request:
moving the approval gate onto the entity (it aggregates state from a separate query and the document
matrix of this workflow, which entity getters here deliberately do not carry), and making the
RiskProfile requirement conditional on the country (that would loosen a compliance gate and is an
operator decision, not a review correction - a test now pins the coupling instead).