[cg8-5712]

Closes #54

变更内容

• 对全部 11 个已注册端点显式标注会话认证；公共端点使用空 security，受保护端点使用 bearerAuth。
• 明确全局角色、案件成员角色和 learner/admin 的实际访问边界，并为案件数据补充字段可见性与处理约束。
• 在 API 文档导航和说明中加入机器可读的 OpenAPI 契约入口。

验收对应

• OpenAPI 仅描述当前已注册的 11 个端点，并逐端点列出认证、角色、错误响应和字段可见性。
• 与 docs/API.md、现有前端请求/响应类型及服务端路由、授权和字段裁剪逻辑完成核对。
• 未将未实现的规划接口或真实搜救数据写入文档。

测试与质量检查

• PyYAML 解析和自定义契约校验：确认 11 个操作、显式 security、角色元数据和数据分级。
• Markdown OpenAPI 链接检查与 git diff --check。
• npm run test:backend：编译阶段因工作盘空间不足（os error 112）中止，未执行到测试用例；已删除本次生成的隔离 target 目录。

风险与边界

• 仅修改文档和机器可读契约说明，不改变服务端认证、授权、隐私裁剪或数据处理行为。

Summary by CodeRabbit

• 文档
  • 新增并完善机器可读 API 契约文档，覆盖已注册接口。
  • 补充接口认证要求、角色权限、数据分类、错误响应及字段可见性说明。
  • 明确敏感数据、案件受限数据与公开数据的访问约束。
  • 更新文档导航，方便查阅 OpenAPI 规范。

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

OpenAPI 契约对齐

Layer / File(s)	Summary
契约说明与阅读约定 docs/API.md, docs/README.md, docs/openapi.yaml	新增机器可读契约导航、覆盖范围说明，以及认证、角色限制、数据分类和缓存约定。
账户与公共接口授权元数据 docs/openapi.yaml	为健康检查、登录、当前用户和登出接口明确安全声明、角色列表及账户数据分类。
案件接口与字段可见性元数据 docs/openapi.yaml	为案件和线索操作补充认证、角色及案件角色限制，并完善敏感字段、位置字段和审核时间字段说明。

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: copilot

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	与 #54 相关的 docs/openapi.yaml 和 docs/API.md 已更新，但未见前端 API 类型、错误码或角色权限表同步。	补齐前端 API 类型、错误码、角色权限表和演示文档的同步，并在 OpenAPI 中逐项确认认证、角色、错误响应与隐私裁剪。

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	标题简洁且准确概括了本次对 OpenAPI 访问契约的澄清。
Out of Scope Changes check	✅ Passed	仅涉及文档与 OpenAPI 契约澄清，没有明显引入无关代码或额外范围变更。
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/issue-54-openapi-contract

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/API.md`:
- Around line 9-10: 更新 docs/API.md 中关于 GET /api/health 的接口描述，使其明确包含失败场景的非 2xx
响应及对应 schema；如果错误由代理层统一处理，则收窄“每个 operation 都显式列出错误响应”的概括表述并注明该边界。

In `@docs/openapi.yaml`:
- Line 225: 将 docs/openapi.yaml 中该字段的 x-data-classification 值改为仅包含机器可读分类值
case-restricted，移除分号及其后的自然语言说明；如需保留敏感字段说明，移至独立的描述字段。

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ce2658f9-34d7-42b2-97d3-0069768b3099

📥 Commits

Reviewing files that changed from the base of the PR and between 4cf6aae and 5f70c4e.

📒 Files selected for processing (3)

• docs/API.md
• docs/README.md
• docs/openapi.yaml

[coderabbitai]

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

保持 x-data-classification 为单一机器可读值。

阅读约定将该字段定义为分类值，但这里把分类和自然语言说明拼成了一个字符串。严格匹配 case-restricted 的客户端可能将其识别为未知分类，从而跳过隐私裁剪或缓存限制。

建议修改

-      x-data-classification: case-restricted; elder_profile.health_notes is sensitive
+      x-data-classification: case-restricted

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	x-data-classification: case-restricted; elder_profile.health_notes is sensitive
	x-data-classification: case-restricted

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/openapi.yaml` at line 225, 将 docs/openapi.yaml 中该字段的
x-data-classification 值改为仅包含机器可读分类值
case-restricted，移除分号及其后的自然语言说明；如需保留敏感字段说明，移至独立的描述字段。