feat: capture guidance_markdown + feedback_subject_id on backoffice reviews

[tathagat2241]

Summary

Extends the Backoffice review-capture endpoint for the Learning Agent feedback loop (SITES-43974) to persist two new fields, and consumes the companion @adobe/spacecat-shared-data-access release so they round-trip on read.

• guidanceMarkdown — AI-generated issue context (title + description). Validated as a string, 64 KB cap (413 on overflow), secret-scrubbed + HTML-sanitised via redactFeedbackContent, stored as guidance_markdown.
• feedbackSubjectId — SpaceCat-internal per-issue grouping key (e.g. a CWV issue id). Validated as a string ≤ 200 chars, stored as feedback_subject_id. Lets the Backoffice group per-issue "previous feedback" when issues share one suggestionId.

⚠️ Deploy order: depends on mysticat-data-service #790 (the feedback_event columns) being migrated first.

Changes

• src/controllers/suggestions.js (createBackofficeReview): accept + validate + scrub + store guidanceMarkdown and feedbackSubjectId on the inserted row.
• src/support/feedback-redaction.js: secret-scrub guidanceMarkdown alongside the other content fields (defence-in-depth — guidance can quote customer HTML/config even though it's AI-generated).
• OpenAPI: request body (site-opportunities.yaml) documents both fields; SuggestionReview response (schemas.yaml) adds feedbackSubjectId + guidanceMarkdown, typed as a [string, 'null'] union (OAS 3.1) so the schema matches the runtime (null for whole-suggestion reviews / absent guidance).
• package.json / lockfile: bump @adobe/spacecat-shared-data-access to the released version so toReviewView returns the new fields on ?include=reviews (and repin off the gist tarball to the published registry version).
• Tests: capture happy-paths + validation (400 non-string, 413 oversize) for both fields; redaction test for guidanceMarkdown; read-response test asserting ?include=reviews returns feedbackSubjectId and ?include=reviews,patches returns guidanceMarkdown.

Testing

Controller + redaction unit tests pass; npm run docs:lint valid; lint clean. Full suite runs in CI.

Please ensure your pull request adheres to the following guidelines:

• make sure to link the related issues in this description. Or if there's no issue created, make sure you describe here the problem you're solving.
• when merging / squashing, make sure the fixed issue references are visible in the commits, for easy compilation of release notes

If the PR is changing the API specification:

• make sure you add a "Not implemented yet" note the endpoint description, if the implementation is not ready yet. Ideally, return a 501 status code with a message explaining the feature is not implemented yet.
• make sure you add at least one example of the request and response.

If the PR is changing the API implementation or an entity exposed through the API:

• make sure you update the API specification and the examples to reflect the changes.

If the PR is introducing a new audit type:

• make sure you update the API specification with the type, schema of the audit result and an example

Related Issues

Jira: https://jira.corp.adobe.com/browse/SITES-43974

Thanks for contributing!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ramboz]

Summary

The capture validation, redaction, tests, and additive API shape are solid. I left two non-blocking inline comments: consume the companion shared-data-access release before advertising its response fields, and make the nullable OpenAPI types match runtime.

The PR description should also be updated—it currently describes the database migration PR rather than this API change—and should state that the database migration must deploy first.

Verdict

Ready to merge: Yes
Reasoning: No blocker-level findings; the implementation paths are covered and CI is green.

For a deeper dedicated security pass, consider invoking /adobe-security-foundations followed by /adobe-security-lang.

[absarasw]

The capture side is clean — extraction, type + size validation (400/413), sanitisation via redactFeedbackContent, and snake_case insert all line up. 6 new tests cover happy paths, non-string bodies, and both size caps. guidance_markdown picking up the same sanitizeMarkdown + scrubString treatment as detail_markdown is honest defence-in-depth (guidance can quote customer HTML/config even though it's AI-generated).

Cross-repo alignment against the DB (#790) + shared (#1809) is on the money: 64 KB cap on guidance_markdown matches the app-layer bound the migration documents; the snake_case row keys match the columns; the OpenAPI schema descriptions match the semantics on both ends.

Two cross-repo flags to close before this PR is fully wired end-to-end. Neither is new to this commit — both are follow-ups the batch already anticipates:

1. Shared dep bump is a required follow-up. This PR captures guidanceMarkdown + feedbackSubjectId on write, but the READ path (getReviewsForSuggestion → toReviewView) uses the currently-pinned @adobe/spacecat-shared-data-access, which doesn't yet return those fields. Until a follow-up PR bumps the dep to the version #1809 publishes, ?include=reviews will silently drop both fields, and the Backoffice per-issue filter in #338 will match nothing (its own "known limitation"). Track the bump PR.

2. Gist-tarball pin carryover. package.json still points @adobe/spacecat-shared-data-access at https://gist.github.com/tathagat2241/…/*.tgz from the earlier round — this is Mihir's cross-repo X4 still unresolved. Repin from the gist URL to the published registry version in the same follow-up bump PR — kills the supply-chain concern permanently.

Minor observation: feedback_subject_id has no character-set validation (length only). UUIDs pass; any 200-char string is accepted. Fine given the field is opaque server-side and only round-trips to the same UI that generated it — flagging in case a second producer ever writes directly.

Not blocking on my side. Approve-worthy in shape, marking COMMENT only so the follow-up-bump story stays visible in the review trail.

[github-actions]

This PR will trigger a minor release when merged.

[solaris007]

🎉 This PR is included in version 1.654.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