Overview

Fact: a franchise unit now exists in Nexus. The payload is a full snapshot of the aggregate re-read after commit: unit data, statuses, category, economic group, region, address, partners (without roles) and products.

When it is published. CNA NexusCNA NexusService•v1.0.0Franchise network back-office (franchises, economic groups, partners, contracts and amendments, document storage, AI doc...PublishesInviteUser, ContractActivationRequested +13SubscribesContractActivationRequested, AmendmentApplyRequested +4Ownercna-platformMapRepoView docs, in createFranchiseForOpening, the only place a franchise is created: the activation of an OPENING ContractContractEntity•v1.0.0A franchise contract in CNA Nexus - opening, renewal or resale - uploaded as a document, analysed by AI, reviewed by a p...Ownercna-platformView docs with no franchise yet (see Contract Activation RequestedContract Activation RequestedEvent•v1.0.0A user saved a contract for activation. cna-nexus's activation consumer turns it ACTIVE and creates or updates the franc...Ownercna-platformSchemaMapView docs). Registered with manager.afterCommit(), so it goes out only after the unit, its brand, address, territory and partners are committed. The same commit also emits one Franchise Partner AddedFranchise Partner AddedEvent•v1.1.0A person became a partner of a franchise unit, with their roles. One message per partner. Consumed by cna-nexus itself t...Ownercna-platformSchemaMapView docs per partner.

What the consumer does. CNA OneCNA OneService•v1.0.0Franchise operating system (franchises and employees, pricing, products and learning books, school operations). Publishe...PublishesGrantApplicationAccess, EmployeeCreated +6SubscribesInviteUser, FranchiseCreated +9Ownercna-platformMapRepoView docs (franchiseConsumer, handler syncFranchise), in three blocks:

1. Franchise: requires and validates cnpj and legalName, checks name, slug and e-mail uniqueness, resolves economicGroup.id (it must have been mirrored by Economic Group CreatedEconomic Group CreatedEvent•v1.0.0An economic group was created in CNA Nexus. cna-one mirrors it by id so that franchises can reference it.Ownercna-platformSchemaMapView docs first, otherwise the message fails), maps the enums onto cna-one’s own, derives status (ACTIVE when operationalStatus is OPERATIONAL), keeps only the distinct product sub-categories, and upserts by id. If this block fails nothing is written.
2. Address: skipped when absent; requires street, number, neighborhood, postal code and an IBGE cityId known to cna-one; upserts the unit’s address in place. Failure here is logged and skipped.
3. Partners: one per distinct document; each becomes a person, an employee, an employment contract with the FRANCHISEE job role and an active staff link, in one transaction. cna-one then publishes its own Employee CreatedEmployee CreatedEvent•v1.0.0An employee was created in CNA One, with the person it points at. Consumed by cna-auth to provision the account and the ...Ownercna-platformSchemaMapView docs (new employee) or Employee UpdatedEmployee UpdatedEvent•v1.0.0An employee or the person it points at changed in CNA One. Consumed by cna-auth to update the account and the user, incl...Ownercna-platformSchemaMapView docs (already known), which is what provisions the login in cna-auth. One bad partner is skipped without stopping the others.

Failures are logged and reported to Sentry, never rethrown.

Kafka

Payload schema

Source of truth

export type FranchisePayload = {
  id: string;
  name: string;
  code?: string | null;
  cnpj?: string | null;
  legalName?: string | null;
  stateRegistration?: string | null;
  taxRegime?: string | null;
  protheusId?: string | null;
  conectaEnabled: boolean;
  openingStatus: string;
  operationalStatus: string;
  financialStatus?: string | null;
  operationalStartAt?: string | null;
  operationalEndAt?: string | null;
  firstContractStartsOn?: string | null;
  category: FranchiseCategoryData;
  economicGroup?: FranchiseEconomicGroupData | null;
  operationalRegion?: FranchiseOperationalRegionData | null;
  address?: FranchiseAddressData | null;
  partners: FranchisePartnerData[];
  products: FranchiseProductData[];
};

export class FranchiseCreated extends Event<FranchisePayload> {
  static readonly owner = 'NEXUS';
  static readonly aggregateRoot = 'Franchise';
  static readonly routingKey = 'id';
}

Known drift

cna-one api/app/events/nexus/franchise/FranchiseCreated.ts differs from the canonical type: