# Spec: project-members-read

## ADDED Requirements

### Requirement: List allowed sections for a project

The system SHALL expose `GET /api/project-sections` with required query parameter `project_id`.

The endpoint MUST require `X-Api-Key` when configured and MUST NOT require `X-Acting-Emp-Id`.

The response MUST include `project_id`, `total`, and `items[]` where each item has `section_id` and `section_name`.

Sections MUST be resolved by joining `tMerakomisProjectSection` with `tMerakomisDSection` for the given project.

Items MUST be ordered by section name ascending.

#### Scenario: Project with configured sections

- **WHEN** client requests `GET /api/project-sections?project_id=86`
- **AND** project 86 has rows in `tMerakomisProjectSection`
- **THEN** system returns all allowed sections with human-readable names

#### Scenario: Unknown project

- **WHEN** `project_id` does not exist or project is removed
- **THEN** system returns `404`

#### Scenario: Empty section list

- **WHEN** project exists but has no `tMerakomisProjectSection` rows
- **THEN** system returns `200` with `total: 0` and empty `items`

### Requirement: List member roles reference

The system SHALL expose `GET /api/member-roles` that returns role ids and titles matching PHP `eMemberRole` non-archived entries.

The endpoint MUST require `X-Api-Key` when configured and MUST NOT require `X-Acting-Emp-Id`.

Each item MUST include `id` (integer) and `title` (string with hierarchy prefix as in CMS).

Optional query `role` (integer): when provided, the response MUST include that role even if marked archive in the reference data (for edit forms).

#### Scenario: Default role list for add form

- **WHEN** client requests `GET /api/member-roles` without query
- **THEN** system returns all non-archived roles (e.g. GIP, GAP, Employer)

#### Scenario: Edit form includes current archived role

- **WHEN** client requests `GET /api/member-roles?role=8`
- **AND** role 8 is archived in reference data
- **THEN** response items include role 8 in addition to non-archived roles

### Requirement: Document integration read flow

Documentation (`DEVELOPERS.md`, `docs/user-reader-api.md`) MUST describe the sequence for building an external add-member UI:

1. `GET /api/project-sections?project_id=…`
2. `GET /api/member-roles`
3. `GET /api/labor/permissions?…` → `can_write_member`
4. `PUT /api/project-members`

#### Scenario: Integrator follows documented flow

- **WHEN** integrator reads updated API docs
- **THEN** docs list all four steps with required headers and example JSON body for PUT