feat(web): generate and consume API types from OpenAPI

[liujuanjuan1984]

背景

从 OpenAPI 契约生成并消费 TypeScript 类型，收紧 Web 网络边界与后端响应契约的一致性。#255 已合并，本 PR 直接消费其定义的响应契约所生成的类型。

Closes #226

实现

• 采用 openapi-typescript 7.13：只生成类型，支持 OpenAPI 3，不引入新的请求 runtime、重试或状态管理。
• 新增 npm run api:generate，直接导入本地 FastAPI app，确定性导出 web/openapi.json 并生成 web/src/services/api/generated/schema.ts。
• 契约文件策略：web/openapi.json 是生成的中间产物，加入 .gitignore 不入库（本地运行 npm run api:generate 即可生成查看）；入库的只有 schema.ts，两者都禁止手工编辑。
• 生成过程不启动服务器、不连接数据库，也不依赖个人配置；当前覆盖 77 条路径、119 个 operation、157 个 schema。
• 新增 npm run api:check drift 检查：重新生成契约后对比入库的 schema.ts，过期即失败；已接入 scripts/web_validate.sh。
• 将 web/src/services/api/ 的主要资源模块迁移到生成的 request/response 类型；保留现有 fetch runtime 和缓存行为。
• 通过 Pick、Omit、交叉类型和显式 adapter 隔离传输 DTO 与前端 view model。
• 更新 Web 开发文档，说明生成时机、命令和提交要求。

有意保留的手写类型

以下类型属于前端 UI/domain，而不是后端传输契约：

• 查询筛选与规范化参数，例如 task selector、task list、habit action 和 timelog advanced search；
• 表单草稿和前端批量操作组合，例如 anniversary 草稿、vision experience rate 和 note batch/bulk 模型；
• UI 聚合与投影，例如 note stats、分页 view model 和 error bus；
• 当前没有对应后端 endpoint 的前端本地编排模型。

迁移中显式化的契约边界

• planned event 的 extra_data 是前端草稿字段，后端 create/update 不接收；adapter 在发送前明确剥离。
• task 的 person_ids 不属于当前 TaskCreate/TaskUpdate；adapter 在传输边界明确剥离。
• timelog 的前端扩展字段与关联 note 是 view model；发送 payload 时只保留生成契约允许的字段。
• tag selector/full response、person compact response 等不同响应形状现在分别由生成类型约束。

本 PR 不改变 API payload、endpoint、缓存 key 或请求 runtime。

CI 修复与验证

• 已合并最新 main（deps: bump fastapi from 0.140.7 to 0.141.1 in the uv-all-updates group across 1 directory #253、chore: update repository organization metadata #254、feat(web): define explicit API response contracts #255），并修复 Validate Frontend 失败：
  • openapi-typescript 引入的 @redocly/openapi-core 依赖存在漏洞的 js-yaml 4.3.0，导致 npm audit --audit-level=high 失败；通过 web/package.json overrides 固定 js-yaml 4.3.1（与 fix(web): upgrade js-yaml to 4.3.1 for CVE-2026-59870 #268 一致）解决。
  • api:check 需要 uv 导出后端 OpenAPI 文档，但前端 CI 任务只安装了 Node；在 .github/workflows/validate.yml 的 frontend job 中补充 Python、uv 与 uv sync --extra web --frozen。
  • 为避免生成中间产物进入版本控制，web/openapi.json 已加入 .gitignore，drift 检查只对比入库的 schema.ts。
• 最新 CI 运行（head 35f3806）全部通过：Validate Frontend、Validate Default Toolchain、Validate Runtime Matrix（Python 3.10/3.11/3.12）、Validate CLI Integration (PostgreSQL)。
• bash ./scripts/web_validate.sh：通过（npm ci、audit、api:check drift、i18n、build、lint，86 个测试文件 / 302 个测试）。