feat: establish Orbit models, migrations and development baseline

This commit is contained in:
2026-09-17 07:04:21 +08:00
commit 4f2935e36f
84 changed files with 4915 additions and 0 deletions

45
docs/api/health.md Normal file
View File

@@ -0,0 +1,45 @@
# 健康检查接口
状态:已实现,基础阶段。无需鉴权;默认仅监听 `127.0.0.1:8080`。
## GET /health/live
返回进程 HTTP 服务是否存活,不访问数据库。
```sh
curl -i http://127.0.0.1:8080/health/live
```
HTTP 200,`Content-Type: application/json`:
```json
{"status":"alive"}
```
## GET /health/ready
检查数据库连接和迁移记录是否与当前二进制的版本、校验和一致且没有 dirty 标记。内部检查最多 2 秒。
```sh
curl -i http://127.0.0.1:8080/health/ready
```
通过时 HTTP 200:
```json
{"status":"ready","scope":"database_and_schema"}
```
数据库不可用、迁移缺失、记录被修改或存在 dirty 标记时 HTTP 503:
```json
{"status":"not_ready"}
```
响应不包含 DSN、数据库错误文本或凭据。检查迁移记录不能发现所有人工 DDL 漂移,运行账户权限和迁移流程仍需受控。
## SDK 与运行限制
对应 `Client.Liveness(ctx)` 和 `Client.Readiness(ctx)`,见 [SDK 接入](../sdk/README.md)。HTTP 503 返回 `*orbit.HTTPError`。
此阶段的 ready 只表示数据库与迁移基础可用;尚无任务、Worker、流程或业务鉴权服务。SDK 默认请求超时为 10 秒,调用方可通过 context 设置更短期限。