# Bugfix Requirements Document

## Introduction

The Jira REST API integration in the STEAM Security Dashboard was submitted for production approval and the reviewer identified three compliance violations that block approval. The `searchIssues()` function uses `POST /rest/api/2/search` instead of the required `GET` with query parameters. The `getIssue()` function performs single-issue `GET /rest/api/2/issue/{key}` calls, which are not allowed — all issue fetching must go through JQL search. Additionally, JQL queries do not consistently include `project = <KEY>` scoping, which is required for all search operations. These issues affect `backend/helpers/jiraApi.js`, `backend/scripts/jira-uat-test.js`, and `docs/jira-api-use-cases.md`.

## Bug Analysis

### Current Behavior (Defect)

1.1 WHEN `searchIssues()` is called with a JQL query THEN the system sends a `POST /rest/api/2/search` request with a JSON body containing `{ jql, startAt, maxResults, fields }`, which is not allowed by the reviewer

1.2 WHEN `searchIssuesByKeys()` is called to bulk-fetch issues by key THEN the system sends a `POST /rest/api/2/search` request (via `searchIssues()`) without a `project = <KEY>` clause in the JQL

1.3 WHEN `getIssue()` is called with a single issue key THEN the system sends a `GET /rest/api/2/issue/{key}?fields=...` request, which is a single-issue GET that the reviewer does not allow

1.4 WHEN the UAT test script exercises use case 3 ("Get Single Issue") THEN it calls `getIssue()` which performs the non-compliant single-issue GET pattern

1.5 WHEN the UAT test script exercises use case 8 ("JQL Search") THEN it calls `searchIssues()` which performs the non-compliant POST to `/rest/api/2/search`

1.6 WHEN the API documentation describes the JQL Search use case THEN it lists the endpoint as `POST /rest/api/2/search`, which does not match the required compliant pattern

1.7 WHEN the API documentation describes the "Get Single Issue" and "Issue Lookup" use cases THEN it lists the endpoint as `GET /rest/api/2/issue/{issueKey}?fields=...`, which is the non-compliant single-issue GET pattern

### Expected Behavior (Correct)

2.1 WHEN `searchIssues()` is called with a JQL query THEN the system SHALL send a `GET /rest/api/2/search` request with query parameters `?jql=<encoded-jql>&fields=<comma-separated-fields>&maxResults=1000&startAt=0` instead of a POST with a JSON body

2.2 WHEN `searchIssuesByKeys()` is called to bulk-fetch issues by key THEN the system SHALL include a `project = <JIRA_PROJECT_KEY>` clause in the JQL query alongside the `key in (...)` clause

2.3 WHEN `getIssue()` is called with a single issue key THEN the system SHALL perform a JQL search using `GET /rest/api/2/search?jql=key="ISSUE-KEY" AND project=<JIRA_PROJECT_KEY>&fields=<fields>&maxResults=1` instead of a direct single-issue GET

2.4 WHEN the UAT test script exercises the single-issue fetch use case THEN it SHALL call the refactored `getIssue()` which uses JQL search, and the test name SHALL reflect the compliant pattern

2.5 WHEN the UAT test script exercises the JQL search use case THEN it SHALL call `searchIssues()` which uses `GET /rest/api/2/search` with query parameters, and the JQL SHALL include `project = <JIRA_PROJECT_KEY>` scoping

2.6 WHEN the API documentation describes the JQL Search use case THEN it SHALL list the endpoint as `GET /rest/api/2/search` with query parameters `?jql=`, `&fields=`, `&maxResults=`, `&startAt=`

2.7 WHEN the API documentation describes the single-issue fetch use case THEN it SHALL describe it as a JQL search using `GET /rest/api/2/search?jql=key="ISSUE-KEY" AND project=<KEY>&fields=...&maxResults=1` and SHALL NOT reference `GET /rest/api/2/issue/{key}`

### Unchanged Behavior (Regression Prevention)

3.1 WHEN `createIssue()` is called THEN the system SHALL CONTINUE TO send a `POST /rest/api/2/issue` request with the issue fields in the JSON body

3.2 WHEN `updateIssue()` is called THEN the system SHALL CONTINUE TO send a `PUT /rest/api/2/issue/{key}` request to update a single issue

3.3 WHEN `addComment()` is called THEN the system SHALL CONTINUE TO send a `POST /rest/api/2/issue/{key}/comment` request

3.4 WHEN `transitionIssue()` is called THEN the system SHALL CONTINUE TO send a `POST /rest/api/2/issue/{key}/transitions` request

3.5 WHEN `getTransitions()` is called THEN the system SHALL CONTINUE TO send a `GET /rest/api/2/issue/{key}/transitions` request

3.6 WHEN `testConnection()` is called THEN the system SHALL CONTINUE TO send a `GET /rest/api/2/myself` request

3.7 WHEN the rate limiter checks request counts THEN the system SHALL CONTINUE TO enforce the 1,440 requests/day daily limit and 60 requests/minute burst limit

3.8 WHEN inter-request delays are applied THEN the system SHALL CONTINUE TO enforce 1 second delay between GET requests and 2 second delay between write requests

3.9 WHEN a blocked endpoint path is requested THEN the system SHALL CONTINUE TO reject calls to `/rest/api/2/field` and `/rest/api/2/issue/bulk`

3.10 WHEN `searchIssues()` returns results THEN the system SHALL CONTINUE TO return the same `{ ok, data }` response shape so that all callers remain compatible