meraproject/openspec/changes/project-members-write/specs/project-members-read/spec.md

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