--- id: CAP-MBR-STR-001 title: Define unit kinds and their permitted places feature: FEAT-MBR-STR-01 product_area: membership module: structure revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - react-console acceptance inventory CAP-MBR-STR-001 source_sha: services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: [] purpose: Administrators describe the association’s building blocks so new units fit an agreed structural pattern. outcomes: - Units use a recognized kind with explicit placement choices. - Unused kinds can leave active use while existing units retain their classification. concepts: - CON-MBR-STR-001 actors: - ACT-MBR-001 - ACT-MBR-002 - ACT-MBR-003 surfaces: - api preconditions: [] postconditions: [] permissions: - key: membership.structure.read where_checked: api scope: tenant - key: membership.structure.manage where_checked: api scope: tenant - key: membership.application.access where_checked: api scope: tenant rules: - id: BR-CAP-MBR-STR-001-01 statement: >- A unit kind retains a permanent readable identifier, supplied by staff or derived from its name, using lowercase letters, digits and single underscores. kind: validation enforced_at: - api - service - database must_prove: true provenance: observed source: >- services-membership:modules/structure/services/persistence/organizational-unit-types.ts:createOrganizationalUnitType origin: none examples: positive: Omitting the identifier for Sub Region produces sub_region. negative: A whitespace-bearing or reserved identifier fails validation. - id: BR-CAP-MBR-STR-001-02 statement: >- Creating or replacing a non-root kind without an allowed parent kind is rejected before any record is saved. kind: validation enforced_at: - service must_prove: true provenance: observed source: 'services-membership:modules/structure/services/persistence/organizational-unit-types.ts:parentIdsOf' origin: none - id: BR-CAP-MBR-STR-001-03 statement: >- Allowed parent kinds must belong to this workspace, with self-reference permitted for nested units of the same kind. kind: validation enforced_at: - service - database must_prove: true provenance: observed source: >- services-membership:modules/structure/services/persistence/organizational-unit-types.ts:requireKnownTypes origin: none - id: BR-CAP-MBR-STR-001-04 statement: Creating a kind under an existing identifier fails without altering the existing kind. kind: validation enforced_at: - service - database must_prove: true provenance: observed source: >- services-membership:modules/structure/services/persistence/organizational-unit-types.ts:createOrganizationalUnitType origin: none - id: BR-CAP-MBR-STR-001-05 statement: >- A kind’s root permission and allowed parent kinds cannot be withdrawn while current unit placements depend on them. kind: policy enforced_at: - service must_prove: true provenance: observed source: >- services-membership:modules/structure/services/persistence/organizational-unit-types.ts:updateOrganizationalUnitType origin: none - id: BR-CAP-MBR-STR-001-06 statement: A kind replacement requires the version read and restores omitted fields to their defaults. kind: policy enforced_at: - api - service must_prove: true provenance: observed source: >- services-membership:modules/structure/services/persistence/organizational-unit-types.ts:updateOrganizationalUnitType origin: none - id: BR-CAP-MBR-STR-001-07 statement: >- An inactive kind prevents creation and movement of its units while preserving their placements; a full replacement can reactivate the kind. kind: lifecycle enforced_at: - service must_prove: true provenance: observed source: 'services-membership:modules/structure/services/tree/tree-edits.ts:validatePlacement' origin: none - id: BR-CAP-MBR-STR-001-08 statement: 'Deletion is blocked while units, other kinds, programs or package requirements refer to the kind.' kind: lifecycle enforced_at: - service - database must_prove: true provenance: test source: >- services-membership:tests/e2e/structure-api.e2e.spec.ts#the structure API, end to end in process › refuses to delete a unit type in use, 409 unit_type_in_use origin: none - id: BR-CAP-MBR-STR-001-09 statement: 'Kind lists use display order followed by identifier, support pagination and can exclude inactive kinds.' kind: calculation enforced_at: - service must_prove: true provenance: observed source: >- services-membership:modules/structure/services/persistence/organizational-unit-types.ts:listOrganizationalUnitTypes origin: none - id: BR-CAP-MBR-STR-001-10 statement: >- The member-affiliation setting controls new affiliations without removing existing affiliations when it is disabled. kind: policy enforced_at: - service must_prove: true provenance: observed source: >- services-membership:modules/structure/services/persistence/organizational-unit-types.ts:updateOrganizationalUnitType origin: none - id: BR-CAP-MBR-STR-001-11 statement: Committee and geography settings are retained on the kind without an implemented consumer. kind: policy enforced_at: - service must_prove: false provenance: observed source: 'services-membership:modules/structure/aws/api/structure-requests.ts:unitTypeBody' origin: none scenarios: - id: SC-CAP-MBR-STR-001-01 given: 'The association uses national, regional, zone and chapter categories.' when: Staff save those categories with their permitted parent choices. then: The catalogue retains the choices and presents categories in display order. provenance: test source: >- services-membership:tests/acceptance/structure/MBR-ACC-0001.acceptance.ts#MBR-ACC-0001 staff define, rename, retire and delete kinds of unit edge_cases: - id: SC-CAP-MBR-STR-001-02 given: Existing chapters have zone parents. when: Staff withdraw zone parentage from the chapter category. then: The service requires those chapters to move before accepting the narrower choice. provenance: test source: >- services-membership:tests/acceptance/structure/MBR-ACC-0003.acceptance.ts#MBR-ACC-0003 a tree rule chapters rely on cannot be withdrawn until they move constraints: [] depends_on: [] related: - CAP-MBR-STR-002 - CAP-MBR-STR-010 journeys: - JNY-MBR-STR-001 open_questions: [] evidence: - >- services-membership: Examination of unit type persistence, request schemas, routes and the placement checks of the tree edits. - 'services-membership: Examination of structure end-to-end and acceptance journeys MBR-ACC-0001 to 0004.' - 'react-console: Review of acceptance inventory CAP-MBR-STR-001 and its rules.' - 'services-membership:modules/structure/aws/api/structure-requests.ts' - 'services-membership:modules/structure/services/persistence/organizational-unit-types.ts' - 'services-membership:modules/structure/services/tree/tree-edits.ts' - 'services-membership:tests/e2e/structure-api.e2e.spec.ts' controls: [TC-AVL-002, TC-AVL-003, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-DAT-001, TC-DAT-004, TC-DAT-007, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-PI-001, TC-PI-003, TC-PI-005, TC-SEC-001, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003] --- # Define unit kinds and their permitted places ## Purpose Administrators describe the association’s building blocks so new units fit an agreed structural pattern. ## How It Works An administrator starts by naming the structural categories the association uses. National bodies, regions and chapters are examples rather than a fixed catalogue. Each category has its own readable reference, presentation details and placement choices. Staff specify possible parents and whether units of that kind may stand independently at the top. The service checks those choices when units are placed. A later adjustment may fail because an existing placement still relies on the previous choices. Staff resolve those placements before narrowing the category. Retiring a category keeps its existing units recognizable. Reactivation restores its availability for placement work. Deletion requires the category to be free of references. ## Relationships - Placement and restructuring use these categories to assess proposed parents. - Program affiliation requirements select categories from this catalogue.