HTTP API reference

共享操作 schema

HTTP/oRPC 输入必须复用业务操作 schema。文档应解释字段含义，而不是为 HTTP 单独发明另一套业务语义。

后端默认在 /api/openapi.json 提供 OpenAPI 3.1 文档，在 /api/reference 提供 Scalar 交互式 API reference。

公共文档站点也会在 /docs/reference/openapi/ 生成 OpenAPI reference 页面，并把每个 operation 展开到独立页面。

OpenAPI operations 会按 Appaloft 业务 domain 标记 tag，避免 Scalar 和生成文档只显示平铺路由列表。

这些入口由内置 OpenAPI Reference 系统插件注册。需要嵌入到其他 Bun/Elysia 服务时，可以 import @appaloft/openapi 并把它导出的 Response handler 挂到自己的路由上。

API 调用方需要通过公开 query 或 read model 观察异步状态，而不是检查数据库或内部运行时对象。

错误文档应包含稳定 code、category、是否可重试、用户下一步操作，以及相关 troubleshooting 页面。

OpenAPI、oRPC 和未来工具描述应该指向 public docs anchor，而不是内部 spec 文件。