fix: 修复后端代码违规并更新协议文档

- 修复 notifications 模块 datetime.now() 缺少时区问题 - 用 ApiProblemError 替换 BaseService 中的 HTTPException - 更新协议文档：添加错误码、繁体字段、邀请相关协议 - 升级 Docker 镜像版本
2026-04-16 10:51:08 +08:00
parent aea514a9b5
commit 443c0c80ae
12 changed files with 113 additions and 17 deletions
@@ -36,6 +36,11 @@ Gateway error codes from `backend/src/v1/auth/gateway.py`:
 - `AUTH_VERIFICATION_CODE_INVALID`
 - `AUTH_REFRESH_TOKEN_INVALID`
 - `AUTH_REFRESH_TOKEN_MISSING`
+- `AUTH_USER_NOT_FOUND`
+
+Authorization error codes from `backend/src/v1/users/dependencies.py`:
+
+- `AUTH_UNAUTHORIZED`

 ## Frontend route mapping

@@ -83,6 +83,12 @@ This document is the source of truth for backend RFC7807 `code` values consumed
 |---|---:|---|---|
 | `NOTIFICATION_NOT_FOUND` | 404 | Notification not found or not owned by current user | Show not-found message and refresh list |

+## Invite
+
+| code | status | meaning | frontend handling |
+|---|---:|---|---|
+| `INVITE_CODE_NOT_FOUND` | 404 | Invite code not found for current user | Show not-found message and trigger invite code bootstrap |
+
 ## Global

 | code | status | meaning | frontend handling |
@@ -39,12 +39,15 @@ Protocol verification status:
 ### profiles

 - PK: `id` (`auth.users.id`, `on delete cascade`)
- Core fields: `username`, `avatar_url`, `bio`, `settings`, `created_at`, `updated_at`, `deleted_at`
+- Core fields: `username`, `avatar_url`, `bio`, `settings`, `referred_by`, `created_at`, `updated_at`, `deleted_at`
 - Constraints:
  - `username` not empty
 - Indexes:
  - `ix_profiles_username`
  - `ix_profiles_settings_gin`
+- Notes:
+  - `referred_by` is FK to `profiles.id` (`on delete set null`) for invite/referral tracking
+  - `settings` stores `ProfileSettingsV1` JSON including `preferences`, `privacy`, `notification`, `divination_tutorial`

 ### user_points

@@ -161,9 +161,11 @@ During run streaming, backend emits standard AG-UI lifecycle events and two divi
  "binaryCode": "101001",
  "changedBinaryCode": "100001",
  "guaName": "山火贲",
+  "guaNameHant": "山火賁",
  "upperName": "艮",
  "lowerName": "离",
  "targetGuaName": "山雷颐",
+  "targetGuaNameHant": "山雷頤",
  "worldPosition": 1,
  "responsePosition": 4,
  "hasChangingYao": true,
@@ -192,7 +194,9 @@ During run streaming, backend emits standard AG-UI lifecycle events and two divi
    {
      "position": 1,
      "spiritName": "虎",
+      "spiritNameHant": "虎",
      "relationName": "官鬼",
+      "relationNameHant": "官鬼",
      "tiganName": "卯",
      "elementName": "木",
      "isYang": true,
@@ -206,13 +210,27 @@ During run streaming, backend emits standard AG-UI lifecycle events and two divi
    {
      "position": 2,
      "relationName": "父母",
+      "relationNameHant": "父母",
      "tiganName": "午",
      "elementName": "火"
    }
-  ]
+  ],
+  "specialStatus": [],
+  "interactions": [],
+  "timeEffect": [],
+  "riChenZhangSheng": []
 }
 ```

+Field notes:
+
+- `guaNameHant`, `targetGuaNameHant`: Traditional Chinese variants for卦名.
+- `spiritNameHant`, `relationNameHant`: Traditional Chinese variants for六神/六亲 names.
+- `specialStatus`: Special hexagram status indicators.
+- `interactions`: 爻位 interaction descriptions.
+- `timeEffect`: Time-based effect descriptions.
+- `riChenZhangSheng`: 日辰长生相关 information.
+
 ### 2) `TEXT_MESSAGE_END`

 - Standard final answer event.
@@ -0,0 +1,49 @@
+# Invite Protocol (Frontend <-> Backend)
+
+This document defines the invite code contract for authenticated users.
+
+Protocol verification status:
+
+- Backend route source: `backend/src/v1/invite/router.py`
+- Backend service source: `backend/src/v1/invite/service.py`
+- Backend schema source: `backend/src/v1/invite/schemas.py`
+- Frontend mapping source: `apps/lib/features/settings/data/apis/invite_api.dart`
+
+## Compatibility strategy
+
+- Additive evolution only.
+- Existing response fields are stable and must remain backward-compatible.
+
+## Route
+
+### GET /api/v1/invite/me
+
+Get the current user's invite code information.
+
+**Authorization**: Requires authenticated session. User identity from JWT `sub`.
+
+**Response (200)**:
+
+```json
+{
+  "code": "ABC123XYZ",
+  "used_count": 5
+}
+```
+
+Field rules:
+
+- `code`: string, unique invite code assigned to the user
+- `used_count`: integer `>= 0`, number of times this code has been used
+
+## Error contract linkage
+
+- RFC7807 + extension `code`, optional `params`.
+- Shared registry: `docs/protocols/common/http-error-codes.md`.
+- Error codes for this feature:
+  - `INVITE_CODE_NOT_FOUND` (404): Invite code not found for current user
+
+## Data model linkage
+
+- Invite codes are stored in `invite_codes` table.
+- See `docs/protocols/common/user-points-chat-data-protocol.md` for `profiles.referred_by` field.
@@ -82,15 +82,15 @@ Field rules:
 - `count`: integer `>= 0`
 - Counts only notifications where `notifications.status = 'published'` and `notifications.deleted_at IS NULL`

-### PATCH /api/v1/notifications/{id}/read
+### PATCH /api/v1/notifications/{notification_id}/read

 Mark a single notification as read. Idempotent.

-**Authorization**: Requires authenticated session. `id` must belong to the current user's `user_notifications`.
+**Authorization**: Requires authenticated session. `notification_id` must belong to the current user's `user_notifications`.

 **Path parameters**:

- `id`: UUID of the `user_notifications` record
+- `notification_id`: UUID of the `user_notifications` record

 **Response (200)**:

@@ -109,6 +109,11 @@ Request:
    "notification": {
      "allow_notifications": true,
      "allow_vibration": true
+    },
+    "divination_tutorial": {
+      "divination_entry_shown": false,
+      "auto_divination_shown": false,
+      "manual_divination_shown": false
    }
  }
 }
@@ -118,6 +123,7 @@ Rules:

 - `settings` must conform to `ProfileSettingsV1`.
 - Additional fields are forbidden.
+- `divination_tutorial` tracks user's tutorial completion state for divination flows.

 Response: