Skip to content

refactor: rename the profiling vocabulary for the RD deployment - #611

Open
mrivas00 wants to merge 4 commits into
feat/mati/rd-deployment-identityfrom
feat/mati/rd-terminology
Open

refactor: rename the profiling vocabulary for the RD deployment#611
mrivas00 wants to merge 4 commits into
feat/mati/rd-deployment-identityfrom
feat/mati/rd-terminology

Conversation

@mrivas00

@mrivas00 mrivas00 commented Aug 21, 2026

Copy link
Copy Markdown
Collaborator

Why

Two of MMARN's ten observations are about words. The platform calls step 1 Perfilamiento and the economic-activity catalog rubro / subrubro — neither term is used in Dominican regulation, and page 5 of the observations asks explicitly to replace rubro with Actividad económica. A third rename is forced by what comes next: the field labelled Actividad principal de la organización actually holds intensity denominators (toneladas producidas, MWh generados), so it would collide head-on with the primary/secondary economic-activity fields PR 7 adds to the same form.

PR 2 of 8 · base feat/mati/rd-deployment-identity (PR 1).

What

Before After
Perfilamiento (step 1, sidebar group) Datos generales
rubro / Rubros sector / Sectores
subrubro / Subrubros actividad económica / Actividades económicas
actividad principal unidad de actividad
RUT / RUC / ID Tributario, RUT RNC (Registro Nacional de Contribuyentes), RNC
ID representante / Rut, ID/Rut the document label, and TAX_ID_LABEL
76123456-7, 12345678-9 (Chilean RUT examples) 131-2345678-9 / 001-1234567-8 (Dominican XXX-XXXXXXX-X)
Acme SpA, Acme Chile Acme SRL, Acme RD

Routes, table names, Prisma models and API contracts are untouched — this is copy: 60 files across screens, maintainers, charts, transparency, the Excel export, API error messages, the ten inline explanation markdowns and two dev docs.

Review notes

The gender problem is the only real logic here. Two of the four catalog subjects are now feminine (actividad económica, unidad de actividad) where all four used to be masculine bar one. Copy that hardcoded masculine agreement now derives it:

  • DeleteWarningDialog keeps an ENTITY_GENDER map beside the label union and derives the demonstrative (este/esta), the participle (asignado/asignada) and the pronoun (eliminarlo/eliminarla).
  • getApiErrorMessage replaces activeAdjective with a gender field on RESOURCE_LABELS, which drives the adjective (activo/activa), the parent participle (eliminado/eliminada), the restore imperative (Restáuralo/Restáurala) and the direct-object pronoun used across the re-parenting copy. The fallback subject is still el registro, so unknown resource types keep masculine agreement.

getApiErrorMessage.test.ts was already exercising the agreement paths, so the updated expectations are the best place to check the wording reads correctly in Spanish.

The tax-id examples were Chilean. Every worked example of a tax identifier
in the repo was a RUT, which the RNC labels here turned into a contradiction —
assertions that read RNC 76123456-7. Organizations now use 131-2345678-9 and
representatives 001-1234567-8, both in the Dominican XXX-XXXXXXX-X shape,
across the collision fixtures, the .rest request samples, the trimming test and
three docs. The cross-format illustrations keep their point: the same identifier
written two ways, 131-2345678-9 against 13123456789. The same fixtures also
carried Chilean company forms (Acme SpA, Acme Chile), now Acme SRL and
Acme RD, and one test name still called the field a RUT.

No validation was added: taxId stays a generic string, with no RNC format
check, no verifier digit and no normalization — the comment in
organizationIdentityCollision.ts still says so, and it is still true.

Why the renames are one commit. They share files and a partial rename does not compile — the ProfilingEntityLabel union has to match its four call sites. The RNC labels are a separate commit.

One rename is a judgement call: actividad principalunidad de actividad.

The field is OrganizationMainActivity, and its values are intensity
denominators — m² construidos, millones de RD$ de ingresos, MWh generados,
pasajeros-km — the unit the footprint is divided by to express intensity. Its
old label named an activity, which is a different thing. Left alone, the form in
PR 7 would have shown these two fields next to each other:

Label What it actually holds
Actividad económica principal the national classifier row the organization declares to the DGII
Actividad principal de la organización m² construidos

The new label follows the sidebar entry Unidades de Actividad, and the field's
explanation markdown now states what it measures instead of describing it as "the
most specific descriptor of what an organization does".

This is a label change only: the table, the Prisma model and the mainActivityId
field of the API contract are all unchanged, so no data and no request shape
moves. It lands here rather than in PR 7 because PR 7 edits the same form file —
renaming afterwards would mean touching it twice, and reviewing the new
economic-activity fields against the colliding label.

Verification

pnpm format && pnpm lint && pnpm type-check && pnpm test:web all green, and the full API suite is green too (2,304 passing).

The rename broke two integration tests, and this now fixes them. getMainActivityEquivalence and getEmissionsDetailedSummary fall back to a literal when an organization's mainActivityId resolves to nothing, and that literal moves from actividad principal to unidad de actividad along with the rest of the vocabulary. Two tests asserted the old wording. They were never run — no database was available while the stack was authored — so the failure only surfaced once one was. Both assertions follow the rename, in the same commit that makes it.

