4.5 KiB
前后端通信约定
当前后端是相邻的 hono-api 仓库，默认根地址 http://localhost:3000。业务接口由 Hono 提供，认证由 Better Auth 提供；旧 opencloud-backend FastAPI 项目不参与当前调用。
职责
| 层 | 文件 | 负责内容 |
|---|---|---|
| HTTP 传输 | src/lib/api.ts |
Cookie、查询编码、JSON/FormData、HTTP 错误和 401 事件 |
| 业务调用 | src/features/{clouds,profile,admin}/api.ts |
资源路径、输入/输出类型、批量分块、分页收集、响应适配 |
| 响应适配 | src/lib/api-adapters.ts |
生成 DTO 到前端视图模型的明确映射，图片 URL |
| 后端契约 | src/types/api-contract.ts |
从后端 schema 生成并同步，禁止手改 |
| 前端模型 | src/types/models.ts、src/types/view-models.ts |
页面需要的 Cloud、CloudType、Profile、CloudDetail、AuthUser |
| 认证客户端 | src/features/auth/authClient.ts |
Better Auth SDK 与其独立错误协议 |
| 页面与 store | src/features/ |
交互、缓存、业务展示；调用业务 API 模块 |
页面不再直接调用 apiRequest；ESLint 会检查该规则。传输层不引用云图/用户模型，也不承担认证 SDK 的职责。后端数据库命名、HTTP 字段命名和页面显示字段各自有明确适配位置。稀有度统一使用后端数值，不再伪造 common 分类。
请求与响应
apiRequest 的路径相对于后端根地址，如 /clouds，不要加入 /api/v1。查询条件通过 query 对象传入，由传输层编码一次。JSON body 是普通对象，上传模块接受类型化参数并构建 FormData，浏览器生成 multipart Content-Type。
所有请求携带 Cookie。auth: false 表示该公开请求的 401 不触发清空登录状态，并不禁止携带 Cookie。需要登录的请求默认派发 opencloud:auth-expired。传输层不会重试写操作；网络错误、非法成功响应及结构化 HTTP 错误会抛给调用者。
业务错误为 {message, issues?}，保存在 ApiError.message/status/detail。成功 JSON 响应必须能解析；204 返回 undefined。图片 URL 直接用于媒体元素，不通过 JSON 请求函数。
云图分页使用 {items, page, page_size, has_more}。页面通过 has_more 控制下一页；热力图、点赞集合与当前管理统计需要完整集合时，由业务 API 使用 collectPages 收集。地图为上限 1000 条的时间范围数组，用户管理与云类型目录目前为非分页数组。没有实时订阅或跨页快照。
批量变更每次最多 100 个 UUID。已完成的删除批次立即修补缓存，后续批次失败不会回滚。上传仍逐张进行，失败前已上传的云图保留；没有恢复上传或自动整批重试。
契约同步与验证
后端 src/schemas/ 是单一事实来源。后端生成的 contracts/api.ts 只含 HTTP 类型，不引入数据库、SDK、服务端配置或运行时包。前端保存类型快照，独立构建不依赖旁边存在后端仓库。
两仓库配套修改时：
# 在 hono-api 中
npm run contract:generate
npm run check
# 在 opencloud 中
npm run api:sync
npm run api:check
npm run check
npm run build
后端不在默认位置时，设置 OPENCLOUD_API_DIR 为实际路径。api:check 比较已生成的后端类型与前端快照，不会替代后端的 contract:check；两者都通过才能确认契约一致。前端 npm test 使用 Node 内置测试与 TypeScript 类型剥离，需要 Node 22.18+，不新增测试框架依赖。
部署与迁移
此次改动需要两端一起发布或回滚。旧路径 /cloud、/profile、/image、/info/cloudtype 改为 /clouds、/profiles、/images、/cloud-types；旧请求字段 type_id/user_name/user_role 改为 cloud_type_id/username/role。云图响应使用 cloud_type/review_status，日期统一 ISO UTC，批量 ID 为字符串数组。
认证仍在 /auth/*，VITE_API_URL 仍为后端根地址。完整端点与迁移表在后端 API.md。本次不需要数据库迁移，TypeScript 字段改名显式映射原数据库列。