feat: pass opportunityId to assess-urls worker for precheck persistence

[danielbatica]

Summary

• Include opportunityId in SQS message payload for assess-urls action
• Remove comment claiming opportunityId was intentionally omitted
• Update acceptance response to include opportunityId for better traceability

Problem

The assess-urls worker needs opportunityId to fetch suggestion entities and save precheck results to the database. Previously, opportunityId was intentionally omitted from the SQS message, causing precheck results to be lost when the async Lambda completed.

Solution

Pass opportunityId in the SQS message so the worker can:

1. Fetch all suggestions for the opportunity
2. Match images by URL from suggestion recommendation data
3. Save precheck results to autofixPrecheckStatus field on each suggestion

Code Changes

// Before
await sqs.sendMessage(queueUrl, {
  siteId,
  // Intentionally omit opportunityId
  action: 'assess-urls',
  pages,
  ...(precheckOnly === true && { precheckOnly: true }),
});

// After
await sqs.sendMessage(queueUrl, {
  siteId,
  opportunityId,  // Now included
  action: 'assess-urls',
  pages,
  ...(precheckOnly === true && { precheckOnly: true }),
});

Test plan

• API returns opportunityId in acceptance response
• Worker receives opportunityId and can fetch suggestions
• Precheck results are persisted correctly (tested in worker PR)
• No regression in existing assess-urls functionality

Dependencies

• Depends on: spacecat-shared PR feat(slack/backfill-llmo): add llmo-referral-traffic backfill #1449 (adds autofixPrecheckStatus field)
• Related: spacecat-autofix-worker PR (consumes opportunityId and saves results)

Release Order

1. Release spacecat-shared first (new field in data model)
2. Release this PR second - API starts passing opportunityId
3. Release spacecat-autofix-worker PR last (consumes opportunityId and saves to DB)

🤖 Generated with Claude Code

[github-actions]

This PR will trigger a minor release when merged.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[iuliag]

The new field autofixPrecheckStatus is stored on Suggestion but SuggestionDto in this repo is not updated to expose it. If any consumer (UI, reporting) needs to read this field via the API, a DTO update and endpoint change will be needed later. Depends on what was the intended outcome.

[iuliag]

This new test duplicates assertions already present in the updated existing test above and adds value only in its additional expect(payload).to.include({...}) assertion (which checks three fields together).
Consider either removing the duplicate by merging the two tests or making the new test genuinely distinct.

[solaris007]

Hey @danielbatica,

Strengths

• Clean, focused diff - adds opportunityId to the SQS payload and response, nothing more.
• Correct use of the established conditional spread pattern for precheckOnly (suggestions.js:984).
• Existing tests updated to verify opportunityId in both the response body and SQS payload (suggestions.test.js:3973,3980).
• CI is passing.

Issues

Important (Should Fix)

1. OpenAPI spec contradicts the code change
The spec at docs/openapi/site-opportunities.yaml describes the assess-urls flow as intentionally omitting opportunityId. The code now sends it, but the spec still says the opposite. This was a deliberate design decision documented recently. The spec needs to be updated in this PR, and the PR description should explain what changed that invalidates the original rationale.

2. Deleted design comment without replacement
suggestions.js:976: The removed comment "Intentionally omit opportunityId: worker uses context differently for URL-based assessments" was a deliberate architectural note. It's been silently removed without explaining why the design changed. Replace with a brief note (e.g., // opportunityId needed for precheck result persistence on Suggestion).

3. Incomplete feature chain - no downstream consumer
This PR sends opportunityId to the worker, and #1449 adds the storage field, but the autofix worker currently has no handler that reads opportunityId from the assess-urls message and writes to autofixPrecheckStatus. If a worker PR exists or is planned, please link to it. If these are intentional prep work, say so explicitly.

4. SuggestionDto not updated
As @iuliag noted, autofixPrecheckStatus is stored on Suggestion but SuggestionDto does not expose it. If any consumer (UI, reporting) needs to read precheck results via the API, a DTO update will be needed.

Minor (Nice to Have)

5. Duplicative test
suggestions.test.js:3997-4022: The new test "passes opportunityId to worker for precheck result persistence" is nearly identical to the existing test above it (updated at lines 3971-3984). Both send the same request and verify opportunityId in the payload. Either remove the duplicate or differentiate the scenario.

Recommendations

• Update the OpenAPI spec to reflect the new behavior and explain the design change.
• Document the release ordering explicitly: shared first, API second, worker third. Link all three PRs.
• Ensure the worker PR handles missing opportunityId gracefully in case deploys get reordered.

Assessment

Ready to merge? No

The OpenAPI spec contradicts the code change, creating a contract inconsistency. The feature chain is incomplete without a corresponding worker PR. Also blocked on #1449 (schema change) which has failing CI.

Next Steps

1. Update the OpenAPI spec to match the new behavior.
2. Replace the deleted design comment with updated reasoning.
3. Link to the worker PR that completes the feature chain.
4. Wait for #1449 to pass CI and merge before releasing this.