--- id: CON-MBR-MEM-003 name: Unit Affiliation feature: FEAT-MBR-MEM-02 product_area: membership module: memberships revision: 1 status: draft product_intent: confirmed implementation_evidence: observed source_sha: services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A unit affiliation connects a membership term to a chapter, section or another organizational unit for a dated span, retaining its primary designation, origin and any purchased dues reference. owned_by: MOD-MBR-MEM synonyms: - chapter affiliation - chapter membership (informally) not_to_be_confused_with: - CRM affiliations connect people to organizations. - An identity-bound chapter program establishes a separate membership holding. - The structure module owns the unit and its place in the hierarchy. facets: - name: Unit and unit type meaning: The selected organizational unit and the category copied onto its affiliation. used_for: 'Connecting member rosters, allowed unit categories and officer authority.' - name: Span meaning: The inclusive days during the term when this connection applies. used_for: Determining unit membership for a requested day. - name: Primary meaning: The designation of a connection as primary for its unit category during its span. used_for: Supporting uses that require a preferred chapter connection. - name: Source and lineage meaning: >- The entry source distinguishes applicant choice, staff entry, inheritance and transfer, with a reference to a predecessor where applicable. used_for: Explaining how chapter choices continue across periods and moves. - name: Dues line meaning: A purchased connection retains its dues product and Commerce line. used_for: Tracing dues and identifying changes that require a purchase. - name: Unit rules meaning: >- Program requirements and package overrides govern eligible unit categories, counts and primary choices; portal settings describe intended member changes. used_for: Validating the set of affiliations within a period. - name: Scope marker meaning: The read marks whether the officer’s grants cover this affiliation’s unit. used_for: Showing other chapter connections while distinguishing authority to change them. - name: Roster rule meaning: Workspace settings determine whether grace extends unit visibility for officers. used_for: Handling officer lists and exports around period expiry. relationships: - to: CON-MBR-MEM-002 statement: The membership term owns the connection and bounds its effective dates. provenance: observed source: 'services-membership:modules/memberships/db/membership-term-organizational-units.table.ts' - to: CON-MBR-MEM-001 statement: >- Effective affiliations and their unit ancestors contribute to the membership visibility chain used for officer access. provenance: observed source: 'services-membership:modules/memberships/services/persistence/visibility-chains.ts' acted_on_by: - CAP-MBR-MEM-007 - CAP-MBR-MEM-008 - CAP-MBR-MEM-009 - CAP-MBR-MEM-015 - CAP-MBR-MEM-016 visible_to: - ACT-MBR-006 - ACT-MBR-007 - ACT-MBR-008 - ACT-MBR-009 - ACT-MBR-010 evidence: - >- services-membership at 5994c270e8a37a30f848e99ba5b5ee6b87c08893: modules/memberships/db/membership-term-organizational-units.table.ts; services/affiliations/affiliation-operations.ts, unit-rules.ts, unit-merge.ts; services/access/unit-scope.ts; db/scope-settings.table.ts; docs/migrations/membership-core/README.md (P2b); docs/migrations/unit-merge/README.md; docs/migrations/scope/README.md. supersedes: - 'inventory:CAP-MBR-AFF-001' --- # Unit Affiliation ## What It Is A unit affiliation records where a member belongs within the association’s structure during one membership period. It connects the term to a chapter, section or another allowed unit and dates that connection. A member can hold several chapter connections during the same period, with separate spans and primary choices rather than one chapter value repeatedly overwritten. The affiliation retains the unit category, entry source and any continuation from an earlier connection. Where the connection was purchased, it also carries a dues product and order-line reference. These details make a chapter move explainable and help distinguish a deliberate new choice from a connection carried into the next period. ## What It Is Not A CRM affiliation connects a person to an organization, such as an employer. Membership’s affiliation connects a term to the association’s own organizational unit. A separately sold chapter program can instead establish an identity-bound membership; that holding has its own periods. The unit’s name, hierarchy and dues configuration remain the structure module’s records. ## How It Is Used Staff select units when recording a term and can later add, end or transfer connections. A renewal without explicit choices can inherit eligible connections from the preceding period. Officers perform permitted changes within their grants and can see a member’s other connections marked as outside their scope. Rosters use effective connections to identify members on a chosen day, including units below a selected parent where requested. A normal addition or transfer into a dues-charging unit requires the purchase workflow. A unit merge follows its own transactional rules, preserving closed history and moving or resolving open connections. Some merge paths leave primary selection unresolved, so staff should not assume every member necessarily has a primary after a merge. ## Its Facets **Unit and unit type.** The selected unit and its category determine which configured requirements apply. Live affiliation entry checks that the unit can accept the connection. **Span.** Start and end days describe the effective connection within the term. Ending a connection before it begins can withdraw it, subject to retained transfer lineage. **Primary.** Unless multiple primaries are allowed, there can be at most one effective primary of a category on a day. That upper limit does not itself guarantee that a primary exists. **Source and lineage.** Staff entry, application choice, inheritance and transfer explain how the affiliation arose. A transfer refers back to the connection it continues. **Dues line.** Purchased affiliations retain the dues reference used by scoped financial summaries. An ordinary chapter change cannot silently supply the dues purchase it requires. **Unit rules.** Program rules and package overrides determine eligible categories and counts. Maximum checks cover the term, while minimum checks begin from the operation’s effective day. Stored portal settings are not yet an operational member editor. **Scope marker.** A visible membership can show connections beyond the officer’s grants. The marker separates visibility of those facts from permission to alter them. **Roster rule.** The workspace can keep grace members visible to officers through their last effective units. Unit-filtered lists and exports currently have a recorded consistency gap in applying that choice. ## How It Relates The term supplies the containing period, and the membership supplies the owner. The structure supplies units and their ancestors. Commerce supplies purchased dues references. Historical reconstruction and monthly snapshots use dated affiliations alongside the historical tree, while only selected affiliation operations publish remote business events. ## What It Could Become The product should settle how reports choose among permitted multiple primaries and how merges preserve a useful primary connection. It should also complete member-controlled chapter changes, migration entry and purchased mid-term moves. Changes that repair existing affiliations after configuration is tightened need a deliberate policy rather than being blocked by historical violations.