Unit Assignment Service

Unit Assignment Service is a medium-complexity shared backend service that depends on both unit-assignment-repository and hierarchy-service. The dependency on hierarchy-service means it cannot be fully tested in isolation until hierarchy management is stable. Key delivery risks include the multi-chapter limit validation (max 5 for NHF), which requires clear product sign-off on the exact constraint rules before implementation to avoid rework. The is_primary enforcement across assignments requires careful transaction handling to prevent race conditions when two concurrent requests attempt to set a new primary unit.

Plan integration testing for all assignment lifecycle scenarios: initial assignment, primary update, secondary additions, and removal. Because this service is shared across features that rely on session context, changes to its interface carry broad impact — scope a regression pass across all dependent features when modifying it.

UnitAssignmentService manages the unit_assignment junction table, linking users to one or more organization_units. Its interface covers assignUserToUnit(userId, unitId, isPrimary), removeAssignment(), setPrimaryUnit(), getAssignmentsForUser(userId, organizationId), getAssignmentsForUnit(unitId), and getUserCountForUnit(unitId). The is_primary constraint must be enforced transactionally — when setting a new primary, wrap the unset of any existing primary and the set of the new one in a single atomic operation to prevent orphaned or duplicate primaries. The five-unit limit for multi-chapter organizations (e.g., NHF) should be validated against a count query before inserting a new assignment, with organization-type awareness sourced from a config or the organization record.

It depends on hierarchy-service for validating that the target unit exists within the correct organization scope. getUserCountForUnit() is used by the admin portal for member count displays — consider caching or materializing this count for large units to avoid expensive joins on each render.