Skip to content

feat(pipelinq): build clients-registry-numbers-and-enrichment - #3942

Open
rubenvdlinde wants to merge 12 commits into
developmentfrom
quality/build-clients-registry-numbers-and-enrichment
Open

rubenvdlinde wants to merge 12 commits into
developmentfrom
quality/build-clients-registry-numbers-and-enrichment

Conversation

@rubenvdlinde

@rubenvdlinde rubenvdlinde commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Builds openspec/changes/clients-registry-numbers-and-enrichment (REQ-CRN-001 to 003): official numbers on an organisation client, each checked against its register, and a bulk fill of empty company details from the KvK.

Tasks done

  • 1.1 register.d/19-client-identifiers.json: client.identifiers, a list of {scheme, value, checkStatus, checkedAt, checkSource, validUntil}. scheme is one of kvk, rsin, vat, duns and oin. The per-scheme patterns JSON schema can hold are declared with allOf/if/then on the items.
  • 1.2 en and nl titles for every new schema string. check:schema-l10n shows the same 13 uncovered strings as development and none of mine.
  • 2.1 ClientIdentifierService::validateFormat(): KvK 8 digits, RSIN 9 digits plus the eleven test, VAT an EU country prefix plus that country's VIES pattern, DUNS 9 digits, OIN 20 digits. ClientIdentifierFormatGuard runs it on every client create and update (ObjectCreatingEvent / ObjectUpdatingEvent) and refuses the write with the reason. So the form, the API, imports and bulk jobs are all held to it.
  • 2.2 checkKvk() asks OpenRegister's KvK leaf (/integrations/kvk/company?kvkNumber=). A found number is valid. A 404, or a 200 that lacks the number, is invalid. A 5xx or no answer is unavailable. To tell these apart, CompanyRegistryHttp::leafAnswer() returns the status code, where leafRows() folds every non-200 answer into "unusable".
  • 2.3 checkVat() resolves shillinq's ViesServiceInterface lazily. Without shillinq the result is unchecked with source shillinq not installed. A VIES outage is unavailable. A valid answer keeps its validUntil.
  • 2.4 POST /api/clients/{id}/identifiers/check with #[NoAdminRequired]. The controller first reads the client with the caller's rights (canAccessClient()) and answers 403 when they may not open it. The outcome is then written with the same rights. The route is documented in openapi.json. Hydra gates route-auth, no-admin-idor and route-reachability pass on the diff.
  • 3.1 ClientIdentifiersSection on ClientDetail (body widget client-identifiers). It lists scheme, number, status and check date. Add saves the list through OpenRegister and shows a refused number in the server's own words. Check appears on KvK and VAT numbers.
  • 4.1 FillFromKvkAction (pipelinq:fill-from-kvk, StepBulkActionInterface + ReversibleBulkActionInterface). It fills an organisation's empty place, legalForm and industry (the SBI descriptions, main activity first) and records the prior values for the undo. A member is skipped with one of these reasons: no KvK number, KvK unavailable, KvK number not found, already has these values, not an organisation. It is registered on BulkActionRegistrationEvent through FillFromKvkRegistrationListener, which sits in ListenerRegistrar (where pipelinq registers its listeners, rather than Application.php).
  • 4.2 Bulk action Fill in from KvK on the Clients list. BulkFillFromKvkModal follows the Change a field preview and confirm with the action id swapped, so the job is listed on Bulk changes and can be undone there.
  • 5.1 docs/Features/client-identifiers.md, listed in the feature index. The docs build exits 0.

Deviations, and why

  • address is not filled. On a client, address is the read-only mirror of the linked Nextcloud contact (15-unify-client-contact.json, readOnly: true), and OpenRegister refuses a change to a read-only property on update. The fill writes place (the place of establishment, from 20-organisation-registry-fields.json) instead, with legalForm and industry.
  • The fill takes the KvK identifier first and otherwise the client's existing kvkNumber field, so organisations that already carry a KvK number do not need it re-entered.
  • REQ-CRN-004 (a bulk fill of person fields) has no task in tasks.md, and the proposal puts person enrichment out of scope. It is not built.

Tasks left

  • None of the code tasks. Left unchecked: the Playwright verifications named under 3.1 and 4.2 (tests/e2e/client-identifiers.spec.ts, and the fill plus undo on Bulk changes), and the register import on a dev instance (1.1). All three need a running instance.

Tests

  • New PHPUnit tests: ClientIdentifierServiceTest (16), ClientIdentifierFormatGuardTest (4), ClientIdentifierControllerTest (4), FillFromKvkActionTest (8). They use OpenRegister stubs for BulkStep, BulkActionResult, BulkActionRegistrationEvent and the bulk action interfaces, under tests/Stubs.
  • New vitest specs: clientIdentifiersSection.spec.js (9) and bulkFillFromKvkModal.spec.js (4).
  • PHP unit suite: development 9280 OK; this branch 9311 OK.
  • vitest: the same 3 files fail on development and on this branch (reportSectionPeriod, myWorkPage, notificationLabels). There are no new failures.
  • phpcs and phpstan are clean on the changed lib files. npm run lint is clean on the touched files. check:l10n, check:l10n-js and check:manifest pass.
  • Hydra gates on the diff: the findings left are inherited (or-abstraction, openregister-dependency-shape, procedure-code, manifest copy style and l10n on existing pages). One more is a config read without a fail-mode guard in OrganisationEnrichmentService::config(), on lines this PR did not change (only its LEGAL_FORMS became public). The gates for the manifest schema, connections and ajv could not load their vendored files in this session and did not run.

Generated by Claude Code

Task 1: client.identifiers, a list of scheme, value and the status, time
and source of its last register check, with the per-scheme patterns JSON
schema can hold; en and nl titles.

Assisted-by: ClaudeCode:claude-opus-5-5
Tasks 2.1 to 2.3: ClientIdentifierService validates each scheme's format
(the RSIN eleven test and the EU VAT country patterns included) on every
client save through ClientIdentifierFormatGuard, checks a KvK number through
OpenRegister's KvK leaf (valid, invalid, unavailable on a 5xx or no answer)
and a VAT number through shillinq's VIES service when shillinq is there.

Assisted-by: ClaudeCode:claude-opus-5-5
Task 2.4: POST /api/clients/{id}/identifiers/check, #[NoAdminRequired],
refusing a client the caller may not open (a read with their rights) before
anything is looked up; the outcome is written with the same rights.
Documented in openapi.json. Hydra gates route-auth, no-admin-idor and
route-reachability pass on the diff.

Assisted-by: ClaudeCode:claude-opus-5-5
Split the VIES availability test over two conditions (line length).

Assisted-by: ClaudeCode:claude-opus-5-5
Task 4.1: FillFromKvkAction (pipelinq:fill-from-kvk), a reversible
OpenRegister bulk action that fills an organisation's empty place, legal
form and industry from the KvK, skipping with the reasons no KvK number,
KvK unavailable, not found and already filled, and recording the prior
values for the undo. Registered on BulkActionRegistrationEvent. Stubs for
BulkStep, BulkActionResult and the registration event for the unit suite.

Assisted-by: ClaudeCode:claude-opus-5-5
Task 3.1: the Identifiers section on ClientDetail lists each official
number with the status, date and source of its last check, adds a number
by saving the list through OpenRegister (a refused number is shown as the
server words it) and checks a KvK or VAT number through the new route.
en and nl strings.

Assisted-by: ClaudeCode:claude-opus-5-5
Sort the new registry import.

Assisted-by: ClaudeCode:claude-opus-5-5
Task 4.2: Fill in from KvK on the Clients list, a previewed OpenRegister
job of pipelinq:fill-from-kvk with the Change a field preview and confirm;
the job appears on Bulk changes and can be undone there. en and nl.

Assisted-by: ClaudeCode:claude-opus-5-5
The KvK-to-client mapping (place, legal form, SBI descriptions) moves into
ClientIdentifierService::kvkFacts() behind the interface, the bulk action
reads only the interface, and its registration listener sits beside it, so
no service gains a caller outside lib/Service (component independence back
above its floor). @SPEC on the section's watcher; stubs carry no anchors to
openregister's own specs.

Assisted-by: ClaudeCode:claude-opus-5-5
Task 5.1: docs/Features/client-identifiers.md, the schemes, what Check
does, what Fill in from KvK fills and what it never overwrites; listed in
the feature index. Docs build exits 0.

Assisted-by: ClaudeCode:claude-opus-5-5
…ichment [skip ci]

l10n: union of both sides' keys, .js rebuilt from the .json catalogues.

Assisted-by: ClaudeCode:claude-opus-5-5
…skip ci]

store() takes the client data and its save options and returns only a refusal;
readClient() takes the register and schema as one location; indexOf() takes
the wanted scheme and number as one pair. Same reads, writes and answers.

Assisted-by: ClaudeCode:claude-opus-5-5

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant