qzl/eryao
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新 HTTP 错误码、用户积分、占卜运行及用户资料协议文档

Browse Source
This commit is contained in:
qzl
2026-04-10 16:45:45 +08:00
parent 1bc8bc6a27
commit 17ef460391
78 changed files with 18680 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/protocols/common/http-error-codes.md
+41 -6
View File
@@ -12,6 +12,7 @@ This document is the source of truth for backend RFC7807 `code` values consumed
| `AUTH_REFRESH_TOKEN_INVALID` | 401 | Invalid/expired refresh token | Clear local session and return login |
| `AUTH_REFRESH_TOKEN_MISSING` | 401 | Refresh token missing on logout | Treat as local logout and clear session |
| `AUTH_USER_NOT_FOUND` | 404 | User not found | Show not-found message where applicable |
| `AUTH_UNAUTHORIZED` | 401 | Missing or invalid auth credentials | Force logout and redirect to login |
## Agent Points
@@ -23,16 +24,41 @@ This document is the source of truth for backend RFC7807 `code` values consumed
| code | status | meaning | frontend handling |
|---|---:|---|---|
| `AGENT_SESSION_RUN_LIMIT_EXCEEDED` | 409 | Session already reached max run count (start + 1 follow-up) | Show run-limit message and require starting a new session |
| `AGENT_SESSION_RUN_LIMIT_EXCEEDED` | 409 | Session already reached max message count (2 user messages per session: initial divination + 1 follow-up) | Show run-limit message and require starting a new session |
| `AGENT_RUNTIME_MODE_INVALID` | 422 | Missing or invalid `forwardedProps.runtime_mode` in run request | Show invalid-request message and retry from current page |
| `AGENT_DIVINATION_PAYLOAD_REQUIRED` | 422 | Missing required `forwardedProps.divinationPayload` in run request | Prompt user to restart casting flow and resubmit |
| `AGENT_OUTPUT_DIVINATION_INVALID` | 422 | Worker output contains invalid `divination_derived` payload shape | Show generic history parse error and suggest retrying latest run |
| `AGENT_SESSION_ID_INVALID` | 422 | Invalid session/thread id format | Show invalid-session message and force refresh history |
| `AGENT_SESSION_NOT_FOUND` | 404 | Session does not exist (including follow-up on non-existing thread) | Show session-not-found message and refresh history |
| `AGENT_USER_ID_INVALID` | 422 | Invalid user id in request context | Show invalid-request message |
| `AGENT_AUDIO_UNSUPPORTED_FORMAT` | 400 | Audio format is not accepted by transcribe endpoint | Show format hint and ask user to retry with wav audio |
| `AGENT_AUDIO_TOO_LARGE` | 400 | Audio file exceeds transcribe size limit | Show size-limit message and ask user to shorten audio |
| `AGENT_AUDIO_EMPTY` | 400 | Uploaded audio payload is empty | Show retry hint and keep input unchanged |
| `AGENT_ASR_UNAVAILABLE` | 502 | Upstream ASR service unavailable | Show retry message and allow fallback to text input |
| `AGENT_PAYLOAD_INVALID` | 422 | Parsed run input payload is invalid | Show invalid-request message and retry from current page |
| `AGENT_RUN_INPUT_INVALID` | 422 | Run request body fails validation | Show invalid-request message and retry |
| `AGENT_RUN_MESSAGES_INVALID` | 422 | Run request messages contract violation | Show invalid-request message and retry |
| `AGENT_INVALID_RUN_ID` | 422 | Invalid or missing `runId` query parameter | Show invalid-request message and retry |
| `AGENT_INVALID_LAST_EVENT_ID` | 422 | Invalid `Last-Event-ID` header format | Retry without the header |
| `AGENT_SSE_CONNECTION_LIMIT` | 429 | Too many concurrent SSE connections per user | Show connection-limit message and reduce concurrent streams |
| `AGENT_FORBIDDEN` | 403 | User does not own the session resource | Force refresh and show unauthorized message |
| `AGENT_ATTACHMENT_EMPTY` | 422 | Uploaded attachment payload is empty | Show retry hint and keep input unchanged |
| `AGENT_ATTACHMENT_TOO_LARGE` | 413 | Attachment file exceeds size limit | Show size-limit message and ask user to use smaller file |
| `AGENT_ATTACHMENTS_TOO_MANY` | 422 | Too many attachments in single message | Show attachment limit message |
| `AGENT_ATTACHMENT_UNSUPPORTED_TYPE` | 422 | Attachment mime type is not supported | Show unsupported type message |
| `AGENT_ATTACHMENT_UPLOAD_FAILED` | 502 | Backend failed to upload attachment to storage | Show retry toast |
| `AGENT_ATTACHMENT_STORAGE_UNAVAILABLE` | 503 | Attachment storage service unavailable | Show retry message |
| `AGENT_ATTACHMENT_BUCKET_INVALID` | 422 | Attachment bucket name is invalid | Show generic error and force refresh |
| `AGENT_ATTACHMENT_PATH_SCOPE_INVALID` | 422 | Attachment path does not belong to user scope | Show generic security error and force refresh |
| `AGENT_SIGNED_URL_GENERATION_FAILED` | 502 | Backend failed to generate attachment signed URL | Show retry toast |
| `AGENT_SIGNED_IMAGE_URL_INVALID` | 422 | Signed image URL is invalid or expired | Show error and retry image load |
## Agent Internal (Binary URL Validation)
| code | status | meaning | frontend handling |
|---|---:|---|---|
| `INVALID_BINARY_URL_HOST` | 422 | Binary URL host is not allowed | Show error and retry |
| `INVALID_BINARY_URL_BUCKET` | 422 | Binary URL bucket name is invalid | Show error and retry |
| `INVALID_BINARY_URL_PATH_SCOPE` | 422 | Binary URL path does not belong to allowed scope | Show error and retry |
## Profile
@@ -51,8 +77,17 @@ This document is the source of truth for backend RFC7807 `code` values consumed
| `AVATAR_SIGNED_URL_FAILED` | 502 | Backend failed to generate avatar signed upload URL | Show retry toast and keep previous avatar |
| `AVATAR_UPLOAD_FAILED` | 502 | Backend failed to upload avatar bytes to storage | Show retry toast and keep previous avatar |
Compatibility strategy:
## Global
- Additive changes only for new codes.
- Existing codes must keep semantic meaning.
- Frontend must map by `code`, not by `detail` text.
| code | status | meaning | frontend handling |
|---|---:|---|---|
| `REQUEST_VALIDATION_ERROR` | 422 | Request validation failed | Show invalid-request message |
| `INTERNAL_ERROR` | 500 | Unexpected internal server error | Show generic error and allow retry |
## Tool (Internal Agent Runtime)
| code | status | meaning | frontend handling |
|---|---:|---|---|
| `MISSING_RUNTIME_ARGS` | 500 | Tool call missing required runtime arguments | Show error and retry |
| `TOOL_REJECTED` | 403 | Tool execution was rejected | Show tool rejection message |
| `TOOL_PENDING_APPROVAL` | 202 | Tool execution awaiting approval | Show pending approval state |
docs/protocols/common/user-points-chat-data-protocol.md
+8 -10
View File
@@ -4,9 +4,9 @@ This protocol defines the canonical data contract for user profile, points accou
Protocol verification status:
- Last audited migration: `backend/alembic/versions/20260410_0005_add_points_audit_and_register_bonus_claims.py`
- Last audited migration: `backend/alembic/versions/20260411_0003_points_audit_and_register_bonus_claims.py`
- Last audited models: `backend/src/models/profile.py`, `backend/src/models/user_points.py`, `backend/src/models/points_ledger.py`, `backend/src/models/points_audit_ledger.py`, `backend/src/models/register_bonus_claims.py`, `backend/src/models/agent_chat_session.py`, `backend/src/models/agent_chat_message.py`
- Current status: partially aligned (register bonus still runs in DB trigger, audit ledger tables are additive and ready)
- Current status: aligned with register bonus moved to application service
## Scope
@@ -139,16 +139,14 @@ JSON constraints:
- `grant`: no extra metadata shape requirement
- `adjust`: requires `ext.ticket_id` non-empty
## Signup initialization contract (current + target)
## Signup initialization contract
- Current trigger:
- Trigger: `auth.users` after insert
- DB trigger (`auth.users` after insert):
- Function: `public.initialize_profile_and_invite_code_on_signup()`
- Side effects include profile init + invite code init + register points (currently fixed to 60)
- Target migration:
- remove register points grant from DB trigger
- grant register bonus in application service with eligibility ledger `register_bonus_claims`
- keep trigger focused on profile/invite initialization only
- Side effects: profile init + invite code init
- Application service (in `POST /auth/email-session`):
- `grant_register_bonus_if_eligible()` grants register bonus via `register_bonus_claims` ledger
- Bonus amount from `config.points_policy.register_bonus_points`
### sessions