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/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/{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/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 }
      responses:
        '200':
          description: OK

  /api/v1/ask/threads/{id}/messages:
    post:
      tags: [ask]
      summary: 发送消息（扣额度）
      parameters:
        - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [content]
              properties:
                content: { type: string }
      responses:
        '200':
          description: assistant 回复

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

  /api/v1/moods:
    post:
      tags: [companion]
      summary: 心情记录（P2 可完善）
      responses:
        '200':
          description: OK

  /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 }