openapi: 3.0.3
info:
  title: YuXinGu API
  version: 0.2.0
  description: |
    愈心谷 P1 API 契约（冻结草案）。
    用户可见文案遵循 .ai/product/lexicon.md。
    统一信封：{ code, message, data }；code=0 成功。
servers:
  - url: http://127.0.0.1:8080
tags:
  - name: system
  - name: profile
  - name: portrait
  - name: scale
  - name: relation
  - name: report
  - name: ask
  - name: companion
  - name: commerce

paths:
  /api/v1/healthz:
    get:
      tags: [system]
      summary: Liveness
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'

  /api/v1/ping:
    get:
      tags: [system]
      summary: Ping
      responses:
        '200':
          description: OK

  /api/v1/profiles:
    get:
      tags: [profile]
      summary: 列出个人档案
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
    post:
      tags: [profile]
      summary: 创建个人档案
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProfileRequest'
      responses:
        '200':
          description: OK

  /api/v1/profiles/{id}:
    patch:
      tags: [profile]
      summary: 更新个人档案
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: OK
    delete:
      tags: [profile]
      summary: 删除个人档案
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: OK

  /api/v1/reports/portrait:
    post:
      tags: [portrait]
      summary: 生成个人画像成长报告
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profile_id]
              properties:
                profile_id: { type: string, format: uuid }
      responses:
        '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]
      summary: 生成关系理解
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profile_a_id, profile_b_id]
              properties:
                profile_a_id: { type: string, format: uuid }
                profile_b_id: { type: string, format: uuid }
      responses:
        '200':
          description: RelationInsight + 可选 report_id

  /api/v1/reports:
    get:
      tags: [report]
      summary: 列出当前用户成长报告
      responses:
        '200':
          description: OK

  /api/v1/reports/{id}:
    get:
      tags: [report]
      summary: 获取成长报告（权益裁剪）
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: OK

  /api/v1/scales:
    get:
      tags: [scale]
      summary: 探索测试列表
      responses:
        '200':
          description: OK

  /api/v1/scales/{slug}:
    get:
      tags: [scale]
      summary: 探索测试题目
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK

  /api/v1/scales/{slug}/result:
    post:
      tags: [scale]
      summary: 提交探索测试并计分
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profile_id, answers]
              properties:
                profile_id: { type: string, format: uuid }
                answers: { type: object }
      responses:
        '200':
          description: 探索结果

  /api/v1/ask/quota:
    get:
      tags: [ask]
      summary: 当前问答剩余次数（免费额度或成长会员）
      responses:
        '200':
          description: OK

  /api/v1/ask/threads:
    post:
      tags: [ask]
      summary: 创建问答线程（须绑定 profile）
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              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: 发送消息（扣额度；P1 规则引擎回复）
      parameters:
        - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [content]
              properties:
                content: { type: string }
      responses:
        '200':
          description: user + assistant + quota
        '402':
          description: 额度用尽

  /api/v1/solar-terms/today:
    get:
      tags: [companion]
      summary: 今日节气生活建议
      responses:
        '200':
          description: OK

  /api/v1/moods:
    post:
      tags: [companion]
      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: Mood

  /api/v1/moods/today:
    get:
      tags: [companion]
      summary: 今日心情
      responses:
        '200':
          description: '{ mood: Mood | null }'

  /api/v1/membership/me:
    get:
      tags: [commerce]
      summary: 当前成长会员权益
      responses:
        '200':
          description: OK

  /api/v1/orders:
    post:
      tags: [commerce]
      summary: 创建订单（membership | deep_access）
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '200':
          description: OK

  /api/v1/orders/{id}/pay-mock:
    post:
      tags: [commerce]
      summary: 模拟支付成功
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: OK

components:
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema: { type: string, format: uuid }

  schemas:
    Envelope:
      type: object
      required: [code, message]
      properties:
        code: { type: integer, example: 0 }
        message: { type: string, example: success }
        data: { type: object }

    CreateProfileRequest:
      type: object
      required: [relation, birth_date]
      properties:
        relation: { type: string, enum: [self, other] }
        display_name: { type: string }
        birth_date: { type: string, format: date }
        birth_time: { type: string, nullable: true }
        birth_place: { type: string, nullable: true }
        gender: { type: string, nullable: true }
        relation_type: { type: string, nullable: true }

    CreateOrderRequest:
      type: object
      required: [kind]
      properties:
        kind: { type: string, enum: [membership, deep_access] }
        plan: { type: string, description: month|quarter|year when membership }
        report_id: { type: string, format: uuid, description: when deep_access }