69 lines
5.6 KiB
Markdown
69 lines
5.6 KiB
Markdown
# Requirements Document
|
||
|
||
## Introduction
|
||
|
||
The STEAM Security Dashboard integrates with Charter's Jira Data Center via a service account. A service account approval request (ATLSUP ticket) was submitted and the reviewer identified two compliance issues that must be resolved before production approval:
|
||
|
||
1. The `POST /api/jira/search` Express route accepts arbitrary JQL from the frontend and proxies it to `POST /rest/api/2/search`, which is not an approved Jira API pattern. This endpoint must be removed entirely — the dashboard's actual workflows (create, sync, lookup) are already served by other endpoints.
|
||
2. The `searchIssuesByKeys()` bulk-sync function uses `updated >= -24h` in its JQL, but the team works Monday–Friday, meaning the worst-case gap between syncs is Friday evening to Monday morning (~60 hours). The window must be widened to `-72h` to cover weekends.
|
||
3. The API use-cases documentation (`jira-api-use-cases.md`) must be updated to reflect both changes so the compliance summary remains accurate for the ATLSUP reviewer.
|
||
|
||
## Glossary
|
||
|
||
- **Dashboard**: The STEAM Security Dashboard Node.js/Express backend application
|
||
- **Search_Route**: The `POST /api/jira/search` Express route in `backend/routes/jiraTickets.js` that accepts arbitrary JQL from the frontend
|
||
- **SearchIssuesByKeys_Function**: The `searchIssuesByKeys()` helper function in `backend/helpers/jiraApi.js` used by the bulk sync-all flow
|
||
- **SearchIssues_Function**: The `searchIssues()` helper function in `backend/helpers/jiraApi.js` that executes JQL queries via `GET /rest/api/2/search`
|
||
- **Sync_All_Route**: The `POST /api/jira/sync-all` Express route that bulk-refreshes all tracked Jira tickets
|
||
- **JQL_Window**: The `updated >= -Xh` clause appended to JQL queries to limit results to recently-changed issues
|
||
- **API_Documentation**: The file `docs/api/jira-api-use-cases.md` that documents all Jira API use cases for the ATLSUP reviewer
|
||
- **Compliance_Summary_Table**: The table in the API_Documentation that summarizes Charter compliance posture
|
||
|
||
## Requirements
|
||
|
||
### Requirement 1: Remove the arbitrary JQL search route
|
||
|
||
**User Story:** As a service account reviewer, I want the dashboard to not expose an arbitrary JQL search endpoint, so that the integration only uses approved Jira API patterns.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN the Dashboard starts, THE Dashboard SHALL NOT register a `POST /api/jira/search` route
|
||
2. WHEN a client sends a `POST` request to `/api/jira/search`, THE Dashboard SHALL respond with HTTP 404
|
||
3. WHILE the Search_Route is removed, THE Sync_All_Route SHALL continue to function by calling the SearchIssuesByKeys_Function
|
||
4. WHILE the Search_Route is removed, THE Dashboard SHALL continue to support single-ticket lookup via `GET /api/jira/lookup/:issueKey`
|
||
5. WHILE the Search_Route is removed, THE Dashboard SHALL continue to support single-ticket sync via `POST /api/jira/:id/sync`
|
||
6. WHILE the Search_Route is removed, THE Dashboard SHALL continue to support ticket creation via `POST /api/jira/create-in-jira`
|
||
|
||
### Requirement 2: Widen the bulk-sync JQL time window to 72 hours
|
||
|
||
**User Story:** As a dashboard administrator, I want the bulk sync to use a 72-hour JQL window, so that tickets updated over the weekend are captured on Monday morning.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN the SearchIssuesByKeys_Function builds a JQL query, THE SearchIssuesByKeys_Function SHALL include the clause `updated >= -72h` instead of `updated >= -24h`
|
||
2. WHEN the Sync_All_Route processes a batch of ticket keys, THE Sync_All_Route SHALL receive results that include tickets updated within the last 72 hours
|
||
3. WHILE the JQL_Window is set to 72 hours, THE SearchIssuesByKeys_Function SHALL continue to include the `project = <KEY>` clause in the JQL query
|
||
4. WHILE the JQL_Window is set to 72 hours, THE SearchIssuesByKeys_Function SHALL continue to cap `maxResults` at 1000
|
||
|
||
### Requirement 3: Update the API use-cases documentation
|
||
|
||
**User Story:** As a service account reviewer, I want the API documentation to accurately reflect the dashboard's current Jira API usage, so that the ATLSUP approval can proceed without discrepancies.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN the API_Documentation is updated, THE API_Documentation SHALL NOT contain a use case entry for `POST /api/jira/search` or arbitrary JQL search
|
||
2. WHEN the API_Documentation is updated, THE API_Documentation SHALL show the JQL pattern for the bulk sync use case as `updated >= -72h` instead of `updated >= -24h`
|
||
3. WHEN the API_Documentation is updated, THE Compliance_Summary_Table SHALL accurately reflect that all JQL queries use scoped, predefined patterns with no arbitrary JQL passthrough
|
||
4. WHEN the API_Documentation is updated, THE API_Documentation SHALL update the estimated daily API usage table to remove the row for the arbitrary JQL search endpoint
|
||
5. WHEN the API_Documentation is updated, THE API_Documentation SHALL update the total estimated daily API call range to reflect the removal of the search endpoint
|
||
|
||
### Requirement 4: Preserve the internal searchIssues helper for scoped callers
|
||
|
||
**User Story:** As a developer, I want the internal `searchIssues()` helper to remain available for use by `getIssue()` and `searchIssuesByKeys()`, so that existing scoped JQL operations continue to work.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHILE the Search_Route is removed, THE SearchIssues_Function SHALL remain exported from `jiraApi.js` for use by internal callers
|
||
2. WHEN the `getIssue()` function is called, THE SearchIssues_Function SHALL execute the JQL query and return the matching issue
|
||
3. WHEN the SearchIssuesByKeys_Function is called, THE SearchIssues_Function SHALL execute the bulk JQL query and return matching issues
|