Francisco Ignácio Fontoura Solla 812e3a0bee B34: editable município chips on the leaderships list.

The "Municípios" column was dead text; it is now chips that navigate to the
município, with a territory chip when a leadership covers a whole TI, and it is
editable in place. What picks inline vs. Drawer is the `pointer:` media query,
not viewport width: on a fine pointer the editor is always mounted (the "×" sits
at the chip's corner, revealed on hover/focus) and on a coarse pointer a tap
anywhere in the cell opens a Drawer with 44 px targets.

`AdvisorMunicipalityCell` is promoted to `shared/MunicipalityPortfolioCell` and
/campanha/assessores migrates onto it in the same change, so the second call site
is born with the first. One batch action only; the single-id advisor twin is
deleted with its int tests migrated. The anti-goal on always-mounted list inputs
is amended for chip-based relations on fine pointers, not reopened.

Also fixes a latent bug: `CampaignTableHead`'s `description` seam broke any RSC
caller, because its two helpers lived in a 'use client' module.

2026-07-27 22:35:19 -03:00

50 KiB

Raw Blame History

Tech Debt

Ledger of known engineering debt. Items large enough to be scheduled work become entries in roadmap.md (linked in the Ref column); this file tracks the full inventory so nothing is lost. Sourced initially from the 2026-07-23 engineering-standards audits.

Debt Ledger

Item	Location	Type	Risk	Effort	Priority	Status	Ref
164 unused exports + 60 unused types reported by knip (warn-level; 158 at Pass 1)	god modules, ui kit families	dead code	low	M	P2	closed 2026-07-25 (Pass 2 W4b): 0 findings; `exports`/`types`/`enumMembers` at error in CI; tests entered the knip graph; `duplicates` off (only hits were the 6 deliberate access aliases `canUpdateX = canReadX`)	Pass 2 W4b
knip loader noise: `Error loading src/payload.config.ts` (server-only guard)	knip run output	tooling noise	none (exit 0, static graph resolves)	S	P3	open
Aikido scan unusable: `aikido_full_scan` answers Opengrep exit code 2 for any input, including a one-line probe file, so the per-change security scan the rules mandate cannot complete. What it reported is an artifact of the failed run, not attributable to the code under review; the Aikido feed lists nothing for this repo. The `shpjs` devDependency added by B8 F2 is therefore SCA-unverified	Aikido MCP / local scanner	tooling outage (security gate)	medium — the gate is skipped, not passed	S	P2	recovered 2026-07-27 (B34): `aikido_full_scan` completed with 0 findings on the changed files; only taint analysis timed out. The outage was transient, so treat this row as a watch item — if exit 2 returns, the SCA gap (incl. `shpjs`) reopens
Missing-consent window fixture releases its exclusive lease during the observation window — readers can interleave (rare flake). Full fix: session-level advisory lock spanning delete→op→restore + updated fault-path pins	`tests/helpers/testDatabaseLease.ts` (`withMissingInviteConsentFixture`)	test-infra race	low (ms-wide window; shared leases added 2026-07-23 narrow it)	M	P2	open
`users` collection has no roles (all admins omnipotent)	`src/collections/Users.ts`	RBAC	medium (small trusted admin set)	M (schema migration)	P1 before widening `/admin`	closed 2026-07-27 (`admin`\|`editor`; migration `20260727_032523_add_users_roles`; roles-admin-payload.md)	AGENTS Known Gaps #1
Any campaign user can enumerate staff names/roles (`canReadCampaignUsers`)	`src/utilities/access/campaignUsers.ts`	info disclosure	low	S	P2	open
`removeSupporterData` deletes via `overrideAccess: true` while `canDeleteSupporter` is admin-only	`src/app/(campaign)/campanha/actions/supporter.ts`	access asymmetry (likely intentional LGPD path)	low	S	P3	open — document or align
Legacy public consent flows hardcode document IDs (`consent: 2`)	`src/app/(frontend)/actions/submitWhatsapp.ts`	correctness	medium	S	P1	closed 2026-07-25 (Pass 2 D3): resolves `Consent.key = 'whatsapp-inscricao'` fail-closed; migration `20260725_170000` tags the live doc (id 2, key vazio) com a chave	AGENTS Known Gaps #2
E2E suite thin (7 specs; most campaign CRUD int-only)	`tests/e2e/`	coverage	medium	L	P2	open
CI runs on GitHub mirror only (no Codeberg/Woodpecker pipeline)	`.github/workflows/ci.yml`	process	low	M	P3	open
E2E campaign journeys flake with 2 workers — root cause narrowed 2026-07-26 (B13), and it is not only latency: (a) `campaignMunicipalities`/`campaign-pwa` click the leader consent checkbox before hydration attaches the handler, and (b) the municipality fixture picks names by regex, so "Conde" also matches "Condeúba". Reproduced on a clean `main` tree, so it is not a B13 regression; both specs pass in isolation	`tests/e2e/campaignMunicipalities.e2e.spec.ts`, `tests/e2e/campaign-pwa.e2e.spec.ts`	test-infra	medium (masks real failures in the delivery gate)	S	P2	open — wait for an interactive-state signal instead of the element existing, and anchor fixture lookups to exact names/slugs instead of substring regex
Two e2e tests fail deterministically at one worker on a clean `main` tree (measured 2026-07-27 by stashing the whole B34 delivery and re-running): `campaignNearestMunicipality` "coordinator in Salvador is sent to the zone list" cannot find the `Salvador — ZE 1` link on `?q=Salvador`, and `campaignMunicipalities` "advisor opens a demand and decides it" cannot find its demand heading. These are not the 2-worker flake in the row above — retrying and lowering concurrency do not help — so the gate currently ships with two red specs whose failure nobody has diagnosed	`tests/e2e/campaignNearestMunicipality.e2e.spec.ts:156`, `tests/e2e/campaignMunicipalities.e2e.spec.ts:394`	broken test (or real regression)	high — a permanently red gate trains everyone to ignore it, which is how a real failure ships	S	P1	open 2026-07-27 (B34 `/simplify`) — start from the saved `test-results/**/error-context.md`: the Salvador list renders (zones ZE 5/9/10–15 are in the snapshot) but the assertion's exact accessible name is absent, so suspect the E9 `deficit` default sort plus pagination rather than the card
Post listing cache holds all published posts, filters in memory	`src/utilities/posts.ts`	scale (fine at ~tens of posts)	low	M	P3	open — watch corpus growth
Petition `generateStaticParams` uses uncached `getDocuments` without `select`/`depth: 0`	`src/utilities/documents.ts` consumers	over-fetch (build-time)	low	S	P2	closed 2026-07-23 (Phase 2: `getPetitionIds` with `depth: 0` + empty `select`)
Compare mode (`?compare=`) still queries per candidate uncached cross-request	`src/utilities/municipalityMapData.ts`	perf	low	M	P3	open — React `cache()` dedups in-request; add `unstable_cache` if profiling warrants
Map bundle serializes all years × scenarios (~100KB raw), +63.6 KB after B13 (`competitiveRankByYear` is ~57 KB of it: three years × 417 codes × `{rank, candidates}`, paid on every dashboard load even by the coordinator who never opens the "posição no município" scale)	`municipalityMapContract.ts` consumers	payload size	low — gzip crushes repeating keys to ~10KB on the wire; instant year/scale switching is a core analysis flow worth the bytes	M	P3	the 2026-07-23 deferral asked for profiling before acting; B13 supplied the number, so the trim is now scheduled as B13+ F4 (roadmap fill-in)	B13+ F4
Props→state `useEffect` mirrors in list controls/comboboxes	`MunicipalityListExpectedVotesControl`, `AsyncSearchCombobox`, `StrictCombobox`	pattern	none — reviewed 2026-07-23: guarded-equality sync is the correct "server echo vs local draft" reconciliation (A10 pattern), not derived state	—	—	closed (accepted as correct)
User-visible "Praça" copy survived the M1 rename (map panel title "Mapa das Praças", admin field descriptions, provisional Onda 0 consent texts, `SupportStatusBadge` summary, fallback/error strings, code comments)	`rg -n 'Praça' src` (~96 hits in 53 files, ~55 user-visible — 2026-07-25 audit)	copy drift	low (cosmetic; consent texts are provisional Onda 0 copies)	S	P2	open — scheduled Pass 2 W4f (consent texts stay for the legal batch)	Pass 2 W4f
Access checks re-read the actor per Local API call: `getFreshCampaignUser` caches in `req.context`, but a `payload.find({ user, overrideAccess: false })` that passes no `req` gets a fresh context, so one `/campanha/municipios` render issues ~5 identical `campaignUser` reads on top of the layout's own pair	`src/utilities/access/shared.ts` + every `overrideAccess: false` caller	perf (round-trip fan-out)	low since the `gru1` move (~2 ms each; it was ~120 ms each while functions ran in `iad1`)	M	P2	open — measured 2026-07-26. A React `cache()` layer would dedupe across requests, but it changes actor freshness inside server actions that mutate roles (`reloadUnrestrictedActor`), so it needs its own delivery with pins
`authenticateCampaignToken` reads the actor twice: Payload's JWT strategy already fetches the user document, then `findByID(depth: 1)` re-reads it — the second read's only unique contribution is populating `avatar` for the sidebar	`src/utilities/campaignAuth.ts`	perf (a round trip in the layout, so on every page)	low	S	P2	open — dropping it needs the avatar resolved another way, plus pins on `removePrivateAuthFields` and on role-downgrade freshness	RS+
`LeadershipStateDeputyRelationCell` (B31) keeps its own Popover, its own `ResizeObserver` collapse math and a 16 px "Ver mais…", while the sibling column in the same table now uses the shared `MunicipalityPortfolioCell` (always-mounted on `pointer-fine`, Drawer on `pointer-coarse`, 24 px targets, ARIA combobox). Two chip editors, one table, different keyboard and touch contracts	`src/components/campaign/leadership/LeadershipStateDeputyRelationCell.tsx` vs `src/components/campaign/shared/MunicipalityPortfolioCell.tsx`	duplication + a11y drift	low functionally, medium for consistency — the dobradinha chips are the only ones in the table a thumb cannot edit safely	M	P2	open 2026-07-27 (B34), trigger fired — the reuse review measured ~105 line-for-line duplicated lines of `ResizeObserver` collapse math between the two cells (constants, the first-callback guard, the `lastVisibleTop + 1` filter, the trailing-width loop, the `expandToggle`), including one verbatim comment. Scheduled as B34+ F2 (`useChipRowOverflow`); the duplication predates B34 (it was born between `AdvisorMunicipalityCell` and B31), which is why it is an extraction and not a regression. B37 still does not by itself justify a generic abstraction — it plugs the shared cell into a third relation	B34
B34 shipped a measured First Load JS regression: `/campanha/liderancas` 246 → 304 kB and `/campanha/assessores` 253 → 295 kB (Next's minified figure, two full builds against a stashed clean `main`). Assessores already imported the static Bahia catalog, so its +42 kB is the cell (Drawer, links, combobox contract, measuring machinery) and only the remaining ~16 kB on lideranças is the catalog reaching a route that lacked it — the same cost B14 already named. The two fixes oppose each other: pulling the catalog out of the browser fattens the payload of every chip toggle, shrinking the payload to `{id,slug}` keeps the bundle	`src/lib/municipalityPortfolio.ts`, `src/utilities/municipalityPortfolioIndex.ts`, `src/components/campaign/shared/MunicipalityPortfolioCell.tsx`	perf (bundle + per-render payload)	medium — two of the most-used staff lists, on phones over 4G	M	P2	open 2026-07-27 (B34) — direction recommended in the fill-in (payload-minimal, since staff edit far more than they navigate), but it trades the DB's `region` for the snapshot-tested catalog's, so it needs an explicit call. A third, orthogonal lever: load the Drawer behind `next/dynamic` on first touch — it only opens on `pointer-coarse`	B34+
`AdvisorsTable` mixes an edit mode (name/e-mail/phone behind an "Editar nome e contato" toggle) with a column that is always live (municípios). The toggle survives because those are text fields with no chip readout, but the row now speaks two interaction grammars at once	`src/components/campaign/advisor/AdvisorsTable.tsx`	UX inconsistency	low	M	P3	open 2026-07-27 (B34) — resolve by giving the text fields the same edit-in-place treatment, not by re-hiding the chips	B34

Smell Inventory

Smell	Location	Refactoring	Status
God module: RBAC for every collection in one file (964 lines, ~80 exports)	`src/utilities/campaignAccess.ts`	split per domain under `src/utilities/access/`	done 2026-07-23 (14 domain modules; `campaignAccess.ts` kept as re-export surface)
God module: ~71 exports of electoral math	`src/lib/electionInsights.ts`	split by concern when next touched	done 2026-07-25 (Pass 2 W4a): module DELETED; survivors in `electionFormat.ts` + `voteTrend.ts`
Multi-feature action bag: CRUD + CSV import pipeline + LGPD in one file (722 lines)	`src/app/(campaign)/campanha/actions/supporter.ts`	split CRUD vs import	done 2026-07-23 (`supporterImport.ts`)
Clone twins: create/update/staff-assert/unique-conflict skeleton	`actions/organization.ts` ↔ `actions/stateDeputy.ts`	extract shared factory	done 2026-07-23 (`runStaffEntityMutation` in `campaignEntityActions.ts`)
14 near-identical `formActions.ts` try/catch→mapError→redirect/return ladders	`src/app/(campaign)/campanha/**/formActions.ts`	shared form-action wrapper	done 2026-07-25 (Pass 2 W4d): `runCampaignFormAction` + 13 ações migradas; exceções documentadas (atividades/formActions, apoiadores/[id], convite login). C8 F4b ✓ 2026-07-27: guard ampliado para `*FormActions.ts` + `taskActions.ts`; 6 irmãos migrados; `taskActions.ts` allowlisted — futuros siblings não driftam silenciosamente
Flat 80+-file `src/utilities/` junk drawer; `lib/` vs `utilities/` boundary undocumented	`src/utilities/`, `src/lib/`	document convention + move misfiled modules	done 2026-07-23 (convention in `.cursor/rules/engineering-standards.mdc`; `RefreshRouteOnSave` moved to `components/`)
Praça→Município rename leftovers in identifiers (`PLAZA_MAP_YEARS`, `ACCESSIBLE_PLAZA_IDS_CONTEXT_KEY`, …)	map/list utilities	finish rename	done 2026-07-23
Props→state `useEffect` mirrors	`MunicipalityListExpectedVotesControl`, comboboxes	key-remount or fully controlled	closed 2026-07-23 (accepted as correct — see Debt Ledger row)
Detail-page RSCs mixing loading + tab UI + forms (300+ lines)	`municipios/[slug]/page.tsx`, `planos/[slug]/page.tsx`	extract tab loaders/sections	done 2026-07-25 (Pass 2 W4c): tabs em `MunicipalityDetailTabs.tsx` / `ActionPlanOverviewTab.tsx`; gêmeos de tab dedupados em `detailTabUi.ts`
God module: list URL + filters + sort + labels + freshness in one file (765 lines, 59 exports)	`src/utilities/municipalityUi.ts`	split along url/filters/sort/labels/freshness seams	done 2026-07-25 (Pass 2 W1-D1): `municipalityListUrl` / `municipalityListFilters` / `municipalityLabels` / `municipalitySignal`
`components/campaign/` flat with 106 files; `utilities/` flat with 92	`src/components/campaign/`, `src/utilities/`	within-layer domain subfolders	components done 2026-07-25 (Pass 2 W2, 15 domínios); `utilities/` deferred with trigger: a domain gaining its 3rd new module in a month gets its subfolder

Sprout / Wrap Register

Host	Sprouted/Wrapped	Notes
(none yet)

Adopted Conventions

Zero lint warnings. pnpm lint runs with --max-warnings=0; deliberate placeholders use a _ prefix (argsIgnorePattern).
as never is banned (ESLint no-restricted-syntax). Production code uses typed helpers (e.g. hookFilledCreateData for hook-completed create data); tests use stub<T>(partial) which keeps property-level checking. A justified eslint-disable-next-line is the only escape hatch.
Dead code is deleted, not commented. knip runs in CI (files/dependencies at error level). After any change: pnpm exec knip and remove what died.
Collections always declare access explicitly. Payload's default ("any authenticated user") is treated as a bug — see payloadAdminOnly.
Generated migration signatures are exempt from unused-args linting (src/migrations/** override); never hand-edit migration content for lint cosmetics.
Shared consent fixture rows are leased, never owned in integration tests (tests/helpers/testDatabaseLease.ts); deleting them steals from parallel spec files.

Debt Budget & Broken-Windows Policy

New warnings/as never/unused exports fail or get ledgered the same day — no untracked // TODOs.
Each delivery that runs /simplify registers surviving debts here or in docs/plans/escala-dry-pos-*.md (existing convention), whichever the item's size warrants.

50 KiB Raw Blame History Unescape Escape