feat: P1 合盘/星座/问答与测测完整设计包及模拟器取证工具

落地 synastry/star/ask API 与 H5 页面，补齐 cece-frontend-re complete-design 证据文档，并加入 Android 模拟器截图抓取脚本。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-03 11:37:53 +08:00
parent 15a9db374a
commit bd22d9dddd
248 changed files with 26309 additions and 842 deletions
@@ -99,6 +99,236 @@ paths:
        '200':
          description: 返回 GrowthReport（detail 按权益裁剪）

+  /api/v1/explore/catalog:
+    get:
+      tags: [explore]
+      summary: 探索三级目录（L1 分类 → L3 工具）
+      responses:
+        '200':
+          description: categories[]
+
+  /api/v1/explore/catalog/{key}:
+    get:
+      tags: [explore]
+      summary: 单个探索分类
+      parameters:
+        - name: key
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: Category
+        '404':
+          description: not found
+
+  /api/v1/growth/plans:
+    get:
+      tags: [growth]
+      summary: 成长计划列表
+      responses:
+        '200':
+          description: OK
+    post:
+      tags: [growth]
+      summary: 创建成长计划
+      responses:
+        '200':
+          description: OK
+
+  /api/v1/growth/plans/{id}/checkin:
+    post:
+      tags: [growth]
+      summary: 今日打卡
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: OK
+
+  /api/v1/growth/plans/{id}/checkins:
+    get:
+      tags: [growth]
+      summary: 打卡记录
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: OK
+
+  /api/v1/moods/recent:
+    get:
+      tags: [companion]
+      summary: 近七日心情轨迹
+      responses:
+        '200':
+          description: OK
+
+  /api/v1/reports/star:
+    post:
+      tags: [star]
+      summary: 生成本命排盘 / 运势成长报告
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [profile_id]
+              properties:
+                profile_id: { type: string, format: uuid }
+      responses:
+        '200':
+          description: GrowthReport type=star（含 chart/planets/aspects_preview/fortune/transits）
+
+  /api/v1/reports/synastry:
+    post:
+      tags: [star]
+      summary: 生成双人合盘报告（五主盘 + 次限推运）
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [profile_id_a, profile_id_b]
+              properties:
+                profile_id_a: { type: string, format: uuid }
+                profile_id_b: { type: string, format: uuid }
+                as_of: { type: string, format: date, description: 次限推运日期 YYYY-MM-DD }
+      responses:
+        '200':
+          description: GrowthReport type=synastry（三指数 + charts 五主盘/推运）
+
+  /api/v1/synastry/nearby:
+    get:
+      tags: [star]
+      summary: 附近可合盘档案
+      parameters:
+        - in: query
+          name: lat
+          required: true
+          schema: { type: number }
+        - in: query
+          name: lng
+          required: true
+          schema: { type: number }
+        - in: query
+          name: radius_km
+          schema: { type: number, default: 50 }
+      responses:
+        '200':
+          description: items[{profile, distance_km}]
+
+  /api/v1/synastry/invites:
+    post:
+      tags: [star]
+      summary: 创建合盘邀请
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [profile_id]
+              properties:
+                profile_id: { type: string, format: uuid }
+      responses:
+        '200':
+          description: token / path / expires_at
+
+  /api/v1/synastry/invites/{token}:
+    get:
+      tags: [star]
+      summary: 邀请元数据
+      parameters:
+        - in: path
+          name: token
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: host_name / expires_at / already_accepted
+
+  /api/v1/synastry/invites/{token}/accept:
+    post:
+      tags: [star]
+      summary: 接受合盘邀请并生成报告
+      parameters:
+        - in: path
+          name: token
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [birth_date]
+              properties:
+                display_name: { type: string }
+                birth_date: { type: string, format: date }
+                birth_time: { type: string }
+                birth_place: { type: string }
+      responses:
+        '200':
+          description: GrowthReport type=synastry
+
+  /api/v1/reports/rhythm:
+    post:
+      tags: [rhythm]
+      summary: 生成身心节律成长报告
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [profile_id]
+              properties:
+                profile_id: { type: string, format: uuid }
+      responses:
+        '200':
+          description: GrowthReport type=rhythm
+
+  /api/v1/image-cards/scenes:
+    get:
+      tags: [image-card]
+      summary: 意象卡片场景列表
+      responses:
+        '200':
+          description: OK
+
+  /api/v1/image-cards/quota:
+    get:
+      tags: [image-card]
+      summary: 今日抽卡剩余次数
+      responses:
+        '200':
+          description: OK
+
+  /api/v1/image-cards/draw:
+    post:
+      tags: [image-card]
+      summary: 抽意象卡片（沉淀为 GrowthReport type=image_card）
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [profile_id]
+              properties:
+                profile_id: { type: string, format: uuid }
+                scene: { type: string }
+                depth: { type: boolean, description: 请求三卡组合（无权益则 detail 剥离） }
+      responses:
+        '200':
+          description: report + cards + quota_left
+        '402':
+          description: 免费次数用尽
+
  /api/v1/relation/insight:
    post:
      tags: [relation]
@@ -117,6 +347,14 @@ paths:
        '200':
          description: RelationInsight + 可选 report_id

+  /api/v1/reports:
+    get:
+      tags: [report]
+      summary: 列出当前用户成长报告
+      responses:
+        '200':
+          description: OK
+
  /api/v1/reports/{id}:
    get:
      tags: [report]
@@ -171,6 +409,14 @@ paths:
        '200':
          description: 探索结果

+  /api/v1/ask/quota:
+    get:
+      tags: [ask]
+      summary: 当前问答剩余次数（免费额度或成长会员）
+      responses:
+        '200':
+          description: OK
+
  /api/v1/ask/threads:
    post:
      tags: [ask]
@@ -184,14 +430,23 @@ paths:
              required: [profile_id]
              properties:
                profile_id: { type: string, format: uuid }
+                scene: { type: string, description: self|relation|career|emotion|life }
      responses:
        '200':
          description: OK

  /api/v1/ask/threads/{id}/messages:
+    get:
+      tags: [ask]
+      summary: 拉取线程消息历史
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: OK
    post:
      tags: [ask]
-      summary: 发送消息（扣额度）
+      summary: 发送消息（扣额度；P1 规则引擎回复）
      parameters:
        - $ref: '#/components/parameters/Id'
      requestBody:
@@ -205,7 +460,9 @@ paths:
                content: { type: string }
      responses:
        '200':
-          description: assistant 回复
+          description: user + assistant + quota
+        '402':
+          description: 额度用尽

  /api/v1/solar-terms/today:
    get:
@@ -218,10 +475,28 @@ paths:
  /api/v1/moods:
    post:
      tags: [companion]
-      summary: 心情记录（P2 可完善）
+      summary: 记录/更新当日心情
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                score: { type: integer, minimum: 1, maximum: 5 }
+                note: { type: string, maxLength: 200 }
+                day: { type: string, format: date }
      responses:
        '200':
-          description: OK
+          description: Mood
+
+  /api/v1/moods/today:
+    get:
+      tags: [companion]
+      summary: 今日心情
+      responses:
+        '200':
+          description: '{ mood: Mood | null }'

  /api/v1/membership/me:
    get: