teqo/src/lib/schemas/municipality.ts
Francisco Ignácio Fontoura Solla c7001b75f0 E14: engagement levels N0-N4 and the first allocationDecision writer.
`municipality.engagementLevel` (staff-only, no default) records what the
campaign decided to invest in a município, next to the E8/E10 metrics that
describe what it knows. Moving it is a reallocation decision, so only
unrestricted staff may, every move carries a rationale plus the signals that
would reverse it, and the write files an `allocationDecision` in the same
transaction under an advisory lock taken before the current level is read —
otherwise the snapshot's `from` is a guess. The enum gains `movimento`: a level
move is neither `aceita` nor `descarta`.

No backfill. Null is "Sem nível", and filtering by it is the triage queue.
That is also why the list sorts `nivel` in memory rather than in the query:
Postgres puts NULLs first on DESC, so a native sort would open "N4 primeiro"
on a page of municípios nobody has decided about yet. The filter stays native.

The hysteresis rules from research §6.8 are pure and client-safe, so the
Popover explains a block before submitting and the server re-runs them anyway;
a blocked move answers 409 with typed violations and the override is recorded
with exactly the rules it contradicted.
2026-07-27 21:19:33 -03:00

97 lines
4 KiB
TypeScript

import { z } from 'zod'
import { ENGAGEMENT_LEVEL_TEXT_MAX_LENGTH, engagementLevels } from '@/lib/engagementLevel'
import { positiveRelationshipId, trimmedNullableText } from '@/lib/schemas/primitives'
import { voteEstimateScenarioFieldsSchema } from '@/lib/schemas/votePledge'
export const politicalTrendStatuses = ['favoravel', 'neutra', 'desfavoravel'] as const
export type PoliticalTrendStatusValue = (typeof politicalTrendStatuses)[number]
const stateDeputiesArraySchema = z
.array(positiveRelationshipId)
.max(20)
.transform((ids) => [...new Set(ids)])
export const municipalityStrategyUpdateSchema = z.object({
municipality: positiveRelationshipId,
priority: z.enum(['alta', 'normal']).optional(),
strengths: z.array(z.string().trim().min(1).max(1000)).max(20).optional(),
risks: z.array(z.string().trim().min(1).max(1000)).max(20).optional(),
stateDeputies: stateDeputiesArraySchema.optional(),
dobradinhaNotes: trimmedNullableText(4000),
nextSteps: trimmedNullableText(4000),
budgetNotes: trimmedNullableText(4000),
})
export const municipalityPoliticalTrendSchema = z.object({
municipality: positiveRelationshipId,
status: z.enum(politicalTrendStatuses).nullable(),
note: trimmedNullableText(2000),
})
export const parsePoliticalTrendStatusFormValue = (
raw: string | undefined,
): PoliticalTrendStatusValue | null => {
if (!raw) return null
return politicalTrendStatuses.includes(raw as PoliticalTrendStatusValue)
? (raw as PoliticalTrendStatusValue)
: null
}
export const MAX_ADVISORS_PER_MUNICIPALITY = 10
export const municipalityAdvisorsAssignmentSchema = z.object({
municipality: positiveRelationshipId,
advisors: z
.array(positiveRelationshipId)
.max(MAX_ADVISORS_PER_MUNICIPALITY)
.transform((ids) => [...new Set(ids)]),
})
/** Single-toggle delta from the list popover — one advisor at a time, never the whole array. */
export const municipalityAdvisorMembershipSchema = z.object({
municipality: positiveRelationshipId,
advisor: positiveRelationshipId,
assigned: z.boolean(),
})
export const MUNICIPALITY_ADVISOR_MEMBERSHIP_UNRESTRICTED_MESSAGE =
'Somente a coordenação geral ou o candidato designa assessores.'
export const MUNICIPALITY_ADVISOR_MEMBERSHIP_SAFE_MESSAGES = [
MUNICIPALITY_ADVISOR_MEMBERSHIP_UNRESTRICTED_MESSAGE,
`Cada município aceita no máximo ${MAX_ADVISORS_PER_MUNICIPALITY} assessores.`,
] as const
export const MUNICIPALITY_ENGAGEMENT_LEVEL_UNRESTRICTED_MESSAGE =
'Somente a coordenação geral ou o candidato move o nível de envolvimento.'
/**
* E14 — a movement is never just the new level: the motivo and the signals
* that would reverse it are what make the decision auditable later, so both
* are required by the schema rather than by the form alone.
*/
export const municipalityEngagementLevelSchema = z.object({
municipality: positiveRelationshipId,
level: z.enum(engagementLevels),
note: z.string().trim().min(1).max(ENGAGEMENT_LEVEL_TEXT_MAX_LENGTH),
reversalSignals: z.string().trim().min(1).max(ENGAGEMENT_LEVEL_TEXT_MAX_LENGTH),
/** Licenses a two-level jump (research §6.8). */
triangulatedShock: z.boolean().default(false),
/** Accepts the listed violations knowingly; recorded in the decision snapshot. */
override: z.boolean().default(false),
})
export const municipalityExpectedVotesSchema = z.object({
municipality: positiveRelationshipId,
expectedVotes: voteEstimateScenarioFieldsSchema,
})
export type MunicipalityStrategyUpdateInput = z.input<typeof municipalityStrategyUpdateSchema>
export type MunicipalityPoliticalTrendInput = z.input<typeof municipalityPoliticalTrendSchema>
export type MunicipalityAdvisorsAssignmentInput = z.input<
typeof municipalityAdvisorsAssignmentSchema
>
export type MunicipalityAdvisorMembershipInput = z.input<typeof municipalityAdvisorMembershipSchema>
export type MunicipalityExpectedVotesInput = z.input<typeof municipalityExpectedVotesSchema>
export type MunicipalityEngagementLevelInput = z.input<typeof municipalityEngagementLevelSchema>