grep -rni 'rubro\|subrubro\|perfilamiento' over apps/, packages/ and tools/seed/src/data/base/explanations/ returns nothing, and so does a sweep for the Chilean tax-id formats (76123456-7, 12345678-9, 76.123.456-7).

Known gap: the user manual (user_manual/**, .claude/user-manual-plugin/data/**) still says Rubro. Its slides embed screenshots of the old sidebar, so text-only edits would contradict the images — it needs a screenshot pass against a running RD environment and is left out of this stack deliberately.

@mrivas00 mrivas00 added priority: high High priority type: refactor internal restructure, no behaviour change area: web apps/web (React frontend) area: api apps/api (Fastify backend) labels Aug 21, 2026
@mrivas00

mrivas00 commented Aug 24, 2026

Copy link
Copy Markdown
Collaborator Author

Why rubro became Sector and not Actividad económica principal. Page 5 of the observations asks to drop the word rubro, but page 1 of the same document names the three fields it wants — "un catálogo nacional oficial con sector, actividad económica principal y actividad económica secundaria" — so sector is MMARN's own term for the top level, and the platform's two catalog levels map onto it directly: CountrySector (the classifier's top level) becomes the Sector, and CountrySubsector (its second level) becomes the Actividad económica an organization actually declares, which the form labels Actividad económica principal — with secundaria added by PR 7 as a second selection from that same level, not a third one. Naming the top level Actividad económica principal instead would leave the finer level with no name available, leave page 1's sector field with nothing to attach to, and invert the classifier's own hierarchy, where the top level is the sector and the level below it is the activity. One caveat on the paper trail: proposal.md and task 3.3 still read "Replace rubro / subrubro with Actividad económica principal / secundaria", which predates decision 1 of design.md — primary and secondary are two selections from one level, not two levels — and so describes something this PR deliberately did not do; the design and the profiling-maintainer spec both match what shipped.

@mrivas00
mrivas00 force-pushed the feat/mati/rd-terminology branch from b0887b8 to 8821621 Compare August 24, 2026 15:10
@mrivas00
mrivas00 force-pushed the feat/mati/rd-deployment-identity branch from 24be92e to 054bd47 Compare August 24, 2026 15:10
@mrivas00
mrivas00 force-pushed the feat/mati/rd-terminology branch from 8821621 to a02887a Compare August 24, 2026 17:58
@mrivas00
mrivas00 force-pushed the feat/mati/rd-deployment-identity branch 2 times, most recently from 04338e9 to 873c157 Compare August 26, 2026 12:12
@mrivas00
mrivas00 force-pushed the feat/mati/rd-terminology branch 2 times, most recently from 781cc21 to 23ce2b3 Compare August 26, 2026 12:36
MMARN asked for "actividad económica" instead of "rubro" and for step 1
to stop being called "Perfilamiento". The three renames land together
because they share files and a partial rename would not compile: the
DeleteWarningDialog union has to match its call sites.

- Perfilamiento → Datos generales (step 1 and the maintainer sidebar
  group).
- rubro / subrubro → sector / actividad económica across screens,
  maintainers, charts, transparency, the Excel export, the API error
  copy and the inline explanations.
- Actividad principal → unidad de actividad. The field holds intensity
  denominators (toneladas producidas, MWh generados), so its old name
  collided with the economic-activity fields the RD registration form is
  about to gain. Its explanation now says what it actually measures.
- The representative identifier drops the Chilean "Rut" literal and
  names the document instead.

Two of the four subjects are now feminine ("actividad económica",
"unidad de actividad"), so the copy that used to hardcode masculine
agreement derives it: DeleteWarningDialog keeps a gender per entity
label, and getApiErrorMessage replaces `activeAdjective` with a `gender`
field that drives the adjective, the participle and the direct-object
pronoun.

Routes, table names and API contracts are untouched — this is copy.
The deployment is Dominican, so `OrganizationData.taxId` is an RNC. Sets
TAX_ID_LABEL / TAX_ID_LABEL_SHORT accordingly and routes the applicant
section through the constant instead of its hardcoded "ID/Rut", which
bypassed it.
Every worked example of a tax identifier was a Chilean RUT (`76123456-7`,
`12345678-9`), which the RNC labels this PR introduces turned into a
contradiction: assertions now read `RNC 76123456-7`.

Organizations get `131-2345678-9` and representatives `001-1234567-8`, both in
the Dominican XXX-XXXXXXX-X shape. The cross-format illustrations keep their
point — the same identifier written two ways, `131-2345678-9` against
`13123456789`.

Also drops the Chilean company forms the same fixtures carried: `Acme SpA`
becomes `Acme SRL`, `Acme Chile` becomes `Acme RD`, and one test name still
called the field a RUT.
@mrivas00
mrivas00 force-pushed the feat/mati/rd-deployment-identity branch from 873c157 to 239b843 Compare August 26, 2026 20:21
@mrivas00
mrivas00 force-pushed the feat/mati/rd-terminology branch from 23ce2b3 to 56e56e4 Compare August 26, 2026 20:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: api apps/api (Fastify backend) area: web apps/web (React frontend) priority: high High priority type: refactor internal restructure, no behaviour change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant