openapi: 3.0.3
info:
  title: Genealogy PC/H5 API
  version: 1.0.0
  description: |
    家谱业务 APP/PC 用户侧接口文档，用于 Apifox 导入。

    导入方式：Apifox -> 导入 API 数据 -> OpenAPI/Swagger -> 选择本文件。

    约定：
    - APP 路径前缀为 `/genealogy/app`
    - PC/H5 路径前缀为 `/genealogy/pc`
    - 后台管理接口不包含在本文件内
    - 登录后接口需要携带 token，且请求 Header 需携带 `clientid`
servers:
  - url: http://127.0.0.1:8080
    description: Local Java backend
  - url: http://127.0.0.1:9527/dev-api
    description: Local frontend proxy
tags:
  - name: 验证中心
    description: 统一验证码、天爱行为验证码和系统图形验证码
  - name: 认证登录
    description: APP/PC 登录注册与账号资料
  - name: 文件上传
    description: APP/PC 统一文件上传与业务引用绑定
  - name: 行政区划
    description: 行政区划
  - name: 家谱
    description: 家谱主体、加入申请与概览
  - name: 家谱成员
    description: 家谱成员
  - name: 字辈谱
    description: 字辈谱
  - name: 世系人物
    description: 世系人物与世系树
  - name: 家族圈
    description: 家族圈动态、点赞、评论
  - name: 内容文章
    description: 谱文、官网文章、帮助、推广
  - name: 相册
    description: 相册与照片
  - name: 祭祀
    description: 祭祀与献礼
  - name: 族务记录
    description: 成长、备忘、亲友、功德等记录
  - name: VIP
    description: VIP 套餐与订单
  - name: 消息通知
    description: 消息通知
  - name: 意见反馈
    description: 意见反馈
security:
  - SaToken: []
paths:
  /captcha/require:
    get:
      tags: [验证中心]
      summary: 查询当前场景是否需要验证
      description: 用于登录、注册、换绑手机等场景。按租户、客户端和场景编码匹配后台验证策略。
      security: []
      parameters:
        - name: tenantId
          description: 租户ID，用于区分不同租户的数据和验证策略
          in: query
          schema:
            type: string
          example: "000000"
        - name: clientId
          description: 客户端ID，对应后台客户端管理中的APP/PC/小程序等终端
          in: query
          schema:
            type: string
          example: 428a8310cd442757ae699df5d894f051
        - name: sceneCode
          description: 验证场景编码，例如APP_LOGIN、PC_LOGIN、APP_REGISTER
          in: query
          required: true
          schema:
            type: string
          example: APP_LOGIN
        - name: subject
          description: 验证主体，通常为手机号、用户ID或登录账号
          in: query
          schema:
            type: string
          example: "13800000000"
      responses:
        '200':
          $ref: '#/components/responses/VerificationRequireResult'
  /captcha/challenge:
    post:
      tags: [验证中心]
      summary: 生成验证挑战
      description: 统一生成验证码。策略为天爱时返回行为验证数据；策略为系统图形时返回 uuid 和 img。
      security: []
      requestBody:
        $ref: '#/components/requestBodies/VerificationChallenge'
      responses:
        '200':
          $ref: '#/components/responses/VerificationChallengeResult'
  /captcha/verify:
    post:
      tags: [验证中心]
      summary: 校验验证结果并换取 validToken
      description: 验证通过后返回 validToken，登录、注册、发短信等业务接口将 validToken 随请求体一起提交。
      security: []
      requestBody:
        $ref: '#/components/requestBodies/VerificationCheck'
      responses:
        '200':
          $ref: '#/components/responses/VerificationCheckResult'
  /auth/code:
    get:
      tags: [验证中心]
      summary: 兼容旧系统图形验证码
      description: 老版后台登录图形验证码入口。新的 APP/PC 业务优先使用 /captcha/require + /captcha/challenge + /captcha/verify。
      security: []
      responses:
        '200':
          $ref: '#/components/responses/LegacyCaptchaResult'
  /genealogy/pc/auth/register:
    post:
      tags: [认证登录]
      summary: PC 用户注册
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/PasswordRegister'
      responses:
        '200':
          $ref: '#/components/responses/LoginResult'
  /genealogy/pc/auth/login:
    post:
      tags: [认证登录]
      summary: PC 密码登录
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/PasswordLogin'
      responses:
        '200':
          $ref: '#/components/responses/LoginResult'
  /genealogy/pc/auth/login/sms:
    post:
      tags: [认证登录]
      summary: PC 短信登录
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/SmsLogin'
      responses:
        '200':
          $ref: '#/components/responses/LoginResult'
  /genealogy/pc/auth/sms/code:
    post:
      tags: [认证登录]
      summary: PC 发送短信验证码
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/SmsCode'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/pc/auth/profile:
    get:
      tags: [认证登录]
      summary: PC 当前用户资料
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
    put:
      tags: [认证登录]
      summary: PC 修改用户资料
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/ProfileUpdate'
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
  /genealogy/pc/auth/password:
    put:
      tags: [认证登录]
      summary: PC 修改密码
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/PasswordChange'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/pc/auth/password/reset:
    put:
      tags: [认证登录]
      summary: PC 找回密码
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/PasswordReset'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/pc/auth/phone:
    put:
      tags: [认证登录]
      summary: PC 换绑手机号
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/PhoneChange'
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
  /genealogy/pc/auth/account/deactivate:
    post:
      tags: [认证登录]
      summary: PC 注销账号
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/AccountDeactivate'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/pc/auth/logout:
    delete:
      tags: [认证登录]
      summary: PC 退出登录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'

  /genealogy/pc/files/upload:
    post:
      tags: [文件上传]
      summary: PC 单文件上传
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/FileUpload'
      responses:
        '200':
          $ref: '#/components/responses/FileUploadResult'
  /genealogy/pc/files/resumable/init:
    post:
      tags: [文件上传]
      summary: PC 分片上传初始化
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/ResumableInit'
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
  /genealogy/pc/files/resumable/chunk:
    post:
      tags: [文件上传]
      summary: PC 上传分片
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/ChunkUpload'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/pc/files/resumable/complete:
    post:
      tags: [文件上传]
      summary: PC 完成分片上传
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/ResumableComplete'
      responses:
        '200':
          $ref: '#/components/responses/FileUploadResult'
  /genealogy/pc/files/reference:
    post:
      tags: [文件上传]
      summary: PC 绑定文件业务引用
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/FileReference'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
    delete:
      tags: [文件上传]
      summary: PC 释放文件业务引用
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/BizTable'
        - $ref: '#/components/parameters/BizId'
        - $ref: '#/components/parameters/BizField'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'

  /genealogy/region/children:
    get:
      tags: [行政区划]
      summary: 查询下级行政区划
      security: []
      parameters:
        - name: parentCode
          description: 父级行政区划编码，不传或传0查省级
          in: query
          required: false
          schema:
            type: string
          example: "51"
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
  /genealogy/region/path/{regionCode}:
    get:
      tags: [行政区划]
      summary: 查询行政区划路径
      security: []
      parameters:
        - $ref: '#/components/parameters/RegionCode'
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
  /genealogy/region/search:
    get:
      tags: [行政区划]
      summary: 搜索行政区划
      security: []
      parameters:
        - name: keyword
          description: 搜索关键词，支持地区名称或编码模糊查询
          in: query
          required: true
          schema:
            type: string
          example: 北京
        - name: level
          description: 行政区划级别，1省、2市、3区县、4乡镇街道、5村社区
          in: query
          required: false
          schema:
            type: integer
          example: 3
        - name: limit
          description: 返回数量上限
          in: query
          required: false
          schema:
            type: integer
          example: 20
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
  /genealogy/region/{regionCode}:
    get:
      tags: [行政区划]
      summary: 查询行政区划详情
      security: []
      parameters:
        - $ref: '#/components/parameters/RegionCode'
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'

