docs: 整理 runtime 系列文档,修正 API 端点名称

This commit is contained in:
qzl
2026-03-02 10:55:46 +08:00
parent c3192a2431
commit 2ac56e5084
9 changed files with 350 additions and 172 deletions
+28 -5
View File
@@ -35,10 +35,22 @@ docker compose --env-file .env -f infra/docker/docker-compose.yml up -d
### Step 2: 执行迁移与初始化
#### 生产环境
```bash
docker compose --env-file .env -f infra/docker/docker-compose.yml run --rm --build init-job bootstrap
docker compose --env-file .env -f infra/docker/docker-compose.yml run --rm --build init-job uv run python -m core.runtime.cli bootstrap
```
#### 开发环境(推荐)
开发阶段推荐使用脚本,直接使用本地代码,无需构建镜像:
```bash
bash infra/scripts/dev-migrate.sh bootstrap
```
可选命令:
- `bash infra/scripts/dev-migrate.sh migrate` - 仅运行迁移
- `bash infra/scripts/dev-migrate.sh init-data` - 仅初始化数据
通过标准:命令退出码为 0,日志中无 migration/init-data 错误。
### Step 3: 版本核对(建议)
@@ -120,20 +132,29 @@ curl -sS -X POST "${WEB_BASE_URL}/api/v1/auth/login" \
```bash
# signup start
curl -sS -X POST "${WEB_BASE_URL}/api/v1/auth/signup/start" \
curl -sS -X POST "${WEB_BASE_URL}/api/v1/auth/verifications" \
-H 'Content-Type: application/json' \
-d '{"username":"demo","email":"demo@example.com","password":"secret123"}'
# signup verify
curl -sS -X POST "${WEB_BASE_URL}/api/v1/auth/signup/verify" \
curl -sS -X POST "${WEB_BASE_URL}/api/v1/auth/verifications/verify" \
-H 'Content-Type: application/json' \
-d '{"email":"demo@example.com","token":"123456"}'
# signup resend
curl -sS -X POST "${WEB_BASE_URL}/api/v1/auth/verifications/resend" \
-H 'Content-Type: application/json' \
-d '{"email":"demo@example.com"}'
# profile patch
curl -sS -X PATCH "${WEB_BASE_URL}/api/v1/profile/me" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer <access_token>" \
-d '{"username":"demo2","bio":"hello"}'
# profile get
curl -sS "${WEB_BASE_URL}/api/v1/profile/me" \
-H "Authorization: Bearer <access_token>"
```
通过标准:接口返回符合预期的 2xx 或受控业务错误,无 5xx。
@@ -145,7 +166,7 @@ PYTHONPATH=backend/src uv run pytest backend/tests/unit -k agent_chat -q
PYTHONPATH=backend/src uv run pytest backend/tests/integration -k agent_chat -q
PYTHONPATH=backend/src uv run pytest backend/tests/e2e/test_agent_chat_flow.py backend/tests/e2e/test_agent_chat_recent_session_home.py -q
curl -sS -X POST "${WEB_BASE_URL}/api/v1/agent-chat/run" \
curl -sS -X POST "${WEB_BASE_URL}/api/v1/agent-chat" \
-H 'Content-Type: application/json' \
-d '{"message":"hello"}'
```
@@ -204,7 +225,7 @@ docker compose --env-file .env -f infra/docker/docker-compose.yml up -d --force-
- 复核标准:
- `docker inspect supabase-auth` 能看到 `GOTRUE_MAILER_TEMPLATES_CONFIRMATION/RECOVERY`
- `supabase-mail-templates` 挂载源为 `infra/mail-templates`
- `POST /api/v1/auth/signup/start` 返回 `202` 且耗时恢复正常。
- `POST /api/v1/auth/verifications` 返回 `202` 且耗时恢复正常。
---
@@ -246,3 +267,5 @@ docker compose --env-file .env -f infra/docker/docker-compose.yml up -d --force-
| 2026-02-25 | 新增配置漂移故障条目:修复 Auth 邮件模板失效与 signup 超时场景 |
| 2026-02-27 | 用户搜索支持邮箱精确匹配:query 含 @ 符号时走 auth.users → profiles 两步查询 |
| 2026-02-28 | 邀请码功能:新增 invite_codes 表、profiles.referred_by,注册时可选填邀请码并记录邀请关系 |
| 2026-03-02 | 文档整理:修正 auth 端点名称(/verifications)、补充 profile 路由文档、修复 L2/L3 验证命令 |
| 2026-03-02 | 修正 bootstrap 命令:init-job 需要使用 `uv run python -m core.runtime.cli bootstrap` |