67 lines
2.5 KiB
Markdown
67 lines
2.5 KiB
Markdown
|
# 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
|