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

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
@@ -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