docs(api): document existing insurance contracts

[cristim]

Document the existing insurance status and plan-wide comparison endpoints, including their bearer/API-key authentication alternatives, permission/account scope, response shapes and sanitized errors. Add passive schemas for the recommendation DTOs already serialized internally; no recommendation query or new HTTP operation is exposed.

The schema contracts preserve exact decimal text, emitted required keys, nullable amounts, flat financial totals and disclosures. A known-issue record tracks the two preexisting OpenAPI structural errors as #1075; this PR does not repair unrelated schemas.

Validation on the reviewed source:

• Actual production DTO output from retained tests: 19 payloads, 51 top-level tests and 73 passing events, no failures/skips.
• Checked 62 comparison and 31 recommendation properties, 89 required-field deletion controls, 38 nullable controls, date/decimal/type negatives and 442 internal references.
• The real local docs handler served exactly the edited YAML bytes.
• Full-document diagnostics retain the same two baseline errors. Seventeen warnings comprise the original sixteen plus one explained unused-component warning for the intentionally passive recommendation schema. The whole existing spec is not claimed valid.
• Both independent reviewers completed two adversarial passes and reviewed final runtime evidence. The authentication omission found during review was corrected and re-reviewed; reviewers did not rerun the tests.
• Normal commit hooks passed, with unrelated file-type checks skipped.

This is a documentation predecessor for #799, not complete recommendation integration or live vendor acceptance. No live vendor call, purchase, deployment or runtime permission change was performed. Platform merge remains held pending direct authorization for existing automatic dev-deployment side effects.

Refs #799, #1075.

Summary by CodeRabbit

• New Features
  • Added authenticated, read-only insurance status and comparison endpoints. The status reports whether required configuration is present; the comparison returns plan details when configuration is available.
  • Added API documentation for comparison results, including financial totals, offer details, and alternatives.
• Documentation
  • Recorded known OpenAPI validation issues that remain unresolved.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: LeanerCloud/cloud-commitments-platform/.coderabbit.yaml
• Review profile: CHILL
• Plan: Essentials
• Run ID: 9c240d21-8522-4cf7-885f-3807d4a028e2

📥 Commits

Reviewing files that changed from the base of the PR and between 8caed39 and f3d3459.

📒 Files selected for processing: 2

• internal/api/openapi.yaml
• known_issues/38_openapi_contract.md

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

📝 Walkthrough

The OpenAPI specification adds authenticated insurance status and plan-comparison endpoints, response schemas, and internal recommendation-comparison DTO schemas. A new audit entry records existing OpenAPI dialect-validation errors.

Changes: Insurance API

Layer / File(s)	Summary
Response contracts internal/api/openapi.yaml, known_issues/38_openapi_contract.md	Adds status and comparison response schemas for configuration, financial values, offers, line items, and disclosures. The audit entry records two existing OpenAPI dialect-validation errors and their open status.
Endpoint contracts internal/api/openapi.yaml	Documents authenticated GET operations for insurance status and plan comparison, including access requirements, configuration behavior, and error responses.
Internal recommendation-comparison DTOs internal/api/openapi.yaml	Adds internal DTO schemas for recommendation comparisons, including nullable current offers and candidate figures.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other

Suggested reviewers: iamjsd

Merge Risk: ⚪ Minimal · up to f3d34

No actionable risk introduced by this documentation change remains after normal checks.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly describes the main change: documenting existing insurance API contracts and endpoints.
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (2 skipped: 2 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[cristim]

archera_reviewer_b

APPROVED f3d3459 by archera_reviewer_b

Both adversarial source/proof passes are clean. The exact committed tree and two files match the final validated/served source, with270 additions and a clean worktree. Evidence inspected includes73 passing test events,19 actual payloads,89 deletion controls and nullable/negative checks. The two preexisting structural errors remain unchanged; the additional warning identifies an intentionally passive DTO schema. No tests rerun by this reviewer. CI and platform deployment authorization remain required.

[cristim]

archera_reviewer_a

APPROVED f3d3459 by archera_reviewer_a

Two adversarial source passes and final fix/proof review are clean. Verified commit/tree452de11d6dd6d484d06ab3aa0c5fe73d7a42bbd6, parent and both committed file hashes against reviewed bytes and actual validation receipts. The auth documentation finding was corrected and re-reviewed. Scope:270 additions. Inspected actual DTO payload fingerprints, served-spec equality, required/null/date/decimal controls and retained baseline diagnostics; did not rerun tests. CI and the platform merge/deployment hold remain separate gates.

[cristim]

@coderabbitai full review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

---

Your included review limit is currently reached under our Fair Usage Limits Policy. Your current included review allowance is based on your included PR review attempts over the past 7 days. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 36 minutes.

[cristim]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.