openapi: 3.0.3
info:
  title: CFC 后台 API - 家庭优惠券特性契约
  description: |
    家庭管理列表新增 couponCount 回填；统一优惠券页（Tabs：模板管理/发放记录/使用记录/转赠记录）复用既有 coupon 端点。
    变更范围：POST /api/admin/families 响应新增 couponCount；其余端点为复用，无契约破坏。
  version: 1.0.0
servers:
  - url: /api
paths:
  /admin/families:
    post:
      summary: 家庭分页列表（含 couponCount 回填）
      operationId: getFamilies
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                page: { type: integer, default: 1 }
                size: { type: integer, default: 10 }
                name: { type: string, description: 家庭名称模糊搜索 }
                sort:
                  type: array
                  items:
                    type: object
                    properties:
                      prop: { type: string }
                      order: { type: string, enum: [asc, desc] }
      responses:
        '200':
          description: 家庭分页
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyPage'
  /admin/coupon/list:
    post:
      summary: 优惠券模板分页列表（统一页-模板管理 Tab）
      operationId: couponList
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                page: { type: integer, default: 1 }
                size: { type: integer, default: 20 }
                keyword: { type: string }
      responses:
        '200':
          description: 模板分页
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponPage'
  /admin/coupon/grant-log:
    post:
      summary: 发券流水（统一页-发放记录 Tab，支持 familyId 过滤）
      operationId: couponGrantLog
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                familyId: { type: integer }
                couponId: { type: integer }
                grantType: { type: string }
                source: { type: string }
      responses:
        '200':
          description: 发券流水列表（含 familyName）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantLogList'
  /admin/coupon/family-coupon-usage:
    post:
      summary: 家庭券使用记录（统一页-使用记录 Tab，支持 familyId 过滤）
      operationId: couponUsage
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                familyId: { type: integer }
                page: { type: integer, default: 1 }
                size: { type: integer, default: 20 }
      responses:
        '200':
          description: 使用记录分页
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponUsagePage'
  /admin/coupon/gift-transfers:
    post:
      summary: 会员券转赠记录（统一页-转赠记录 Tab，支持赠送方/接收方家庭过滤）
      operationId: couponGiftTransfers
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                giverFamilyId: { type: integer }
                receiverFamilyId: { type: integer }
                status: { type: string, enum: [GIFTED, USED, REVOKED] }
                couponId: { type: integer }
                page: { type: integer, default: 1 }
                size: { type: integer, default: 20 }
      responses:
        '200':
          description: 转赠记录分页
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GiftTransferPage'
components:
  schemas:
    ApiResult:
      type: object
      required: [code, data]
      properties:
        code: { type: integer, description: 0=成功, 非0=错误码 }
        data: {}
        message: { type: string }
    Family:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        inviteCode: { type: string }
        memberCount: { type: integer }
        reportCount: { type: integer }
        planCount: { type: integer }
        taskCount: { type: integer }
        couponCount:
          type: integer
          description: 新增：该家庭在 family_coupon 表的记录数
    FamilyPage:
      allOf:
        - $ref: '#/components/schemas/ApiResult'
        - type: object
          properties:
            data:
              type: object
              properties:
                records:
                  type: array
                  items:
                    $ref: '#/components/schemas/Family'
                total: { type: integer }
                current: { type: integer }
                size: { type: integer }
    Coupon:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        type: { type: string, enum: [FIXED, DISCOUNT] }
        value: { type: integer }
        discountRate: { type: integer }
        minSpend: { type: integer }
        applicableTo: { type: string }
        status: { type: string, enum: [ACTIVE, DISABLED] }
    CouponPage:
      allOf:
        - $ref: '#/components/schemas/ApiResult'
        - type: object
          properties:
            data:
              type: object
              properties:
                records:
                  type: array
                  items:
                    $ref: '#/components/schemas/Coupon'
                total: { type: integer }
    GrantLog:
      type: object
      properties:
        id: { type: integer }
        familyId: { type: integer }
        couponId: { type: integer }
        grantType: { type: string }
        period: { type: string }
        quantity: { type: integer }
        source: { type: string }
        createdAt: { type: string, format: date-time }
        familyName: { type: string }
    GrantLogList:
      allOf:
        - $ref: '#/components/schemas/ApiResult'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/GrantLog'
    CouponUsageItem:
      type: object
      properties:
        id: { type: integer }
        familyId: { type: integer }
        couponId: { type: integer }
        usedAt: { type: string, format: date-time }
        orderId: { type: integer }
        name: { type: string }
        type: { type: string }
        value: { type: integer }
        discountRate: { type: integer }
        minSpend: { type: integer }
    CouponUsagePage:
      allOf:
        - $ref: '#/components/schemas/ApiResult'
        - type: object
          properties:
            data:
              type: object
              properties:
                records:
                  type: array
                  items:
                    $ref: '#/components/schemas/CouponUsageItem'
                total: { type: integer }
    GiftTransferItem:
      type: object
      properties:
        id: { type: integer }
        giverFamilyId: { type: integer }
        receiverFamilyId: { type: integer }
        couponId: { type: integer }
        status: { type: string }
        createdAt: { type: string, format: date-time }
    GiftTransferPage:
      allOf:
        - $ref: '#/components/schemas/ApiResult'
        - type: object
          properties:
            data:
              type: object
              properties:
                records:
                  type: array
                  items:
                    $ref: '#/components/schemas/GiftTransferItem'
                total: { type: integer }
                current: { type: integer }
                size: { type: integer }