openapi: 3.0.3
info:
  title: 无烟打卡 V2 API
  version: 0.1.0
  description: 戒烟小程序 V2 后端接口文档，覆盖打卡、复吸、梦想目标、统计、海报和资料管理。
servers:
  - url: https://wx.nepiedg.top
    description: 生产环境
  - url: http://127.0.0.1:8080
    description: 本地开发环境
tags:
  - name: QuitCheckin
    description: 无烟打卡 V2 接口
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: session_key
  schemas:
    Response:
      type: object
      properties:
        code:
          type: integer
          example: 200
        message:
          type: string
          example: success
        data:
          nullable: true
    UpsertProfileRequest:
      type: object
      properties:
        quit_start_date:
          type: string
          format: date
        pack_price_cent:
          type: integer
        baseline_cigs_per_day:
          type: integer
        motivation:
          type: string
        notify_time:
          type: string
          example: "21:00"
    CheckinRequest:
      type: object
      properties:
        date:
          type: string
          format: date
        note:
          type: string
    RelapseRequest:
      type: object
      required: [relapse_num]
      properties:
        date:
          type: string
          format: date
        relapse_at:
          type: string
          format: date-time
        relapse_num:
          type: integer
          minimum: 1
          maximum: 200
        reason:
          type: string
        note:
          type: string
    RewardGoalCreateRequest:
      type: object
      required: [title, target_amount_cent]
      properties:
        title:
          type: string
        target_amount_cent:
          type: integer
        cover_image:
          type: string
    RewardGoalUpdateRequest:
      type: object
      properties:
        title:
          type: string
        target_amount_cent:
          type: integer
        cover_image:
          type: string
        status:
          type: string
          enum: [active, completed, archived]
    PosterGenerateRequest:
      type: object
      properties:
        template_code:
          type: string
        show_fields:
          type: array
          items:
            type: string
            enum: [streak_days, saved_money_cent, avoided_cigs, health_recovery_percent]
paths:
  /api/v2/profile:
    get:
      tags: [QuitCheckin]
      summary: 获取无烟打卡资料
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
    post:
      tags: [QuitCheckin]
      summary: 保存无烟打卡资料
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpsertProfileRequest"
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
  /api/v2/checkin/home:
    get:
      tags: [QuitCheckin]
      summary: 获取首页数据
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
  /api/v2/checkin/check:
    post:
      tags: [QuitCheckin]
      summary: 今日打卡
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CheckinRequest"
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
        "409":
          description: 当日已复吸，不允许再打卡
  /api/v2/checkin/relapse:
    post:
      tags: [QuitCheckin]
      summary: 记录复吸
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RelapseRequest"
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
        "409":
          description: 当日已是复吸状态
  /api/v2/stats/overview:
    get:
      tags: [QuitCheckin]
      summary: 获取统计概览
      security: [{ bearerAuth: [] }]
      parameters:
        - in: query
          name: range
          schema:
            type: string
            enum: [week, month, year]
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
  /api/v2/badges:
    get:
      tags: [QuitCheckin]
      summary: 获取勋章列表
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
  /api/v2/relapses:
    get:
      tags: [QuitCheckin]
      summary: 获取复吸历史
      security: [{ bearerAuth: [] }]
      parameters:
        - in: query
          name: page
          schema:
            type: integer
        - in: query
          name: page_size
          schema:
            type: integer
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
  /api/v2/reward-goals:
    get:
      tags: [QuitCheckin]
      summary: 获取梦想目标列表
      security: [{ bearerAuth: [] }]
      parameters:
        - in: query
          name: status
          schema:
            type: string
            enum: [active, completed, archived, all]
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
    post:
      tags: [QuitCheckin]
      summary: 创建梦想目标
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RewardGoalCreateRequest"
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
  /api/v2/reward-goals/{id}:
    put:
      tags: [QuitCheckin]
      summary: 更新梦想目标
      security: [{ bearerAuth: [] }]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RewardGoalUpdateRequest"
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
  /api/v2/poster/data:
    get:
      tags: [QuitCheckin]
      summary: 获取海报数据
      security: [{ bearerAuth: [] }]
      parameters:
        - in: query
          name: template_code
          schema:
            type: string
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
  /api/v2/poster/generate:
    post:
      tags: [QuitCheckin]
      summary: 生成海报
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PosterGenerateRequest"
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"