components:
  securitySchemes:
    SaToken:
      type: apiKey
      in: header
      name: Authorization
      description: 登录后返回的 token。若本地配置使用 sa-token 名称，请按项目实际 token-name 调整。
  parameters:
    ClientIdHeader:
      name: clientid
      description: 客户端ID，请求Header携带，用于区分APP/PC/小程序等终端
      in: header
      required: true
      schema:
        type: string
      example: 428a8310cd442757ae699df5d894f051
    PageNum:
      name: pageNum
      description: 页码，从1开始
      in: query
      required: false
      schema:
        type: integer
        default: 1
    PageSize:
      name: pageSize
      description: 每页条数
      in: query
      required: false
      schema:
        type: integer
        default: 10
    GenealogyId:
      name: genealogyId
      description: 家谱ID
      in: path
      required: true
      schema:
        type: integer
        format: int64
      example: 900001001
    MemberId:
      name: memberId
      description: 家谱成员ID
      in: path
      required: true
      schema:
        type: integer
        format: int64
    PersonId:
      name: personId
      description: 世系人物ID
      in: path
      required: true
      schema:
        type: integer
        format: int64
    FeedId:
      name: feedId
      description: 家族动态ID
      in: path
      required: true
      schema:
        type: integer
        format: int64
    RegionCode:
      name: regionCode
      description: 行政区划编码
      in: path
      required: true
      schema:
        type: string
      example: "510000"
    BizTable:
      name: bizTable
      description: 业务表名，用于文件引用绑定
      in: query
      required: true
      schema:
        type: string
      example: gen_family_feed
    BizId:
      name: bizId
      description: 业务数据ID，用于文件引用绑定
      in: query
      required: true
      schema:
        type: integer
        format: int64
      example: 900013001
    BizField:
      name: bizField
      description: 业务字段名，例如avatar_oss_id、cover_oss_id
      in: query
      required: true
      schema:
        type: string
      example: media_ids
  requestBodies:
    JsonObject:
      required: true
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    PasswordRegister:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PasswordRegisterBody'
          example:
            grantType: "password"
            tenantId: "000000"
            phone: "13800000000"
            password: "e10adc3949ba59abbe56e057f20f883e"
            nickName: "测试用户"
            registerSource: "app"
            validToken: "captcha-ticket-or-sms-token"
    PasswordLogin:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PasswordLoginBody'
          example:
            grantType: "password"
            tenantId: "000000"
            phone: "13800000000"
            password: "e10adc3949ba59abbe56e057f20f883e"
            validToken: "captcha-ticket"
    SmsLogin:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SmsLoginBody'
          example:
            grantType: "sms"
            tenantId: "000000"
            phone: "13800000000"
            smsCode: "123456"
            validToken: "captcha-ticket"
    SmsCode:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SmsCodeBody'
          example:
            tenantId: "000000"
            phone: "13800000000"
            sceneCode: "APP_LOGIN"
            validToken: "captcha-ticket"
    ProfileUpdate:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProfileUpdateBody'
          example:
            nickName: "张三"
            avatarOssId: 2060000000000000001
            sex: "0"
            birthday: "1990-01-01"
            regionCode: "110101"
            addressDetail: "北京市东城区"
    PasswordChange:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PasswordChangeBody'
          example:
            oldPassword: "e10adc3949ba59abbe56e057f20f883e"
            newPassword: "25d55ad283aa400af464c76d713c07ad"
            validToken: "captcha-ticket"
    PasswordReset:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PasswordResetBody'
          example:
            tenantId: "000000"
            phone: "13800000000"
            smsCode: "123456"
            newPassword: "25d55ad283aa400af464c76d713c07ad"
            validToken: "captcha-ticket"
    PhoneChange:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PhoneChangeBody'
          example:
            newPhone: "13900000000"
            smsCode: "123456"
            validToken: "captcha-ticket"
    AccountDeactivate:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountDeactivateBody'
          example:
            password: "e10adc3949ba59abbe56e057f20f883e"
            reason: "user request"
    FileUpload:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [file]
            properties:
              file:
                type: string
                format: binary
    ChunkUpload:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [uploadId, chunkIndex, chunkMd5, file]
            properties:
              uploadId:
                type: string
              chunkIndex:
                type: integer
                example: 0
              chunkMd5:
                type: string
                example: d41d8cd98f00b204e9800998ecf8427e
              file:
                type: string
                format: binary
    ResumableInit:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResumableInitBody'
          example:
            fileName: "cover.jpg"
            fileSize: 9532
            fileMd5: "d41d8cd98f00b204e9800998ecf8427e"
            contentType: "image/jpeg"
            chunkSize: 4194304
            totalChunks: 1
            bizType: "genealogy"
            usageScene: "cover"
    ResumableComplete:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResumableCompleteBody'
          example:
            uploadId: "UPLOAD202607090001"
            fileMd5: "d41d8cd98f00b204e9800998ecf8427e"
            fileSize: 9532
    FileReference:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FileReferenceBody'
          example:
            bizType: "family_feed"
            bizName: "family feed image"
            bizTable: "gen_family_feed"
            bizId: 900013001
            bizField: "media_oss_ids"
            ossId: 2060000000000000001
            usageScene: "feed_image"
    GenerationPoemBatch:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenerationPoemBatchBody'
          example:
            genealogyId: 900001001
            poemText: "德承家亦\n忠厚传芳"
            disableMissing: false
    LineagePerson:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LineagePersonBody'
          example:
            appUserId: 900000001
            personNo: "P202607090001"
            personName: "彭德明"
            aliasName: "德明"
            sex: "0"
            generationNo: 1
            generationName: "德"
            avatarOssId: 2060000000000000001
            birthDate: "1950-01-01"
            deathDate: null
            introduction: "first generation introduction"
    FamilyFeed:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FamilyFeedBody'
          example:
            content: "今天上传一张老照片。"
            mediaOssIds: "2060000000000000001,2060000000000000002"
            visibility: "1"
            status: "0"
    FamilyFeedComment:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FamilyFeedCommentBody'
          example:
            parentCommentId: null
            replyUserId: null
            content: "这张照片很有年代感。"
    VerificationChallenge:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VerificationChallengeBody'
          example:
            tenantId: "000000"
            clientId: "428a8310cd442757ae699df5d894f051"
            sceneCode: "APP_LOGIN"
            subject: "13800000000"
    VerificationCheck:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VerificationCheckBody'
          examples:
            tianai_behavior:
              summary: 天爱滑块/旋转/滑动还原/文字点选验证
              value:
                tenantId: "000000"
                clientId: "428a8310cd442757ae699df5d894f051"
                sceneCode: "APP_LOGIN"
                subject: "13800000000"
                challengeId: "CAPTCHA_CHALLENGE_ID"
                providerCode: "tianai"
                captchaType: "SLIDER"
                payload:
                  id: "tianai-captcha-id"
                  data:
                    bgImageWidth: 340
                    bgImageHeight: 180
                    startSlidingTime: 1720000000000
                    endSlidingTime: 1720000001500
                    trackList: []
            system_image:
              summary: 系统图形验证码
              value:
                tenantId: "000000"
                clientId: "428a8310cd442757ae699df5d894f051"
                sceneCode: "APP_LOGIN"
                subject: "13800000000"
                challengeId: "CAPTCHA_CHALLENGE_ID"
                providerCode: "ruoyi_image"
                captchaType: "math"
                payload:
                  uuid: "captcha-uuid"
                  code: "6"
  responses:
    VoidResult:
      description: 通用成功响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RVoid'
    ObjectResult:
      description: 通用对象响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RObject'
    ListResult:
      description: 通用列表响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RList'
    PageResult:
      description: 通用分页响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PageResult'
    LoginResult:
      description: 登录结果
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RLogin'
    FileUploadResult:
      description: 文件上传结果
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RFileUpload'
    VerificationRequireResult:
      description: 验证需求查询结果
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RVerificationRequire'
    VerificationChallengeResult:
      description: 验证挑战生成结果
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RVerificationChallenge'
    VerificationCheckResult:
      description: 验证校验结果
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RVerificationCheck'
    LegacyCaptchaResult:
      description: 兼容旧图形验证码结果
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RLegacyCaptcha'
  schemas:
    RVoid:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          nullable: true
    RObject:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          type: object
          additionalProperties: true
    RList:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          type: array
          items:
            type: object
            additionalProperties: true
    PageResult:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        rows:
          description: 分页数据列表
          type: array
          items:
            type: object
            additionalProperties: true
        total:
          type: integer
          example: 0
    RLogin:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/LoginVo'
    RFileUpload:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/FileUploadVo'
    LoginVo:
      type: object
      properties:
        token:
          type: string
        accessToken:
          type: string
        tokenValue:
          type: string
        userId:
          type: integer
          format: int64
        tenantId:
          description: 租户ID，用于区分不同租户的数据和验证策略
          type: string
        clientId:
          description: 客户端ID，对应后台客户端管理中的APP/PC/小程序等终端
          type: string
        clientKey:
          type: string
    FileUploadVo:
      type: object
      properties:
        ossId:
          description: OSS文件ID，表单内部使用，用户侧应通过上传组件获取
          type: integer
          format: int64
        url:
          type: string
        thumbnailUrl:
          type: string
          nullable: true
        fileName:
          description: 原始文件名
          type: string
        originalName:
          type: string
    PasswordRegisterBody:
      type: object
      required: [grantType, tenantId, phone, password]
      properties:
        clientId:
          description: 客户端ID，对应后台客户端管理中的APP/PC/小程序等终端
          type: string
        grantType:
          description: 授权类型，例如password、sms、wechat、apple
          type: string
          example: password
        tenantId:
          description: 租户ID，用于区分不同租户的数据和验证策略
          type: string
          example: "000000"
        phone:
          description: 手机号
          type: string
          example: "13800000000"
        password:
          type: string
          description: 32 位 MD5
          example: e10adc3949ba59abbe56e057f20f883e
        nickName:
          description: 用户昵称
          type: string
        registerSource:
          description: 注册来源，例如APP、PC、H5、MINI_PROGRAM
          type: string
        validToken:
          description: 验证中心通过后返回的票据，用于注册/登录/换绑等二次校验
          type: string
    PasswordLoginBody:
      type: object
      required: [grantType, tenantId, phone, password]
      properties:
        clientId:
          description: 客户端ID，对应后台客户端管理中的APP/PC/小程序等终端
          type: string
        grantType:
          description: 授权类型，例如password、sms、wechat、apple
          type: string
          example: password
        tenantId:
          description: 租户ID，用于区分不同租户的数据和验证策略
          type: string
          example: "000000"
        phone:
          description: 手机号
          type: string
          example: "13800000000"
        password:
          type: string
          description: 32 位 MD5
          example: e10adc3949ba59abbe56e057f20f883e
        validToken:
          description: 验证中心通过后返回的票据，用于注册/登录/换绑等二次校验
          type: string
    SmsLoginBody:
      type: object
      required: [grantType, tenantId, phone, smsCode]
      properties:
        clientId:
          description: 客户端ID，对应后台客户端管理中的APP/PC/小程序等终端
          type: string
        grantType:
          description: 授权类型，例如password、sms、wechat、apple
          type: string
          example: sms
        tenantId:
          description: 租户ID，用于区分不同租户的数据和验证策略
          type: string
          example: "000000"
        phone:
          description: 手机号
          type: string
          example: "13800000000"
        smsCode:
          description: 短信验证码
          type: string
          example: "1234"
    SmsCodeBody:
      type: object
      required: [grantType, tenantId, sceneCode, phone, validToken]
      properties:
        clientId:
          description: 客户端ID，对应后台客户端管理中的APP/PC/小程序等终端
          type: string
        grantType:
          description: 授权类型，例如password、sms、wechat、apple
          type: string
          example: sms
        tenantId:
          description: 租户ID，用于区分不同租户的数据和验证策略
          type: string
          example: "000000"
        sceneCode:
          description: 验证场景编码，例如APP_LOGIN、PC_LOGIN、APP_REGISTER
          type: string
          example: APP_LOGIN
        phone:
          description: 手机号
          type: string
          example: "13800000000"
        validToken:
          description: 验证中心通过后返回的票据，用于注册/登录/换绑等二次校验
          type: string
    ProfileUpdateBody:
      type: object
      properties:
        nickName:
          description: 用户昵称
          type: string
        avatarOssId:
          description: 头像文件OSS ID
          type: integer
          format: int64
        sex:
          description: 性别，建议使用系统字典值
          type: string
        birthday:
          description: 生日，格式 yyyy-MM-dd
          type: string
          format: date
        provinceCode:
          type: string
        cityCode:
          type: string
        districtCode:
          type: string
    PasswordChangeBody:
      type: object
      required: [oldPassword, newPassword]
      properties:
        oldPassword:
          type: string
          description: 32 位 MD5
        newPassword:
          type: string
          description: 32 位 MD5
    PasswordResetBody:
      type: object
      required: [tenantId, phone, smsCode, newPassword]
      properties:
        tenantId:
          description: 租户ID，用于区分不同租户的数据和验证策略
          type: string
          example: "000000"
        phone:
          description: 手机号
          type: string
        smsCode:
          description: 短信验证码
          type: string
        newPassword:
          type: string
          description: 32 位 MD5
        validToken:
          description: 验证中心通过后返回的票据，用于注册/登录/换绑等二次校验
          type: string
    PhoneChangeBody:
      type: object
      required: [newPhone, smsCode]
      properties:
        newPhone:
          type: string
        smsCode:
          description: 短信验证码
          type: string
        validToken:
          description: 验证中心通过后返回的票据，用于注册/登录/换绑等二次校验
          type: string
    AccountDeactivateBody:
      type: object
      required: [password]
      properties:
        password:
          type: string
          description: 32 位 MD5
        reason:
          description: 操作原因或说明
          type: string
    ResumableInitBody:
      type: object
      required: [fileName, fileSize, fileMd5, chunkSize, totalChunks]
      properties:
        fileName:
          description: 原始文件名
          type: string
        fileSize:
          description: 文件大小，单位字节
          type: integer
          format: int64
        fileMd5:
          description: 完整文件MD5，用于秒传和完整性校验
          type: string
        contentType:
          description: 文件MIME类型，例如 image/jpeg、video/mp4
          type: string
        chunkSize:
          description: 单个分片大小，单位字节
          type: integer
          example: 4194304
        totalChunks:
          description: 总分片数
          type: integer
        bizType:
          description: 业务类型，例如avatar、cover、feed_image
          type: string
        usageScene:
          description: 文件使用场景，便于后续引用统计和清理
          type: string
    ResumableCompleteBody:
      type: object
      required: [uploadId, fileMd5, fileSize]
      properties:
        uploadId:
          description: 分片上传任务ID
          type: string
        fileMd5:
          description: 完整文件MD5，用于秒传和完整性校验
          type: string
        fileSize:
          description: 文件大小，单位字节
          type: integer
          format: int64
    FileReferenceBody:
      type: object
      required: [bizType, bizTable, bizId, bizField]
      properties:
        bizType:
          description: 业务类型，例如avatar、cover、feed_image
          type: string
          example: family_feed
        bizName:
          description: 业务名称，用于后台展示文件引用来源
          type: string
          example: 家族圈动态
        bizTable:
          description: 业务表名，用于文件引用绑定
          type: string
          example: gen_family_feed
        bizId:
          description: 业务数据ID，用于文件引用绑定
          type: integer
          format: int64
        bizField:
          description: 业务字段名，例如avatar_oss_id、cover_oss_id
          type: string
          example: media_ids
        ossId:
          description: OSS文件ID，表单内部使用，用户侧应通过上传组件获取
          type: integer
          format: int64
        ossIds:
          type: string
          example: "2060001,2060002"
        usageScene:
          description: 文件使用场景，便于后续引用统计和清理
          type: string
        usageName:
          type: string
    GenerationPoemBatchBody:
      type: object
      properties:
        content:
          type: string
          example: 德承家亦
        stopMissingOldGeneration:
          type: boolean
          example: false
    LineagePersonBody:
      type: object
      properties:
        appUserId:
          type: integer
          format: int64
        personNo:
          type: string
        personName:
          type: string
        aliasName:
          type: string
        sex:
          description: 性别，建议使用系统字典值
          type: string
          example: "0"
        generationNo:
          description: 世代序号
          type: integer
        generationName:
          description: 字辈
          type: string
        avatarOssId:
          description: 头像文件OSS ID
          type: integer
          format: int64
        birthDate:
          type: string
        deathDate:
          type: string
        introduction:
          type: string
    FamilyFeedBody:
      type: object
      properties:
        content:
          type: string
        mediaOssIds:
          description: 媒体文件OSS ID列表，多个用逗号或数组传递以接口约定为准
          type: string
          example: "2060001,2060002"
        visibility:
          description: 可见范围，例如0私密、1公开、2成员可见
          type: string
          example: "1"
        status:
          description: 状态，建议使用对应字典值
          type: string
          example: "0"
    FamilyFeedCommentBody:
      type: object
      required: [content]
      properties:
        parentCommentId:
          type: integer
          format: int64
          nullable: true
        replyUserId:
          type: integer
          format: int64
          nullable: true
        content:
          type: string
    VerificationChallengeBody:
      type: object
      required: [sceneCode]
      properties:
        tenantId:
          type: string
          description: 租户 ID
        clientId:
          type: string
          description: 客户端 ID
        sceneCode:
          type: string
          description: 验证场景编码，如 ADMIN_LOGIN/APP_LOGIN/APP_REGISTER
        subject:
          type: string
          description: 验证主体，如手机号/用户名/IP
      example:
        tenantId: "000000"
        clientId: "428a8310cd442757ae699df5d894f051"
        sceneCode: "APP_LOGIN"
        subject: "13800000000"
    VerificationCheckBody:
      type: object
      required: [sceneCode]
      properties:
        tenantId:
          description: 租户ID，用于区分不同租户的数据和验证策略
          type: string
        clientId:
          description: 客户端ID，对应后台客户端管理中的APP/PC/小程序等终端
          type: string
        sceneCode:
          description: 验证场景编码，例如APP_LOGIN、PC_LOGIN、APP_REGISTER
          type: string
        subject:
          description: 验证主体，通常为手机号、用户ID或登录账号
          type: string
        challengeId:
          description: 验证挑战ID，由验证挑战接口返回
          type: string
        providerCode:
          type: string
          description: 验证服务，tianai 或 ruoyi_image
        captchaType:
          type: string
          description: SLIDER/ROTATE/CONCAT/WORD_IMAGE_CLICK/math/char
        payload:
          type: object
          additionalProperties: true
          description: 前端验证控件返回的轨迹/点击/图形验证码数据
    VerificationRequireVo:
      type: object
      properties:
        required:
          description: 当前场景是否需要验证
          type: boolean
        providerCode:
          description: 第三方服务商编码
          type: string
        captchaType:
          description: 验证码类型，例如SLIDER、ROTATE、CONCAT、WORD_IMAGE_CLICK
          type: string
        sceneCode:
          description: 验证场景编码，例如APP_LOGIN、PC_LOGIN、APP_REGISTER
          type: string
        ttlSeconds:
          description: 验证或票据有效秒数
          type: integer
      example:
        required: true
        providerCode: "tianai"
        captchaType: "SLIDER"
        sceneCode: "APP_LOGIN"
        ttlSeconds: 300
    VerificationChallengeVo:
      type: object
      properties:
        required:
          description: 当前场景是否需要验证
          type: boolean
        providerCode:
          description: 第三方服务商编码
          type: string
        captchaType:
          description: 验证码类型，例如SLIDER、ROTATE、CONCAT、WORD_IMAGE_CLICK
          type: string
        challengeId:
          description: 验证挑战ID，由验证挑战接口返回
          type: string
        uuid:
          type: string
          description: 系统图形验证码 uuid
        img:
          type: string
          description: 系统图形验证码 base64 图片
        payload:
          type: object
          additionalProperties: true
          description: 天爱验证码数据，包括背景图、模板图、尺寸等
        expireSeconds:
          description: 验证挑战过期秒数
          type: integer
      example:
        required: true
        providerCode: "tianai"
        captchaType: "SLIDER"
        challengeId: "CAPTCHA_CHALLENGE_ID"
        payload:
          backgroundImage: "data:image/png;base64,..."
          templateImage: "data:image/png;base64,..."
          backgroundImageWidth: 340
          backgroundImageHeight: 180
        expireSeconds: 300
    VerificationCheckVo:
      type: object
      properties:
        passed:
          description: 验证是否通过
          type: boolean
        validToken:
          type: string
          description: 验证通过后交给业务接口的票据
        expireSeconds:
          description: 验证挑战过期秒数
          type: integer
        message:
          description: 返回消息
          type: string
      example:
        passed: true
        validToken: "captcha-ticket"
        expireSeconds: 300
        message: "验证通过"
    LegacyCaptchaVo:
      type: object
      properties:
        captchaEnabled:
          type: boolean
        uuid:
          description: 系统图形验证码UUID
          type: string
        img:
          type: string
          description: base64 图形验证码
      example:
        captchaEnabled: true
        uuid: "captcha-uuid"
        img: "data:image/png;base64,..."
    RVerificationRequire:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: "操作成功"
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/VerificationRequireVo'
    RVerificationChallenge:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: "操作成功"
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/VerificationChallengeVo'
    RVerificationCheck:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: "操作成功"
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/VerificationCheckVo'
    RLegacyCaptcha:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: "操作成功"
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/LegacyCaptchaVo'