# service-project-members

## Purpose

Service-to-service API для upsert участника проекта Merakomis без impersonation сотрудника (только API-ключ).

## Requirements

### Requirement: Service upsert project team member

The system SHALL expose `PUT /api/service/project-members` that creates or updates a row in `tMerakomisTeamMember` for the given `project_id` and `emp_id`.

The endpoint MUST resolve `team` from `tMerakomisProject.team` for `project_id`.

If a row with the same `(team, emp)` already exists, the system MUST UPDATE it; otherwise MUST INSERT.

The request MUST require `X-Api-Key` (or `Authorization: Bearer`) when the server API key is configured.

The request MUST NOT require `X-Acting-Emp-Id`.

The system MUST NOT apply portal `Rules::isRwMember` / `can_write_project_member` checks for this endpoint.

Required JSON fields: `project_id`, `emp_id`, `section_id`, `role`.

Optional JSON fields: `active` (default `true`), `text` (default empty string).

The response MUST include `ok: true` and a member object with the same fields as one item of `GET /api/project-members` (`member_id`, `emp_id`, `emp_name`, `project_id`, `project_code`, `project_name`, `step_name`, `status`, `status_name`, `archive`, `archive_date`, `section_id`, `section_name`, `role`, `active`).

#### Scenario: Add new member with API key only

- **WHEN** a valid API key is provided
- **AND** `X-Acting-Emp-Id` is omitted
- **AND** no `tMerakomisTeamMember` row exists for `(team, emp)`
- **AND** `section_id` is allowed for `project_id`
- **AND** `emp_id` refers to a non-archived, non-removed employee
- **AND** `role` is a valid member role
- **THEN** system inserts a new TeamMember row
- **AND** returns `200` with `ok: true` and the new member object including `member_id`

#### Scenario: Update existing member with API key only

- **WHEN** a TeamMember row already exists for `(team, emp)`
- **AND** a valid API key is provided without acting header
- **THEN** system updates `section`, `role`, `active`, and `text`
- **AND** returns `200` with updated member object (same `member_id`)

#### Scenario: Deactivate member via service endpoint

- **WHEN** client sends `PUT /api/service/project-members` with `active: false`
- **AND** a valid API key is provided
- **THEN** system sets `active` to 0
- **AND** member no longer appears in `GET /api/project-members?active_only=true`

#### Scenario: Missing API key rejected

- **WHEN** server has `USER_READER_API_KEY` configured
- **AND** client calls `PUT /api/service/project-members` without a valid key
- **THEN** system returns `401 Unauthorized`

### Requirement: Service endpoint reuses portal write validation

The system MUST apply the same business validation as `PUT /api/project-members` for project existence, employee existence and eligibility, section membership in the project, role validity, and presence of a project team.

#### Scenario: Invalid section for project

- **WHEN** `section_id` is not in `tMerakomisProjectSection` for `project_id`
- **THEN** system returns `400` with a structured error indicating invalid section

#### Scenario: Project has no configured sections

- **WHEN** `tMerakomisProjectSection` has no rows for `project_id`
- **AND** client attempts to add a member via the service endpoint
- **THEN** system returns `400` indicating sections must be configured on the project first

#### Scenario: Archived employee rejected

- **WHEN** `emp_id` refers to an employee with `archive=1` or `removed=1`
- **THEN** system returns `400` with validation error for employee

#### Scenario: Unknown employee

- **WHEN** `emp_id` does not exist in the employee table
- **THEN** system returns `404`

#### Scenario: Unknown project

- **WHEN** `project_id` does not exist
- **THEN** system returns `404`

#### Scenario: Invalid role

- **WHEN** `role` is 0, omitted, or not a valid member role
- **THEN** system returns `400` with validation error for role

### Requirement: Portal project-members write remains unchanged

The system MUST continue to require `X-Acting-Emp-Id` and `isRwMember` authorization for `PUT /api/project-members`.

#### Scenario: Portal PUT still requires acting

- **WHEN** client calls `PUT /api/project-members` without `X-Acting-Emp-Id`
- **THEN** system returns an error indicating missing acting identity (same behavior as before this change)

#### Scenario: Portal PUT still enforces permissions

- **WHEN** acting employee does not meet `isRwMember` conditions
- **AND** client calls `PUT /api/project-members`
- **THEN** system returns `403` with structured error `forbidden`