jiapuapp/APP.openapi.yaml

openapi: 3.0.1
info:
  title: APP
  description: |
    家谱业务 APP/PC 用户侧接口文档，用于 Apifox 导入。

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

    约定：
    - APP 路径前缀为 `/genealogy/app`
    - PC/H5 路径前缀为 `/genealogy/pc`
    - 后台管理接口不包含在本文件内
    - 登录后接口需要携带 token，且请求 Header 需携带 `clientid`
  version: 1.0.0
tags:
  - name: 验证中心
  - name: 认证登录
  - name: 文件上传
  - name: 行政区划
  - name: 家谱
  - name: 家谱成员
  - name: 字辈谱
  - name: 世系人物
  - name: 家族圈
  - name: 内容文章
  - name: 相册
  - name: 祭祀
  - name: 族务记录
  - name: 消息通知
  - name: 意见反馈
  - name: VIP
  - name: 视频
paths:
  /captcha/require:
    get:
      summary: 查询当前场景是否需要验证
      deprecated: false
      description: 用于登录、注册、换绑手机等场景。按租户、客户端和场景编码匹配后台验证策略。
      tags:
        - 验证中心
      parameters:
        - name: tenantId
          in: query
          description: 租户ID，用于区分不同租户的数据和验证策略
          required: false
          example: '000000'
          schema:
            type: string
        - name: clientId
          in: query
          description: 客户端ID，对应后台客户端管理中的APP/PC/小程序等终端
          required: false
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
        - name: sceneCode
          in: query
          description: APP 短信场景编码，例如APP_SMS_LOGIN、APP_REGISTER
          required: true
          example: APP_SMS_LOGIN
          schema:
            type: string
        - name: subject
          in: query
          description: 验证主体，通常为手机号、用户ID或登录账号
          required: false
          example: '13800000000'
          schema:
            type: string
        - name: clientid
          in: header
          description: 客户端ID
          example: ced7e5f0498645c6ec642dcf450b036f
          schema:
            type: string
            default: ced7e5f0498645c6ec642dcf450b036f
      responses:
        '200':
          $ref: '#/components/responses/VerificationRequireResult'
          description: 验证需求查询结果
      security:
        - SaToken: []
  /captcha/challenge:
    post:
      summary: 生成验证挑战
      deprecated: false
      description: >-
        统一生成验证码。tenantId、clientId、sceneCode、subject
        必须完整提交；挑战仅可由同一租户、客户端、场景、主体和请求 IP 校验。策略为天爱时返回行为验证数据；策略为系统图形时返回 uuid 和
        img。
      tags:
        - 验证中心
      parameters:
        - name: clientid
          in: header
          description: 客户端ID
          example: ced7e5f0498645c6ec642dcf450b036f
          schema:
            type: string
            default: ced7e5f0498645c6ec642dcf450b036f
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationChallengeBody'
            example:
              tenantId: '000000'
              clientId: 428a8310cd442757ae699df5d894f051
              sceneCode: APP_SMS_LOGIN
              subject: '13800000000'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VerificationChallengeResult'
          description: 验证挑战生成结果
      security:
        - SaToken: []
  /captcha/verify:
    post:
      summary: 校验验证结果并换取 validToken
      deprecated: false
      description: >-
        必须提交生成挑战时相同的 tenantId、clientId、sceneCode、subject 和 challengeId。验证通过后返回
        validToken；该票据仅随发送短信验证码接口一起提交，由发送入口单次消费。
      tags:
        - 验证中心
      parameters:
        - name: clientid
          in: header
          description: 客户端ID
          example: ced7e5f0498645c6ec642dcf450b036f
          schema:
            type: string
            default: ced7e5f0498645c6ec642dcf450b036f
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationCheckBody'
            examples:
              tianai_behavior:
                value:
                  tenantId: '000000'
                  clientId: 428a8310cd442757ae699df5d894f051
                  sceneCode: APP_SMS_LOGIN
                  subject: '13800000000'
                  challengeId: CAPTCHA_CHALLENGE_ID
                  providerCode: tianai
                  captchaType: SLIDER
                  payload:
                    track:
                      bgImageWidth: 340
                      bgImageHeight: 180
                      templateImageWidth: 50
                      templateImageHeight: 50
                      startTime: 1720000000000
                      stopTime: 1720000001500
                      left: 120
                      top: 0
                      trackList:
                        - x: 0
                          'y': 0
                          t: 0
                          type: down
                        - x: 120
                          'y': 0
                          t: 650
                          type: move
                        - x: 120
                          'y': 0
                          t: 700
                          type: up
                summary: 天爱滑块/旋转/滑动还原/文字点选验证
              system_image:
                value:
                  tenantId: '000000'
                  clientId: 428a8310cd442757ae699df5d894f051
                  sceneCode: APP_SMS_LOGIN
                  subject: '13800000000'
                  challengeId: CAPTCHA_CHALLENGE_ID
                  providerCode: ruoyi_image
                  captchaType: math
                  payload:
                    uuid: captcha-uuid
                    code: '6'
                summary: 系统图形验证码
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VerificationCheckResult'
          description: 验证校验结果
      security:
        - SaToken: []
  /auth/code:
    get:
      summary: 兼容旧系统图形验证码
      deprecated: false
      description: >-
        老版后台登录图形验证码入口。新的 APP/PC 业务优先使用 /captcha/require + /captcha/challenge +
        /captcha/verify。
      tags:
        - 验证中心
      parameters:
        - name: clientid
          in: header
          description: 客户端ID
          example: ced7e5f0498645c6ec642dcf450b036f
          schema:
            type: string
            default: ced7e5f0498645c6ec642dcf450b036f
      responses:
        '200':
          $ref: '#/components/responses/LegacyCaptchaResult'
          description: 兼容旧图形验证码结果
      security:
        - SaToken: []
  /genealogy/app/auth/register:
    post:
      summary: APP 用户注册
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordRegisterBody'
            example:
              grantType: password
              tenantId: '000000'
              phone: '13800000000'
              password: e10adc3949ba59abbe56e057f20f883e
              nickName: 测试用户
              registerSource: app
              smsCode: '1234'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/LoginResult'
          description: 登录结果
        '400':
          $ref: '#/components/responses/LoginResult'
          description: >-
            短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带
            validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。
          headers: {}
      security:
        - SaToken: []
  /genealogy/app/auth/login:
    post:
      summary: APP 密码登录
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordLoginBody'
            example:
              grantType: password
              tenantId: '000000'
              phone: '13800000000'
              password: e10adc3949ba59abbe56e057f20f883e
        required: true
      responses:
        '200':
          $ref: '#/components/responses/LoginResult'
          description: 登录结果
        '400':
          $ref: '#/components/responses/LoginResult'
          description: 密码登录仅接收租户、客户端、手机号和密码；不需要短信验证码或行为验证票据，携带验证码及其他未知旧字段返回 HTTP 400。
          headers: {}
      security:
        - SaToken: []
  /genealogy/app/auth/login/sms:
    post:
      summary: APP 短信登录
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmsLoginBody'
            example:
              grantType: sms
              tenantId: '000000'
              phone: '13800000000'
              smsCode: '1234'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/LoginResult'
          description: 登录结果
        '400':
          $ref: '#/components/responses/LoginResult'
          description: >-
            短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带
            validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。
          headers: {}
      security:
        - SaToken: []
  /genealogy/app/auth/sms/code:
    post:
      summary: APP 发送短信验证码
      deprecated: false
      description: >-
        先完成验证中心校验，再提交 validToken。sceneCode 仅允许
        APP_SMS_LOGIN、APP_REGISTER、APP_FORGOT_PASSWORD、APP_PHONE_CHANGE、APP_ACCOUNT_DEACTIVATE；服务端按租户、APP
        客户端、场景和手机号主体校验票据，不接收短信供应商配置 ID。
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmsCodeBody'
            example:
              tenantId: '000000'
              phone: '13800000000'
              grantType: sms
              sceneCode: APP_SMS_LOGIN
              validToken: captcha-ticket
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
        '400':
          $ref: '#/components/responses/VoidResult'
          description: >-
            拒绝原因：票据缺失；票据与租户不匹配（错租户）；票据与客户端不匹配（错客户端）；票据与场景不匹配（错场景）；票据过期；票据已被使用（重复使用）；手机号主体不匹配；请求携带供应商配置或历史字段。
          headers: {}
      security:
        - SaToken: []
  /genealogy/app/auth/profile:
    get:
      summary: APP 当前用户资料
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    put:
      summary: APP 修改用户资料
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileUpdateBody'
            example:
              nickName: 张三
              avatarOssId: '2060000000000000000'
              sex: '0'
              birthday: '1990-01-01'
              regionCode: '110101'
              addressDetail: 北京市东城区
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/auth/password:
    put:
      summary: APP 修改密码
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordChangeBody'
            example:
              oldPassword: e10adc3949ba59abbe56e057f20f883e
              newPassword: 25d55ad283aa400af464c76d713c07ad
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/auth/password/reset:
    put:
      summary: APP 找回密码
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordResetBody'
            example:
              grantType: password
              tenantId: '000000'
              phone: '13800000000'
              smsCode: '1234'
              newPassword: 25d55ad283aa400af464c76d713c07ad
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
        '400':
          $ref: '#/components/responses/VoidResult'
          description: >-
            短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带
            validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。
          headers: {}
      security:
        - SaToken: []
  /genealogy/app/auth/phone:
    put:
      summary: APP 换绑手机号
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneChangeBody'
            example:
              clientId: 428a8310cd442757ae699df5d894f051
              phone: '13900000000'
              smsCode: '1234'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
        '400':
          $ref: '#/components/responses/ObjectResult'
          description: >-
            短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带
            validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。
          headers: {}
      security:
        - SaToken: []
  /genealogy/app/auth/account/deactivate:
    post:
      summary: APP 注销账号
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountDeactivateBody'
            example:
              clientId: 428a8310cd442757ae699df5d894f051
              smsCode: '1234'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
        '400':
          $ref: '#/components/responses/VoidResult'
          description: >-
            短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带
            validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。
          headers: {}
      security:
        - SaToken: []
  /genealogy/app/auth/logout:
    delete:
      summary: APP 退出登录
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/pc/auth/register:
    post:
      summary: PC 用户注册
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordRegisterBody'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/LoginResult'
          description: 登录结果
      security:
        - SaToken: []
  /genealogy/pc/auth/login:
    post:
      summary: PC 密码登录
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordLoginBody'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/LoginResult'
          description: 登录结果
      security:
        - SaToken: []
  /genealogy/pc/auth/login/sms:
    post:
      summary: PC 短信登录
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmsLoginBody'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/LoginResult'
          description: 登录结果
      security:
        - SaToken: []
  /genealogy/pc/auth/sms/code:
    post:
      summary: PC 发送短信验证码
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmsCodeBody'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/pc/auth/profile:
    get:
      summary: PC 当前用户资料
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    put:
      summary: PC 修改用户资料
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileUpdateBody'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/pc/auth/password:
    put:
      summary: PC 修改密码
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordChangeBody'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/pc/auth/password/reset:
    put:
      summary: PC 找回密码
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordResetBody'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/pc/auth/phone:
    put:
      summary: PC 换绑手机号
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneChangeBody'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/pc/auth/account/deactivate:
    post:
      summary: PC 注销账号
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountDeactivateBody'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/pc/auth/logout:
    delete:
      summary: PC 退出登录
      deprecated: false
      description: ''
      tags:
        - 认证登录
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/files/upload:
    post:
      summary: APP 单文件上传
      deprecated: false
      description: ''
      tags:
        - 文件上传
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  example: ''
              required:
                - file
            example:
              file: ''
        required: true
      responses:
        '200':
          $ref: '#/components/responses/FileUploadResult'
          description: 文件上传结果
      security:
        - SaToken: []
  /genealogy/app/files/resumable/init:
    post:
      summary: APP 分片上传初始化
      deprecated: false
      description: 所有文件统一使用分片上传；普通小文件可设置为一个分片。返回 instant=true 时直接使用返回的 OSS 信息，跳过分片上传和合并。
      tags:
        - 文件上传
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        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
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/files/resumable/chunk:
    post:
      summary: APP 上传分片
      deprecated: false
      description: ''
      tags:
        - 文件上传
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                uploadId:
                  type: string
                  example: ''
                chunkIndex:
                  type: integer
                  example: 0
                chunkMd5:
                  type: string
                  example: d41d8cd98f00b204e9800998ecf8427e
                file:
                  type: string
                  format: binary
                  example: ''
              required:
                - uploadId
                - chunkIndex
                - chunkMd5
                - file
            example:
              uploadId: ''
              chunkIndex: 0
              chunkMd5: d41d8cd98f00b204e9800998ecf8427e
              file: ''
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/files/resumable/complete:
    post:
      summary: APP 完成分片上传
      deprecated: false
      description: ''
      tags:
        - 文件上传
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumableCompleteBody'
            example:
              uploadId: UPLOAD202607090001
              fileMd5: d41d8cd98f00b204e9800998ecf8427e
              fileSize: 9532
        required: true
      responses:
        '200':
          $ref: '#/components/responses/FileUploadResult'
          description: 文件上传结果
      security:
        - SaToken: []
  /genealogy/app/files/reference:
    post:
      summary: APP 绑定文件业务引用
      deprecated: false
      description: ''
      tags:
        - 文件上传
      parameters:
        - name: clientid
          in: header
          description: 客户端ID，请求Header携带，用于区分APP/PC/小程序等终端
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        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: '2060000000000000000'
              usageScene: feed_image
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
    delete:
      summary: APP 释放文件业务引用
      deprecated: false
      description: ''
      tags:
        - 文件上传
      parameters:
        - name: bizTable
          in: query
          description: 业务表名，用于文件引用绑定
          required: true
          example: gen_family_feed
          schema:
            type: string
        - name: bizId
          in: query
          description: 业务数据ID，用于文件引用绑定
          required: true
          example: 900013001
          schema:
            type: integer
            format: int64
        - name: bizField
          in: query
          description: 业务字段名，例如avatar_oss_id、cover_oss_id
          required: true
          example: media_ids
          schema:
            type: string
        - name: clientid
          in: header
          description: 客户端ID，请求Header携带，用于区分APP/PC/小程序等终端
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/pc/files/upload:
    post:
      summary: PC 单文件上传
      deprecated: false
      description: ''
      tags:
        - 文件上传
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  example: ''
              required:
                - file
            example:
              file: ''
        required: true
      responses:
        '200':
          $ref: '#/components/responses/FileUploadResult'
          description: 文件上传结果
      security:
        - SaToken: []
  /genealogy/pc/files/resumable/init:
    post:
      summary: PC 分片上传初始化
      deprecated: false
      description: ''
      tags:
        - 文件上传
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumableInitBody'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/pc/files/resumable/chunk:
    post:
      summary: PC 上传分片
      deprecated: false
      description: ''
      tags:
        - 文件上传
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                uploadId:
                  type: string
                  example: ''
                chunkIndex:
                  type: integer
                  example: 0
                chunkMd5:
                  type: string
                  example: d41d8cd98f00b204e9800998ecf8427e
                file:
                  type: string
                  format: binary
                  example: ''
              required:
                - uploadId
                - chunkIndex
                - chunkMd5
                - file
            example:
              uploadId: ''
              chunkIndex: 0
              chunkMd5: d41d8cd98f00b204e9800998ecf8427e
              file: ''
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/pc/files/resumable/complete:
    post:
      summary: PC 完成分片上传
      deprecated: false
      description: ''
      tags:
        - 文件上传
      parameters:
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumableCompleteBody'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/FileUploadResult'
          description: 文件上传结果
      security:
        - SaToken: []
  /genealogy/region/children:
    get:
      summary: 查询下级行政区划
      deprecated: false
      description: ''
      tags:
        - 行政区划
      parameters:
        - name: parentCode
          in: query
          description: 父级行政区划编码，不传或传0查省级
          required: false
          example: '51'
          schema:
            type: string
        - name: clientid
          in: header
          description: 客户端ID
          example: ced7e5f0498645c6ec642dcf450b036f
          schema:
            type: string
            default: ced7e5f0498645c6ec642dcf450b036f
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/region/path/{regionCode}:
    get:
      summary: 查询行政区划路径
      deprecated: false
      description: ''
      tags:
        - 行政区划
      parameters:
        - name: regionCode
          in: path
          description: 行政区划编码
          required: true
          example: '510000'
          schema:
            type: string
        - name: clientid
          in: header
          description: 客户端ID
          example: ced7e5f0498645c6ec642dcf450b036f
          schema:
            type: string
            default: ced7e5f0498645c6ec642dcf450b036f
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/region/search:
    get:
      summary: 搜索行政区划
      deprecated: false
      description: ''
      tags:
        - 行政区划
      parameters:
        - name: keyword
          in: query
          description: 搜索关键词，支持地区名称或编码模糊查询
          required: true
          example: 北京
          schema:
            type: string
        - name: level
          in: query
          description: 行政区划级别，1省、2市、3区县、4乡镇街道、5村社区
          required: false
          example: 3
          schema:
            type: integer
        - name: limit
          in: query
          description: 返回数量上限
          required: false
          example: 20
          schema:
            type: integer
        - name: clientid
          in: header
          description: 客户端ID
          example: ced7e5f0498645c6ec642dcf450b036f
          schema:
            type: string
            default: ced7e5f0498645c6ec642dcf450b036f
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/region/{regionCode}:
    get:
      summary: 查询行政区划详情
      deprecated: false
      description: ''
      tags:
        - 行政区划
      parameters:
        - name: regionCode
          in: path
          description: 行政区划编码
          required: true
          example: '510000'
          schema:
            type: string
        - name: clientid
          in: header
          description: 客户端ID
          example: ced7e5f0498645c6ec642dcf450b036f
          schema:
            type: string
            default: ced7e5f0498645c6ec642dcf450b036f
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies:
    post:
      summary: APP 创建家谱
      deprecated: false
      description: ''
      tags:
        - 家谱
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenealogyCreateBody'
            example:
              genealogyName: 彭氏家谱
              surname: 彭
              ancestralHall: 陇西堂
              originPlace: 江西吉安
              regionCode: '360800'
              addressDetail: 江西省吉安市
              coverOssId: '2060000000000000000'
              intro: 彭氏家谱简介
              visibility: '1'
              joinMode: '1'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/mine:
    get:
      summary: APP 我的家谱
      deprecated: false
      description: ''
      tags:
        - 家谱
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/public:
    get:
      summary: APP 公开家谱
      deprecated: false
      description: ''
      tags:
        - 家谱
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/options:
    get:
      summary: APP 家谱下拉选项
      deprecated: false
      description: ''
      tags:
        - 家谱
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}:
    get:
      summary: APP 家谱详情
      deprecated: false
      description: ''
      tags:
        - 家谱
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    put:
      summary: APP 修改家谱
      deprecated: false
      description: ''
      tags:
        - 家谱
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenealogyUpdateBody'
            example:
              genealogyName: 彭氏家谱
              surname: 彭
              ancestralHall: 陇西堂
              originPlace: 江西吉安
              regionCode: '360800'
              addressDetail: 江西省吉安市
              coverOssId: '2060000000000000000'
              intro: 更新后的家谱简介
              visibility: '1'
              joinMode: '1'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/overview:
    get:
      summary: APP 家谱概览
      deprecated: false
      description: ''
      tags:
        - 家谱
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/join-applies:
    post:
      summary: APP 申请加入家谱
      deprecated: false
      description: ''
      tags:
        - 家谱
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenealogyJoinApplyBody'
            example:
              applicantName: 彭小明
              phone: '13800000000'
              relationDesc: 本族成员
              applyReason: 申请加入家谱维护
              inviterUserId: 900000001
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/join-applies/mine:
    get:
      summary: APP 我的加入申请
      deprecated: false
      description: ''
      tags:
        - 家谱
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/join-applies/pending:
    get:
      summary: APP 待审核加入申请
      deprecated: false
      description: ''
      tags:
        - 家谱
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/join-applies/{applyId}/audit:
    put:
      summary: APP 审核加入申请
      deprecated: false
      description: ''
      tags:
        - 家谱
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: applyId
          in: path
          description: 加入家谱申请ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenealogyJoinAuditBody'
            example:
              status: '1'
              auditRemark: 信息核验通过
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/join-applies/{applyId}:
    delete:
      summary: APP 撤销加入申请
      deprecated: false
      description: ''
      tags:
        - 家谱
      parameters:
        - name: applyId
          in: path
          description: 加入家谱申请ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/members:
    get:
      summary: APP 家谱成员列表
      deprecated: false
      description: ''
      tags:
        - 家谱成员
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/members/options:
    get:
      summary: APP 家谱成员选项
      deprecated: false
      description: ''
      tags:
        - 家谱成员
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/members/{memberId}:
    put:
      summary: APP 修改成员
      deprecated: false
      description: ''
      tags:
        - 家谱成员
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: memberId
          in: path
          description: 家谱成员ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenealogyMemberUpdateBody'
            example:
              memberName: 彭小明
              relationName: 族亲
              roleType: member
              lineagePersonId: 900020001
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    delete:
      summary: APP 移除成员
      deprecated: false
      description: ''
      tags:
        - 家谱成员
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: memberId
          in: path
          description: 家谱成员ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/members/me:
    delete:
      summary: APP 退出家谱
      deprecated: false
      description: ''
      tags:
        - 家谱成员
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/members/owner-transfer:
    put:
      summary: APP 转让家谱所有者
      deprecated: false
      description: ''
      tags:
        - 家谱成员
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenealogyOwnerTransferBody'
            example:
              targetMemberId: 900010002
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/generation-poems:
    get:
      summary: APP 查询正常字辈谱
      deprecated: false
      description: 对可查看家谱的业务用户开放；仅返回正常状态字辈，供世系人物录入和展示使用。
      tags:
        - 字辈谱
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/GenerationPoemListResult'
          description: 字辈列表响应
      security:
        - SaToken: []
    post:
      summary: APP 新增字辈
      deprecated: false
      description: ''
      tags:
        - 字辈谱
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerationPoemBody'
            example:
              generationNo: 5
              generationText: 忠
              description: fifth generation poem
              sortOrder: 5
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/GenerationPoemResult'
          description: 字辈详情响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/generation-poems/batch/preview:
    post:
      summary: APP 批量字辈预览
      deprecated: false
      description: ''
      tags:
        - 字辈谱
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerationPoemBatchBody'
            example:
              poemText: |-
                德承家亦
                忠厚传芳
              disableMissing: false
        required: true
      responses:
        '200':
          $ref: '#/components/responses/GenerationPoemBatchPreviewResult'
          description: 字辈批量预览响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/generation-poems/batch/save:
    post:
      summary: APP 批量保存字辈
      deprecated: false
      description: 保存时会重新按当前数据生成差异；停用不删除历史字辈记录。
      tags:
        - 字辈谱
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerationPoemBatchBody'
            example:
              poemText: |-
                德承家亦
                忠厚传芳
              disableMissing: false
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/generation-poems/management:
    get:
      summary: APP 查询字辈维护列表
      deprecated: false
      description: 仅家谱内容编辑者可访问，返回正常和停用字辈，用于恢复、纠错和排序调整。
      tags:
        - 字辈谱
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/GenerationPoemListResult'
          description: 字辈列表响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/generation-poems/{poemId}:
    put:
      summary: APP 修改、停用或恢复字辈
      deprecated: false
      description: ''
      tags:
        - 字辈谱
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: poemId
          in: path
          description: 字辈记录ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerationPoemBody'
            example:
              generationNo: 5
              generationText: 忠
              description: fifth generation poem
              sortOrder: 5
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/GenerationPoemResult'
          description: 字辈详情响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/lineage/persons:
    get:
      summary: APP 世系人物列表
      deprecated: false
      description: ''
      tags:
        - 世系人物
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonListResult'
          description: 世系人物列表或选项响应
      security:
        - SaToken: []
    post:
      summary: APP 新增世系人物
      deprecated: false
      description: ''
      tags:
        - 世系人物
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LineagePersonBody'
            example:
              appUserId: 900000001
              personNo: P202607090001
              name: 彭德明
              aliasName: 德明
              sex: '0'
              generation: 1
              generationName: 德
              avatarOssId: '2060000000000000000'
              birthDate: '1950-01-01'
              birthLunar: '0'
              birthPlace: 江西吉安
              personStatus: '0'
              biography: 第一世人物简介
              sortOrder: 1
        required: true
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonResult'
          description: 世系人物详情响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/page:
    get:
      summary: APP 世系人物分页
      deprecated: false
      description: ''
      tags:
        - 世系人物
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: pageNum
          in: query
          description: 页码，从1开始
          required: false
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          description: 每页条数
          required: false
          schema:
            type: integer
            default: 10
        - name: keyword
          in: query
          description: 姓名、别名或人物编号关键词
          required: false
          schema:
            type: string
        - name: generation
          in: query
          description: 世代序号
          required: false
          schema:
            type: integer
            format: int64
        - name: personStatus
          in: query
          description: 人物状态字典值
          required: false
          schema:
            type: string
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonPageResult'
          description: 世系人物分页响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/options:
    get:
      summary: APP 世系人物选项
      deprecated: false
      description: ''
      tags:
        - 世系人物
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: keyword
          in: query
          description: 姓名、别名或人物编号关键词
          required: false
          schema:
            type: string
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonListResult'
          description: 世系人物列表或选项响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/lineage/tree:
    get:
      summary: APP 世系树
      deprecated: false
      description: ''
      tags:
        - 世系人物
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonTreeResult'
          description: 世系树响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}:
    get:
      summary: APP 世系人物详情
      deprecated: false
      description: ''
      tags:
        - 世系人物
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: personId
          in: path
          description: 世系人物ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonResult'
          description: 世系人物详情响应
      security:
        - SaToken: []
    put:
      summary: APP 修改世系人物
      deprecated: false
      description: ''
      tags:
        - 世系人物
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: personId
          in: path
          description: 世系人物ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LineagePersonBody'
            example:
              appUserId: 900000001
              personNo: P202607090001
              name: 彭德明
              aliasName: 德明
              sex: '0'
              generation: 1
              generationName: 德
              avatarOssId: '2060000000000000000'
              birthDate: '1950-01-01'
              birthLunar: '0'
              birthPlace: 江西吉安
              personStatus: '0'
              biography: 第一世人物简介
              sortOrder: 1
        required: true
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonResult'
          description: 世系人物详情响应
      security:
        - SaToken: []
    delete:
      summary: APP 停用世系人物
      deprecated: false
      description: 逻辑停用人物，不执行物理删除；存在正常子女时拒绝停用。
      tags:
        - 世系人物
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: personId
          in: path
          description: 世系人物ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/children:
    post:
      summary: APP 给人物添加子女
      deprecated: false
      description: ''
      tags:
        - 世系人物
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: personId
          in: path
          description: 世系人物ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LineagePersonBody'
            example:
              appUserId: 900000001
              personNo: P202607090001
              name: 彭德明
              aliasName: 德明
              sex: '0'
              generation: 1
              generationName: 德
              avatarOssId: '2060000000000000000'
              birthDate: '1950-01-01'
              birthLunar: '0'
              birthPlace: 江西吉安
              personStatus: '0'
              biography: 第一世人物简介
              sortOrder: 1
        required: true
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonResult'
          description: 世系人物详情响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/parents:
    post:
      summary: APP 给人物添加父母
      deprecated: false
      description: ''
      tags:
        - 世系人物
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: personId
          in: path
          description: 世系人物ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LineagePersonBody'
            example:
              appUserId: 900000001
              personNo: P202607090001
              name: 彭德明
              aliasName: 德明
              sex: '0'
              generation: 1
              generationName: 德
              avatarOssId: '2060000000000000000'
              birthDate: '1950-01-01'
              birthLunar: '0'
              birthPlace: 江西吉安
              personStatus: '0'
              biography: 第一世人物简介
              sortOrder: 1
        required: true
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonResult'
          description: 世系人物详情响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/siblings:
    post:
      summary: APP 给人物添加兄弟姐妹
      deprecated: false
      description: ''
      tags:
        - 世系人物
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: personId
          in: path
          description: 世系人物ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LineagePersonBody'
            example:
              appUserId: 900000001
              personNo: P202607090001
              name: 彭德明
              aliasName: 德明
              sex: '0'
              generation: 1
              generationName: 德
              avatarOssId: '2060000000000000000'
              birthDate: '1950-01-01'
              birthLunar: '0'
              birthPlace: 江西吉安
              personStatus: '0'
              biography: 第一世人物简介
              sortOrder: 1
        required: true
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonResult'
          description: 世系人物详情响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/spouses:
    post:
      summary: APP 给人物添加配偶
      deprecated: false
      description: ''
      tags:
        - 世系人物
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: personId
          in: path
          description: 世系人物ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LineagePersonBody'
            example:
              appUserId: 900000001
              personNo: P202607090001
              name: 彭德明
              aliasName: 德明
              sex: '0'
              generation: 1
              generationName: 德
              avatarOssId: '2060000000000000000'
              birthDate: '1950-01-01'
              birthLunar: '0'
              birthPlace: 江西吉安
              personStatus: '0'
              biography: 第一世人物简介
              sortOrder: 1
        required: true
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonResult'
          description: 世系人物详情响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/feeds:
    get:
      summary: APP 家族圈动态列表
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
    post:
      summary: APP 发布家族圈动态
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyFeedBody'
            example:
              feedType: text
              feedContent: 今天上传一张老照片。
              mediaOssIds: 2060000000000000001,2060000000000000002
              sortOrder: 0
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/feeds/page:
    get:
      summary: APP 家族圈动态分页
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: pageNum
          in: query
          description: 页码，从1开始
          required: false
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          description: 每页条数
          required: false
          schema:
            type: integer
            default: 10
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/PageResult'
          description: 通用分页响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}:
    get:
      summary: APP 家族圈动态详情
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: 家族动态ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    put:
      summary: APP 修改家族圈动态
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: 家族动态ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyFeedBody'
            example:
              feedType: text
              feedContent: 今天上传一张老照片。
              mediaOssIds: 2060000000000000001,2060000000000000002
              sortOrder: 0
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    delete:
      summary: APP 删除家族圈动态
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: 家族动态ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/likes:
    post:
      summary: APP 点赞动态
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: 家族动态ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
    delete:
      summary: APP 取消点赞动态
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: 家族动态ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/comments:
    get:
      summary: APP 动态一级评论列表
      deprecated: false
      description: 仅返回正常展示的一级评论；每条评论的 replyCount 为正常展示的直接回复数量。
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: 家族动态ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedCommentListResult'
          description: 家族圈评论列表响应
      security:
        - SaToken: []
    post:
      summary: APP 评论动态
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: 家族动态ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyFeedCommentBody'
            example:
              parentCommentId: null
              commentContent: 这张照片很有年代感。
        required: true
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedCommentResult'
          description: 家族圈评论对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/comments/page:
    get:
      summary: APP 动态一级评论分页
      deprecated: false
      description: 仅返回正常展示的一级评论；展开回复时请调用 replies 接口。
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: 家族动态ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: pageNum
          in: query
          description: 页码，从1开始
          required: false
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          description: 每页条数
          required: false
          schema:
            type: integer
            default: 10
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedCommentPageResult'
          description: 家族圈评论分页响应
      security:
        - SaToken: []
  /genealogy/pc/genealogies/{genealogyId}/feeds:
    get:
      summary: PC 家族圈动态列表
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: ''
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
    post:
      summary: PC 发布家族圈动态
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: ''
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyFeedBody'
            example:
              feedType: text
              feedContent: 今天上传一张老照片。
              mediaOssIds: 2060000000000000001,2060000000000000002
              sortOrder: 0
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/pc/genealogies/{genealogyId}/feeds/page:
    get:
      summary: PC 家族圈动态分页
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: ''
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: pageNum
          in: query
          description: ''
          required: false
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          description: ''
          required: false
          schema:
            type: integer
            default: 10
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/PageResult'
          description: 通用分页响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/comments/{commentId}:
    delete:
      summary: APP 删除本人动态评论；有回复时保留删除占位
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: 家族动态ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: commentId
          in: path
          description: 评论ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/pc/genealogies/{genealogyId}/feeds/{feedId}:
    get:
      summary: PC 家族圈动态详情
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: ''
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: ''
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    put:
      summary: PC 修改家族圈动态
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: ''
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: ''
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyFeedBody'
            example:
              feedType: text
              feedContent: 今天上传一张老照片。
              mediaOssIds: 2060000000000000001,2060000000000000002
              sortOrder: 0
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    delete:
      summary: PC 删除家族圈动态
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: ''
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: ''
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/pc/genealogies/{genealogyId}/feeds/{feedId}/likes:
    post:
      summary: PC 点赞动态
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: ''
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: ''
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
    delete:
      summary: PC 取消点赞动态
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: ''
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: ''
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/pc/genealogies/{genealogyId}/feeds/{feedId}/comments:
    get:
      summary: PC 动态评论列表
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: ''
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: ''
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
    post:
      summary: PC 评论动态
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: ''
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: ''
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyFeedCommentBody'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/pc/genealogies/{genealogyId}/feeds/{feedId}/comments/page:
    get:
      summary: PC 动态评论分页
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: ''
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: ''
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: pageNum
          in: query
          description: ''
          required: false
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          description: ''
          required: false
          schema:
            type: integer
            default: 10
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/PageResult'
          description: 通用分页响应
      security:
        - SaToken: []
  /genealogy/pc/genealogies/{genealogyId}/feeds/{feedId}/comments/{commentId}:
    delete:
      summary: PC 删除动态评论
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: ''
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: ''
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: commentId
          in: path
          description: 评论ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: ''
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/comments/{commentId}/replies:
    get:
      summary: APP 获取评论的直接回复列表
      deprecated: false
      description: 仅返回指定正常评论的正常展示直接回复；回复的 replyCount 可用于继续按需展开下一层。
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: 家族动态ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: commentId
          in: path
          description: 父评论 ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedCommentListResult'
          description: 家族圈评论列表响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/comments/{commentId}/replies/page:
    get:
      summary: APP 分页获取评论的直接回复
      deprecated: false
      description: ''
      tags:
        - 家族圈
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: feedId
          in: path
          description: 家族动态ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: commentId
          in: path
          description: 父评论 ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: pageNum
          in: query
          description: 页码，从1开始
          required: false
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          description: 每页条数
          required: false
          schema:
            type: integer
            default: 10
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedCommentPageResult'
          description: 家族圈评论分页响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/article-categories:
    get:
      summary: APP 谱文分类
      deprecated: false
      description: ''
      tags:
        - 内容文章
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/articles:
    get:
      summary: APP 谱文列表
      deprecated: false
      description: ''
      tags:
        - 内容文章
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
    post:
      summary: APP 新增谱文
      deprecated: false
      description: ''
      tags:
        - 内容文章
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleBody'
            example:
              categoryId: 900040001
              articleTitle: 族谱源流
              articleSummary: 介绍本支源流
              coverOssId: '2060000000000000000'
              articleContent: <p>article content</p>
              authorName: 族谱管理员
              sortOrder: 1
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/articles/{articleId}:
    get:
      summary: APP 谱文详情
      deprecated: false
      description: ''
      tags:
        - 内容文章
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: articleId
          in: path
          description: 谱文/官网文章ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    put:
      summary: APP 修改谱文
      deprecated: false
      description: ''
      tags:
        - 内容文章
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: articleId
          in: path
          description: 谱文/官网文章ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleBody'
            example:
              categoryId: 900040001
              articleTitle: 族谱源流
              articleSummary: 介绍本支源流
              coverOssId: '2060000000000000000'
              articleContent: <p>article content</p>
              authorName: 族谱管理员
              sortOrder: 1
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    delete:
      summary: APP 删除谱文
      deprecated: false
      description: ''
      tags:
        - 内容文章
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: articleId
          in: path
          description: 要删除的谱文ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/help-articles:
    get:
      summary: APP 帮助文章列表
      deprecated: false
      description: ''
      tags:
        - 内容文章
      parameters:
        - name: clientid
          in: header
          description: 客户端ID
          example: ced7e5f0498645c6ec642dcf450b036f
          schema:
            type: string
            default: ced7e5f0498645c6ec642dcf450b036f
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/app/help-articles/{helpId}:
    get:
      summary: APP 帮助文章详情
      deprecated: false
      description: ''
      tags:
        - 内容文章
      parameters:
        - name: helpId
          in: path
          description: 帮助文章ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: 客户端ID
          example: ced7e5f0498645c6ec642dcf450b036f
          schema:
            type: string
            default: ced7e5f0498645c6ec642dcf450b036f
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/promotions:
    get:
      summary: APP 应用推广列表
      deprecated: false
      description: ''
      tags:
        - 内容文章
      parameters:
        - name: clientid
          in: header
          description: 客户端ID
          example: ced7e5f0498645c6ec642dcf450b036f
          schema:
            type: string
            default: ced7e5f0498645c6ec642dcf450b036f
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/albums:
    get:
      summary: APP 相册列表
      deprecated: false
      description: ''
      tags:
        - 相册
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
    post:
      summary: APP 创建相册
      deprecated: false
      description: ''
      tags:
        - 相册
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlbumBody'
            example:
              albumName: 老照片
              albumDesc: family old photos
              coverOssId: '2060000000000000000'
              sortOrder: 1
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/albums/{albumId}:
    put:
      summary: APP 修改相册
      deprecated: false
      description: ''
      tags:
        - 相册
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: albumId
          in: path
          description: 相册ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlbumBody'
            example:
              albumName: 老照片
              albumDesc: family old photos
              coverOssId: '2060000000000000000'
              sortOrder: 1
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    delete:
      summary: APP 删除相册
      deprecated: false
      description: 逻辑删除相册及其照片，并释放封面和照片文件引用。
      tags:
        - 相册
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: albumId
          in: path
          description: 要删除的相册ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/albums/{albumId}/photos:
    get:
      summary: APP 相册图片列表
      deprecated: false
      description: ''
      tags:
        - 相册
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: albumId
          in: path
          description: 相册ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
    post:
      summary: APP 上传相册图片记录
      deprecated: false
      description: ''
      tags:
        - 相册
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: albumId
          in: path
          description: 相册ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlbumPhotoBody'
            example:
              ossId: '2060000000000000000'
              photoTitle: 老宅合影
              photoDesc: old house photo
              photographer: 彭小明
              shootTime: '2026-07-09 10:00:00'
              sortOrder: 1
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/albums/{albumId}/photos/{photoId}:
    delete:
      summary: APP 删除单张相册图片
      deprecated: false
      description: ''
      tags:
        - 相册
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: albumId
          in: path
          description: 相册ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: photoId
          in: path
          description: 要删除的相册图片ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/ceremonies:
    get:
      summary: APP 祭祀列表
      deprecated: false
      description: ''
      tags:
        - 祭祀
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
    post:
      summary: APP 创建祭祀
      deprecated: false
      description: ''
      tags:
        - 祭祀
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CeremonyBody'
            example:
              ceremonyType: ancestor
              ceremonyTitle: 清明祭祖
              ceremonyDesc: online ancestor ceremony
              ceremonyTime: '2026-04-04 09:00:00'
              location: 祠堂
              coverOssId: '2060000000000000000'
              sortOrder: 1
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/ceremonies/{ceremonyId}:
    get:
      summary: APP 祭祀详情
      deprecated: false
      description: ''
      tags:
        - 祭祀
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: ceremonyId
          in: path
          description: 祭祀/活动ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    put:
      summary: APP 修改祭祀
      deprecated: false
      description: ''
      tags:
        - 祭祀
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: ceremonyId
          in: path
          description: 祭祀/活动ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CeremonyBody'
            example:
              ceremonyType: ancestor
              ceremonyTitle: 清明祭祖
              ceremonyDesc: online ancestor ceremony
              ceremonyTime: '2026-04-04 09:00:00'
              location: 祠堂
              coverOssId: '2060000000000000000'
              sortOrder: 1
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    delete:
      summary: APP 删除祭祀活动
      deprecated: false
      description: 逻辑删除祭祀活动及其祭品，并释放活动封面文件引用。
      tags:
        - 祭祀
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: ceremonyId
          in: path
          description: 要删除的祭祀活动ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/ceremonies/{ceremonyId}/gifts:
    get:
      summary: APP 祭祀献礼列表
      deprecated: false
      description: ''
      tags:
        - 祭祀
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: ceremonyId
          in: path
          description: 祭祀/活动ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
    post:
      summary: APP 新增祭祀献礼
      deprecated: false
      description: ''
      tags:
        - 祭祀
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: ceremonyId
          in: path
          description: 祭祀/活动ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CeremonyGiftBody'
            example:
              giverName: 彭小明
              giftAmount: 66.66
              giftMessage: 缅怀先祖
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/ceremonies/{ceremonyId}/gifts/{giftId}:
    delete:
      summary: APP 删除单条祭品
      deprecated: false
      description: ''
      tags:
        - 祭祀
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: ceremonyId
          in: path
          description: 祭祀活动ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: giftId
          in: path
          description: 要删除的祭品ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/growth-records:
    get:
      summary: APP 成长记录列表
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
    post:
      summary: APP 新增成长记录
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrowthRecordBody'
            example:
              lineagePersonId: 900020001
              recordType: birth
              recordTitle: 出生记录
              recordContent: birth record
              recordDate: '2026-07-09 10:00:00'
              remindTime: '2027-07-09 10:00:00'
              mediaOssIds: '2060000000000000001'
              sortOrder: 1
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/growth-records/{recordId}:
    get:
      summary: APP 成长记录详情
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: recordId
          in: path
          description: 记录ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    put:
      summary: APP 修改成长记录
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: recordId
          in: path
          description: 记录ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrowthRecordBody'
            example:
              lineagePersonId: 900020001
              recordType: birth
              recordTitle: 出生记录
              recordContent: birth record
              recordDate: '2026-07-09 10:00:00'
              remindTime: '2027-07-09 10:00:00'
              mediaOssIds: '2060000000000000001'
              sortOrder: 1
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    delete:
      summary: APP 删除成长记录
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: recordId
          in: path
          description: 要删除的成长记录ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/memos:
    get:
      summary: APP 备忘录列表
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
    post:
      summary: APP 新增备忘录
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemoBody'
            example:
              memoTitle: 修谱事项
              memoContent: contact family members
              remindTime: '2026-08-01 09:00:00'
              completed: '0'
              mediaOssIds: '2060000000000000001'
              sortOrder: 1
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/memos/{memoId}:
    get:
      summary: APP 备忘录详情
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: memoId
          in: path
          description: ''
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    put:
      summary: APP 修改备忘录
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: memoId
          in: path
          description: ''
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemoBody'
            example:
              memoTitle: 修谱事项
              memoContent: contact family members
              remindTime: '2026-08-01 09:00:00'
              completed: '0'
              mediaOssIds: '2060000000000000001'
              sortOrder: 1
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    delete:
      summary: APP 删除备忘录
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: memoId
          in: path
          description: 要删除的备忘录ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/relative-records:
    get:
      summary: APP 亲友记录列表
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
    post:
      summary: APP 新增亲友记录
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RelativeRecordBody'
            example:
              relativeName: 张三
              relationName: 亲友
              eventName: 礼尚往来
              eventTime: '2026-07-16 10:00:00'
              giftAmount: 100
              recordContent: 往来记录
              mediaOssIds: '2060000000000000001'
              sortOrder: 1
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/relative-records/{relativeId}:
    get:
      summary: APP 亲友记录详情
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: relativeId
          in: path
          description: 亲友记录ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    put:
      summary: APP 修改亲友记录
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: relativeId
          in: path
          description: 亲友记录ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RelativeRecordBody'
            example:
              relativeName: 张三
              relationName: 亲友
              eventName: 礼尚往来
              eventTime: '2026-07-16 10:00:00'
              giftAmount: 100
              recordContent: 往来记录
              mediaOssIds: '2060000000000000001'
              sortOrder: 1
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
    delete:
      summary: APP 删除亲友记录
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: relativeId
          in: path
          description: 要删除的亲友记录ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/merit-records:
    get:
      summary: APP 功德记录列表
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
    post:
      summary: APP 新增功德记录
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeritRecordBody'
            example:
              donorName: 彭小明
              meritType: donation
              meritTitle: 修谱捐款
              meritContent: support genealogy work
              amount: 100
              meritTime: '2026-07-09 10:00:00'
              sortOrder: 1
              status: '0'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/merit-records/{meritId}:
    delete:
      summary: APP 删除功德记录
      deprecated: false
      description: ''
      tags:
        - 族务记录
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: meritId
          in: path
          description: 要删除的功德记录ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/notifications:
    get:
      summary: APP 消息通知列表
      deprecated: false
      description: ''
      tags:
        - 消息通知
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/app/notifications/{notificationId}/read:
    post:
      summary: APP 标记通知已读
      deprecated: false
      description: ''
      tags:
        - 消息通知
      parameters:
        - name: notificationId
          in: path
          description: 通知ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/notifications/read-all:
    post:
      summary: APP 全部标记已读
      deprecated: false
      description: ''
      tags:
        - 消息通知
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
  /genealogy/app/feedback:
    get:
      summary: APP 我的反馈列表
      deprecated: false
      description: ''
      tags:
        - 意见反馈
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
    post:
      summary: APP 提交反馈
      deprecated: false
      description: ''
      tags:
        - 意见反馈
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackBody'
            example:
              feedbackType: bug
              feedbackContent: upload image failed
              contactInfo: '13800000000'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/vip/packages:
    get:
      summary: APP VIP 套餐列表
      deprecated: false
      description: ''
      tags:
        - VIP
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
  /genealogy/app/vip/orders:
    get:
      summary: APP VIP 订单列表
      deprecated: false
      description: ''
      tags:
        - VIP
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
          description: 通用列表响应
      security:
        - SaToken: []
    post:
      summary: APP 创建 VIP 订单
      deprecated: false
      description: ''
      tags:
        - VIP
      parameters:
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VipOrderBody'
            example:
              packageId: 900060001
              genealogyId: 900001001
              payType: wechat
        required: true
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
          description: 通用对象响应
      security:
        - SaToken: []
  /genealogy/app/genealogies/{genealogyId}/videos/{videoId}:
    delete:
      summary: APP 删除视频
      deprecated: false
      description: 逻辑删除视频，并释放视频文件和封面文件引用。
      tags:
        - 视频
      parameters:
        - name: genealogyId
          in: path
          description: 家谱ID
          required: true
          example: 900001001
          schema:
            type: integer
            format: int64
        - name: videoId
          in: path
          description: 要删除的视频ID
          required: true
          example: ''
          schema:
            type: integer
            format: int64
        - name: clientid
          in: header
          description: >-
            APP 认证业务请求的 clientid Header 必填；必须与请求体 clientId（如提交）一致，且客户端 clientKey
            必须为 app 并与 APP 路由一致。
          required: true
          example: 428a8310cd442757ae699df5d894f051
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
          description: 通用成功响应
      security:
        - SaToken: []
components:
  schemas:
    RVoid:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          type: 'null'
    PasswordRegisterBody:
      type: object
      additionalProperties: false
      required:
        - clientId
        - grantType
        - tenantId
        - phone
        - password
        - smsCode
      properties:
        clientId:
          description: 必填；必须与 clientid Header 一致，且客户端 clientKey 必须为 app 并与 APP 路由一致。
          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
        smsCode:
          description: 4 位短信验证码
          type: string
          pattern: ^\d{4}$
          example: '1234'
    PasswordLoginBody:
      type: object
      additionalProperties: false
      required:
        - clientId
        - grantType
        - tenantId
        - phone
        - password
      properties:
        clientId:
          description: 必填；必须与 clientid Header 一致，且客户端 clientKey 必须为 app 并与 APP 路由一致。
          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
    SmsLoginBody:
      type: object
      additionalProperties: false
      required:
        - clientId
        - grantType
        - tenantId
        - phone
        - smsCode
      properties:
        clientId:
          description: 必填；必须与 clientid Header 一致，且客户端 clientKey 必须为 app 并与 APP 路由一致。
          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: 4 位短信验证码
          type: string
          pattern: ^\d{4}$
          example: '1234'
    SmsCodeBody:
      type: object
      additionalProperties: false
      required:
        - clientId
        - grantType
        - tenantId
        - sceneCode
        - phone
        - validToken
      properties:
        clientId:
          description: 必填；必须与 clientid Header 一致，且客户端 clientKey 必须为 app 并与 APP 路由一致。
          type: string
        grantType:
          description: 授权类型，例如password、sms、wechat、apple
          type: string
          example: sms
        tenantId:
          description: 租户ID，用于区分不同租户的数据和验证策略
          type: string
          example: '000000'
        sceneCode:
          description: APP 短信场景编码
          type: string
          enum:
            - APP_SMS_LOGIN
            - APP_REGISTER
            - APP_FORGOT_PASSWORD
            - APP_PHONE_CHANGE
            - APP_ACCOUNT_DEACTIVATE
          example: APP_SMS_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
      additionalProperties: false
      required:
        - clientId
        - grantType
        - tenantId
        - phone
        - smsCode
        - newPassword
      properties:
        clientId:
          description: 必填；必须与 clientid Header 一致，且客户端 clientKey 必须为 app 并与 APP 路由一致。
          type: string
        grantType:
          description: 授权类型
          type: string
          example: password
        tenantId:
          description: 租户ID，用于区分不同租户的数据和验证策略
          type: string
          example: '000000'
        phone:
          description: 手机号
          type: string
        smsCode:
          description: 4 位短信验证码
          type: string
          pattern: ^\d{4}$
          example: '1234'
        newPassword:
          type: string
          description: 32 位 MD5
    PhoneChangeBody:
      type: object
      additionalProperties: false
      required:
        - clientId
        - phone
        - smsCode
      properties:
        clientId:
          description: 必填；必须与 clientid Header 一致，且客户端 clientKey 必须为 app 并与 APP 路由一致。
          type: string
        phone:
          description: 新手机号
          type: string
        smsCode:
          description: 4 位短信验证码
          type: string
          pattern: ^\d{4}$
          example: '1234'
    AccountDeactivateBody:
      type: object
      additionalProperties: false
      required:
        - clientId
        - smsCode
      properties:
        clientId:
          description: 必填；必须与 clientid Header 一致，且客户端 clientKey 必须为 app 并与 APP 路由一致。
          type: string
        smsCode:
          description: 4 位短信验证码
          type: string
          pattern: ^\d{4}$
          example: '1234'
    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
      required:
        - poemText
      properties:
        poemText:
          description: 字辈文本。无分隔符时按单个字拆分；可用空格、逗号、分号、顿号、斜杠或竖线分隔多个字辈。单个字辈最多50个字符，一次最多500个世代。
          type: string
          maxLength: 26000
          example: |-
            德承家亦
            忠厚传芳
        disableMissing:
          description: 保存时是否停用未出现在新文本中的后续世代；不会删除历史记录。
          type: boolean
          example: false
    LineagePersonBody:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        appUserId:
          description: 绑定的业务用户ID；仅家谱管理员可绑定，且用户必须属于当前租户并处于正常状态
          type: integer
          format: int64
        personNo:
          description: 人物编号；不传时由服务端生成
          type: string
        name:
          description: 姓名
          type: string
        aliasName:
          description: 别名或曾用名
          type: string
        sex:
          description: 性别，建议使用系统字典值
          type: string
          example: '0'
        generation:
          description: 世代序号
          type: integer
          format: int64
        generationName:
          description: 字辈或辈分
          type: string
        fatherId:
          description: 父亲人物ID，必须属于当前家谱
          type: integer
          format: int64
        motherId:
          description: 母亲人物ID，必须属于当前家谱
          type: integer
          format: int64
        avatarOssId:
          description: 头像文件OSS ID；用户界面应通过统一上传组件获得，不允许手工录入
          type: integer
          format: int64
          nullable: true
        birthDate:
          type: string
          format: date-time
          nullable: true
        birthLunar:
          description: 生日是否农历，使用项目字典值
          type: string
        birthPlace:
          description: 出生地
          type: string
        deathDate:
          type: string
          format: date-time
          nullable: true
        deathLunar:
          description: 逝世日期是否农历，使用项目字典值
          type: string
        deathPlace:
          description: 逝世地
          type: string
        burialPlace:
          description: 安葬地
          type: string
        personStatus:
          description: 人物状态字典值
          type: string
        biography:
          description: 人物简介
          type: string
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        remark:
          description: 备注
          type: string
        relationName:
          description: 通过添加配偶快捷接口提交时使用的关系显示名称
          type: string
    FamilyFeedBody:
      type: object
      required:
        - feedContent
      properties:
        feedType:
          description: 动态类型，未传时默认为 text
          type: string
          example: text
        feedContent:
          description: 动态内容，不能为空
          type: string
          example: 今天上传一张老照片。
        mediaOssIds:
          description: 媒体文件 OSS ID 列表，多个 ID 使用英文逗号分隔
          type: string
          example: 2060000000000000001,2060000000000000002
        sortOrder:
          description: 排序值，未传时默认为 0
          type: integer
          format: int64
          example: 0
        status:
          description: 动态状态，未传时默认为正常状态
          type: string
          example: '0'
    FamilyFeedCommentBody:
      type: object
      required:
        - commentContent
      properties:
        parentCommentId:
          description: 父评论 ID；不传或传 null 表示发布一级评论
          type: integer
          format: int64
          nullable: true
        commentContent:
          description: 评论内容，最多 1000 个字符
          type: string
    GenealogyCreateBody:
      type: object
      required:
        - genealogyName
        - surname
        - regionCode
      properties:
        genealogyName:
          description: 家谱名称
          type: string
        surname:
          description: 姓氏
          type: string
        ancestralHall:
          description: 堂号/祠堂名称
          type: string
        originPlace:
          description: 籍贯/起源地
          type: string
        regionCode:
          description: 行政区划编码
          type: string
        addressDetail:
          description: 详细地址
          type: string
        coverOssId:
          description: 封面图片OSS ID
          type: integer
          format: int64
        intro:
          description: 简介
          type: string
        visibility:
          description: 可见范围，例如0私密、1公开、2成员可见
          type: string
        joinMode:
          description: 加入方式，例如0关闭、1审核、2邀请码
          type: string
      example:
        genealogyName: 彭氏家谱
        surname: 彭
        ancestralHall: 陇西堂
        originPlace: 江西吉安
        regionCode: '360800'
        addressDetail: 江西省吉安市
        coverOssId: 2060000000000000000
        intro: 彭氏家谱简介
        visibility: '1'
        joinMode: '1'
    GenealogyUpdateBody:
      type: object
      properties:
        genealogyName:
          description: 家谱名称
          type: string
        surname:
          description: 姓氏
          type: string
        ancestralHall:
          description: 堂号/祠堂名称
          type: string
        originPlace:
          description: 籍贯/起源地
          type: string
        regionCode:
          description: 行政区划编码
          type: string
        addressDetail:
          description: 详细地址
          type: string
        coverOssId:
          description: 封面图片OSS ID
          type: integer
          format: int64
        intro:
          description: 简介
          type: string
        visibility:
          description: 可见范围，例如0私密、1公开、2成员可见
          type: string
        joinMode:
          description: 加入方式，例如0关闭、1审核、2邀请码
          type: string
      example:
        genealogyName: 彭氏家谱
        surname: 彭
        ancestralHall: 陇西堂
        originPlace: 江西吉安
        regionCode: '360800'
        addressDetail: 江西省吉安市
        coverOssId: 2060000000000000000
        intro: 更新后的家谱简介
        visibility: '1'
        joinMode: '1'
    GenealogyJoinApplyBody:
      type: object
      properties:
        applicantName:
          description: 申请人姓名
          type: string
        phone:
          description: 手机号
          type: string
        relationDesc:
          description: 与家谱/人物的关系说明
          type: string
        applyReason:
          description: 申请理由
          type: string
        inviterUserId:
          description: 邀请人业务用户ID
          type: integer
          format: int64
      example:
        applicantName: 彭小明
        phone: '13800000000'
        relationDesc: 本族成员
        applyReason: 申请加入家谱维护
        inviterUserId: 900000001
    GenealogyJoinAuditBody:
      type: object
      required:
        - status
      properties:
        status:
          description: 状态，建议使用对应字典值
          type: string
        auditRemark:
          description: 审核备注
          type: string
      example:
        status: '1'
        auditRemark: 信息核验通过
    GenealogyMemberUpdateBody:
      type: object
      properties:
        memberName:
          description: 成员姓名
          type: string
        relationName:
          description: 成员关系名称
          type: string
        roleType:
          description: 成员角色类型，例如创建者、管理员、普通成员
          type: string
        lineagePersonId:
          description: 绑定的世系人物ID
          type: integer
          format: int64
      example:
        memberName: 彭小明
        relationName: 族亲
        roleType: member
        lineagePersonId: 900020001
    GenealogyOwnerTransferBody:
      type: object
      required:
        - targetMemberId
      properties:
        targetMemberId:
          description: 目标成员ID
          type: integer
          format: int64
      example:
        targetMemberId: 900010002
    GenerationPoemBody:
      type: object
      required:
        - generationNo
        - generationText
      properties:
        generationNo:
          description: 世代序号
          type: integer
          format: int64
          minimum: 1
          maximum: 2147483647
        generationText:
          description: 当前世代的字辈文字，最长50个字符
          type: string
          maxLength: 50
        description:
          description: 字辈说明，最长500个字符
          type: string
          maxLength: 500
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
          minimum: -2147483648
          maximum: 2147483647
        status:
          description: 状态，0正常，1停用
          type: string
      example:
        generationNo: 5
        generationText: 忠
        description: fifth generation poem
        sortOrder: 5
        status: '0'
    ArticleBody:
      type: object
      required:
        - articleTitle
        - articleContent
      properties:
        categoryId:
          description: 分类ID
          type: integer
          format: int64
        articleTitle:
          description: 文章标题
          type: string
        articleSummary:
          description: 文章摘要
          type: string
        coverOssId:
          description: 封面图片OSS ID
          type: integer
          format: int64
        articleContent:
          description: 文章内容
          type: string
        authorName:
          description: 作者名称
          type: string
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: 状态，建议使用对应字典值
          type: string
      example:
        categoryId: 900040001
        articleTitle: 族谱源流
        articleSummary: 介绍本支源流
        coverOssId: 2060000000000000000
        articleContent: <p>article content</p>
        authorName: 族谱管理员
        sortOrder: 1
        status: '0'
    AlbumBody:
      type: object
      required:
        - albumName
      properties:
        albumName:
          description: 相册名称
          type: string
        albumDesc:
          description: 相册说明
          type: string
        coverOssId:
          description: 封面图片OSS ID
          type: integer
          format: int64
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: 状态，建议使用对应字典值
          type: string
      example:
        albumName: 老照片
        albumDesc: family old photos
        coverOssId: 2060000000000000000
        sortOrder: 1
        status: '0'
    AlbumPhotoBody:
      type: object
      required:
        - ossId
      properties:
        ossId:
          description: OSS文件ID，表单内部使用，用户侧应通过上传组件获取
          type: integer
          format: int64
        photoTitle:
          description: 图片标题
          type: string
        photoDesc:
          description: 图片说明
          type: string
        photographer:
          description: 拍摄人
          type: string
        shootTime:
          description: 拍摄时间
          type: string
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: 状态，建议使用对应字典值
          type: string
      example:
        ossId: 2060000000000000000
        photoTitle: 老宅合影
        photoDesc: old house photo
        photographer: 彭小明
        shootTime: '2026-07-09 10:00:00'
        sortOrder: 1
        status: '0'
    CeremonyBody:
      type: object
      required:
        - ceremonyType
        - ceremonyTitle
      properties:
        ceremonyType:
          description: 祭祀/活动类型
          type: string
        ceremonyTitle:
          description: 祭祀/活动标题
          type: string
        ceremonyDesc:
          description: 祭祀/活动说明
          type: string
        ceremonyTime:
          description: 祭祀/活动时间
          type: string
        location:
          description: 地点
          type: string
        coverOssId:
          description: 封面图片OSS ID
          type: integer
          format: int64
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: 状态，建议使用对应字典值
          type: string
      example:
        ceremonyType: ancestor
        ceremonyTitle: 清明祭祖
        ceremonyDesc: online ancestor ceremony
        ceremonyTime: '2026-04-04 09:00:00'
        location: 祠堂
        coverOssId: 2060000000000000000
        sortOrder: 1
        status: '0'
    CeremonyGiftBody:
      type: object
      required:
        - giftAmount
      properties:
        giverName:
          description: 赠送人/献礼人姓名
          type: string
        giftAmount:
          description: 礼物金额
          type: number
          format: double
        giftMessage:
          description: 礼物留言
          type: string
      example:
        giverName: 彭小明
        giftAmount: 66.66
        giftMessage: 缅怀先祖
    GrowthRecordBody:
      type: object
      required:
        - recordTitle
      properties:
        lineagePersonId:
          description: 绑定的世系人物ID
          type: integer
          format: int64
        recordType:
          description: 记录类型
          type: string
        recordTitle:
          description: 记录标题
          type: string
        recordContent:
          description: 记录内容
          type: string
        recordDate:
          description: 记录日期
          type: string
        remindTime:
          description: 提醒时间
          type: string
        mediaOssIds:
          description: 媒体文件 OSS ID 列表；多个正整数 ID 使用英文逗号分隔，禁止空项和其他字符
          type: string
          pattern: ^$|^[1-9][0-9]*(,[1-9][0-9]*)*$
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: 状态，建议使用对应字典值
          type: string
      example:
        lineagePersonId: 900020001
        recordType: birth
        recordTitle: 出生记录
        recordContent: birth record
        recordDate: '2026-07-09 10:00:00'
        remindTime: '2027-07-09 10:00:00'
        mediaOssIds: '2060000000000000001'
        sortOrder: 1
        status: '0'
    MemoBody:
      type: object
      required:
        - memoTitle
      properties:
        memoTitle:
          description: 备忘标题
          type: string
        memoContent:
          description: 备忘内容
          type: string
        remindTime:
          description: 提醒时间
          type: string
        completed:
          description: 是否已完成
          type: string
        mediaOssIds:
          description: 媒体文件 OSS ID 列表；多个正整数 ID 使用英文逗号分隔，禁止空项和其他字符
          type: string
          pattern: ^$|^[1-9][0-9]*(,[1-9][0-9]*)*$
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: 状态，建议使用对应字典值
          type: string
      example:
        memoTitle: 修谱事项
        memoContent: contact family members
        remindTime: '2026-08-01 09:00:00'
        completed: '0'
        mediaOssIds: '2060000000000000001'
        sortOrder: 1
        status: '0'
    RelativeRecordBody:
      type: object
      required:
        - relativeName
      properties:
        relativeName:
          description: 亲友姓名
          type: string
        relationName:
          description: 关系名称
          type: string
        eventName:
          description: 事件名称
          type: string
        eventTime:
          description: 事件时间
          type: string
        giftAmount:
          description: 礼金金额
          type: number
        recordContent:
          description: 记录内容
          type: string
        mediaOssIds:
          description: 媒体文件 OSS ID 列表；多个正整数 ID 使用英文逗号分隔，禁止空项和其他字符
          type: string
          pattern: ^$|^[1-9][0-9]*(,[1-9][0-9]*)*$
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: 状态，建议使用对应字典值
          type: string
    MeritRecordBody:
      type: object
      required:
        - donorName
        - meritTitle
      properties:
        donorName:
          description: 功德人/捐赠人姓名
          type: string
        meritType:
          description: 功德类型
          type: string
        meritTitle:
          description: 功德标题
          type: string
        meritContent:
          description: 功德内容
          type: string
        amount:
          description: 金额
          type: number
          format: double
        meritTime:
          description: 功德时间
          type: string
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: 状态，建议使用对应字典值
          type: string
      example:
        donorName: 彭小明
        meritType: donation
        meritTitle: 修谱捐款
        meritContent: support genealogy work
        amount: 100
        meritTime: '2026-07-09 10:00:00'
        sortOrder: 1
        status: '0'
    FeedbackBody:
      type: object
      required:
        - feedbackContent
      properties:
        feedbackType:
          description: 反馈类型
          type: string
        feedbackContent:
          description: 反馈内容
          type: string
        contactInfo:
          description: 联系方式
          type: string
      example:
        feedbackType: bug
        feedbackContent: upload image failed
        contactInfo: '13800000000'
    VipOrderBody:
      type: object
      required:
        - packageId
      properties:
        packageId:
          description: VIP套餐ID
          type: integer
          format: int64
        genealogyId:
          description: 家谱ID
          type: integer
          format: int64
        payType:
          description: 支付方式
          type: string
      example:
        packageId: 900060001
        genealogyId: 900001001
        payType: wechat
    VerificationChallengeBody:
      type: object
      required:
        - tenantId
        - clientId
        - sceneCode
        - subject
      properties:
        tenantId:
          type: string
          description: 租户 ID
        clientId:
          type: string
          description: 客户端 ID
        sceneCode:
          type: string
          description: APP 短信场景编码
          enum:
            - APP_SMS_LOGIN
            - APP_REGISTER
            - APP_FORGOT_PASSWORD
            - APP_PHONE_CHANGE
            - APP_ACCOUNT_DEACTIVATE
        subject:
          type: string
          description: 验证主体，如手机号/用户名/IP
      example:
        tenantId: '000000'
        clientId: 428a8310cd442757ae699df5d894f051
        sceneCode: APP_SMS_LOGIN
        subject: '13800000000'
    VerificationCheckBody:
      type: object
      required:
        - tenantId
        - clientId
        - sceneCode
        - subject
        - challengeId
      properties:
        tenantId:
          description: 租户ID，用于区分不同租户的数据和验证策略
          type: string
        clientId:
          description: 客户端ID，对应后台客户端管理中的APP/PC/小程序等终端
          type: string
        sceneCode:
          description: APP 短信场景编码
          type: string
          enum:
            - APP_SMS_LOGIN
            - APP_REGISTER
            - APP_FORGOT_PASSWORD
            - APP_PHONE_CHANGE
            - APP_ACCOUNT_DEACTIVATE
        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:
          description: 验证结果载荷。天爱行为验证码提交 payload.track；系统图形验证码提交 payload.uuid 和 payload.code
          oneOf:
            - $ref: '#/components/schemas/TianaiVerificationPayload'
            - $ref: '#/components/schemas/SystemImageVerificationPayload'
    TianaiVerificationPayload:
      type: object
      description: >-
        将天爱 1.5.5 前端验证回调中的 data 原样放入 track；回调 id 不放入 payload，挑战标识统一提交顶层
        challengeId
      required:
        - track
      properties:
        track:
          $ref: '#/components/schemas/TianaiCaptchaTrack'
    TianaiCaptchaTrack:
      type: object
      required:
        - bgImageWidth
        - bgImageHeight
        - startTime
        - stopTime
        - trackList
      properties:
        bgImageWidth:
          type: integer
          description: 验证码背景图片在前端实际显示的宽度，单位像素
        bgImageHeight:
          type: integer
          description: 验证码背景图片在前端实际显示的高度，单位像素
        templateImageWidth:
          type: integer
          description: 滑块或旋转模板图片在前端实际显示的宽度，单位像素
        templateImageHeight:
          type: integer
          description: 滑块或旋转模板图片在前端实际显示的高度，单位像素
        startTime:
          type: integer
          format: int64
          description: 用户开始操作的时间戳，单位毫秒
        stopTime:
          type: integer
          format: int64
          description: 用户结束操作的时间戳，单位毫秒
        left:
          type: integer
          description: 滑块最终水平偏移量，单位像素；由天爱前端控件生成
        top:
          type: integer
          description: 点选或模板最终垂直偏移量，单位像素；由天爱前端控件生成
        trackList:
          type: array
          minItems: 1
          description: 用户操作轨迹，不能为空，必须直接使用天爱前端控件产生的数据
          items:
            $ref: '#/components/schemas/TianaiCaptchaTrackPoint'
        data:
          type: object
          additionalProperties: true
          description: 不同验证码类型附带的扩展数据，由天爱前端控件原样提交
          properties: {}
          nullable: true
    TianaiCaptchaTrackPoint:
      type: object
      required:
        - x
        - 'y'
        - t
        - type
      properties:
        x:
          type: number
          format: float
          description: 当前轨迹点的水平坐标
        'y':
          type: number
          format: float
          description: 当前轨迹点的垂直坐标
        t:
          type: number
          format: float
          description: 当前轨迹点相对操作开始时的时间，单位毫秒
        type:
          type: string
          description: 轨迹事件类型，例如 down、move、up
    SystemImageVerificationPayload:
      type: object
      required:
        - uuid
        - code
      properties:
        uuid:
          type: string
          description: 系统图形验证码接口返回的唯一标识
        code:
          type: string
          description: 用户填写的图形验证码答案
    RObject:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          type: object
          additionalProperties: true
          properties: {}
    RList:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          type: array
          items:
            type: object
            additionalProperties: true
            properties: {}
    PageResult:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        rows:
          description: 分页数据列表
          type: array
          items:
            type: object
            additionalProperties: true
            properties: {}
        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'
    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
    RFileUpload:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/FileUploadVo'
    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
    RVerificationRequire:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/VerificationRequireVo'
    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 短信场景编码
          type: string
          enum:
            - APP_SMS_LOGIN
            - APP_REGISTER
            - APP_FORGOT_PASSWORD
            - APP_PHONE_CHANGE
            - APP_ACCOUNT_DEACTIVATE
        ttlSeconds:
          description: 验证或票据有效秒数
          type: integer
      example:
        required: true
        providerCode: tianai
        captchaType: SLIDER
        sceneCode: APP_SMS_LOGIN
        ttlSeconds: 300
    RVerificationChallenge:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/VerificationChallengeVo'
    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: 天爱验证码数据，包括背景图、模板图、尺寸等
          properties: {}
        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
    RVerificationCheck:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/VerificationCheckVo'
    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: 验证通过
    RLegacyCaptcha:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/LegacyCaptchaVo'
    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,...
    RGenerationPoem:
      type: object
      properties:
        code:
          description: 响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
        data:
          $ref: '#/components/schemas/GenerationPoemView'
    GenerationPoemView:
      type: object
      properties:
        poemId:
          description: 字辈记录ID
          type: integer
          format: int64
        genealogyId:
          description: 所属家谱ID
          type: integer
          format: int64
        genealogyNo:
          description: 家谱编号
          type: string
        genealogyName:
          description: 家谱名称
          type: string
        generationNo:
          description: 世代序号
          type: integer
          format: int64
        generationText:
          description: 字辈文字
          type: string
        description:
          description: 字辈说明
          type: string
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: 状态，0正常，1停用
          type: string
    RGenerationPoemList:
      type: object
      properties:
        code:
          description: 响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/GenerationPoemView'
    RGenerationPoemBatchPreview:
      type: object
      properties:
        code:
          description: 响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
        data:
          $ref: '#/components/schemas/GenerationPoemBatchPreviewView'
    GenerationPoemBatchPreviewView:
      type: object
      properties:
        genealogyId:
          description: 所属家谱ID
          type: integer
          format: int64
        genealogyNo:
          description: 家谱编号
          type: string
        genealogyName:
          description: 家谱名称
          type: string
        createCount:
          description: 将新增的字辈数量
          type: integer
        updateCount:
          description: 将修改或恢复的字辈数量
          type: integer
        keepCount:
          description: 保持不变的字辈数量
          type: integer
        disableCount:
          description: 将停用的字辈数量
          type: integer
        items:
          description: 按世代排序的逐项变更预览
          type: array
          items:
            $ref: '#/components/schemas/GenerationPoemBatchItemView'
    GenerationPoemBatchItemView:
      type: object
      properties:
        poemId:
          description: 现有字辈记录ID；新增时为空
          type: integer
          format: int64
        generationNo:
          description: 世代序号
          type: integer
          format: int64
        oldGenerationText:
          description: 保存前字辈文字
          type: string
        newGenerationText:
          description: 保存后字辈文字
          type: string
        oldStatus:
          description: 保存前状态
          type: string
        newStatus:
          description: 保存后状态
          type: string
        action:
          description: 预览动作，create、update、keep 或 disable
          type: string
        warning:
          description: 需要用户确认的变更提示
          type: string
    RLineagePerson:
      type: object
      properties:
        code:
          description: 响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          $ref: '#/components/schemas/LineagePersonView'
    LineagePersonView:
      type: object
      properties:
        personId:
          description: 人物ID
          type: integer
          format: int64
        genealogyId:
          description: 家谱ID
          type: integer
          format: int64
        genealogyName:
          description: 家谱名称
          type: string
        genealogyNo:
          description: 家谱编号
          type: string
        appUserId:
          description: 绑定业务用户ID
          type: integer
          format: int64
          nullable: true
        appUserNickName:
          description: 绑定业务用户昵称
          type: string
        personNo:
          description: 人物编号
          type: string
        name:
          description: 姓名
          type: string
        aliasName:
          description: 别名或曾用名
          type: string
        sex:
          description: 性别字典值
          type: string
        generation:
          description: 世代序号
          type: integer
          format: int64
        generationName:
          description: 字辈或辈分
          type: string
        fatherId:
          description: 父亲人物ID
          type: integer
          format: int64
          nullable: true
        fatherName:
          description: 父亲姓名
          type: string
        motherId:
          description: 母亲人物ID
          type: integer
          format: int64
          nullable: true
        motherName:
          description: 母亲姓名
          type: string
        spouseNames:
          description: 配偶姓名，多个使用顿号分隔
          type: string
        avatarOssId:
          description: 头像文件OSS ID
          type: integer
          format: int64
          nullable: true
        birthDate:
          description: 出生日期
          type: string
          format: date-time
          nullable: true
        birthLunar:
          description: 生日是否农历字典值
          type: string
        birthPlace:
          description: 出生地
          type: string
        deathDate:
          description: 逝世日期
          type: string
          format: date-time
          nullable: true
        deathLunar:
          description: 逝世日期是否农历字典值
          type: string
        deathPlace:
          description: 逝世地
          type: string
        burialPlace:
          description: 安葬地
          type: string
        personStatus:
          description: 人物状态字典值
          type: string
        biography:
          description: 人物简介
          type: string
        sortOrder:
          description: 排序值
          type: integer
          format: int64
        status:
          description: 数据状态，0正常、1停用
          type: string
        remark:
          description: 备注
          type: string
    RLineagePersonList:
      type: object
      properties:
        code:
          description: 响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          type: array
          items:
            $ref: '#/components/schemas/LineagePersonView'
    RLineagePersonTreeList:
      type: object
      properties:
        code:
          description: 响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          type: array
          items:
            $ref: '#/components/schemas/LineagePersonTreeView'
    LineagePersonTreeView:
      allOf:
        - $ref: '#/components/schemas/LineagePersonView'
        - type: object
          properties:
            relationType:
              description: 与当前树节点的关系类型
              type: string
            relationName:
              description: 关系显示名称
              type: string
            spouses:
              description: 配偶节点
              type: array
              items:
                $ref: '#/components/schemas/LineagePersonTreeView'
            children:
              description: 子女节点
              type: array
              items:
                $ref: '#/components/schemas/LineagePersonTreeView'
    LineagePersonPageResult:
      type: object
      properties:
        code:
          description: 响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        rows:
          description: 当前页世系人物
          type: array
          items:
            $ref: '#/components/schemas/LineagePersonView'
        total:
          description: 总记录数
          type: integer
          format: int64
          example: 0
    RFamilyFeedComment:
      type: object
      properties:
        code:
          description: 响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
        data:
          $ref: '#/components/schemas/FamilyFeedCommentView'
    FamilyFeedCommentView:
      type: object
      properties:
        commentId:
          description: 评论 ID
          type: integer
          format: int64
        genealogyId:
          description: 所属家谱 ID
          type: integer
          format: int64
        feedId:
          description: 所属动态 ID
          type: integer
          format: int64
        parentCommentId:
          description: 父评论 ID；null 或 0 表示一级评论
          type: integer
          format: int64
          nullable: true
        appUserId:
          description: 评论业务用户 ID
          type: integer
          format: int64
        appUserNickName:
          description: 评论人昵称
          type: string
        appUserAvatar:
          description: 评论人头像文件 ID
          type: integer
          format: int64
          nullable: true
        parentAppUserId:
          description: 被直接回复的业务用户 ID
          type: integer
          format: int64
          nullable: true
        parentAppUserNickName:
          description: 被直接回复的用户昵称
          type: string
          nullable: true
        commentContent:
          description: 评论内容；作者删除后为 null
          type: string
          nullable: true
        userDeleted:
          description: 作者删除状态，0 未删除，1 已删除并保留占位
          type: string
          enum:
            - '0'
            - '1'
          example: '0'
        replyCount:
          description: 正常展示的直接回复数量
          type: integer
          format: int64
        commentLevel:
          description: 评论层级，root 为一级评论，reply 为回复
          type: string
          enum:
            - root
            - reply
        status:
          description: 可见状态；会员接口仅返回 0（正常展示）
          type: string
          example: '0'
        createTime:
          description: 评论发布时间
          type: string
          format: date-time
    RFamilyFeedCommentList:
      type: object
      properties:
        code:
          description: 响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/FamilyFeedCommentView'
    FamilyFeedCommentPageResult:
      type: object
      properties:
        code:
          description: 响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
        rows:
          description: 评论分页数据
          type: array
          items:
            $ref: '#/components/schemas/FamilyFeedCommentView'
        total:
          description: 评论总数
          type: integer
          format: int64
  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'
    GenerationPoemResult:
      description: 字辈详情响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RGenerationPoem'
    GenerationPoemListResult:
      description: 字辈列表响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RGenerationPoemList'
    GenerationPoemBatchPreviewResult:
      description: 字辈批量预览响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RGenerationPoemBatchPreview'
    LineagePersonResult:
      description: 世系人物详情响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RLineagePerson'
    LineagePersonListResult:
      description: 世系人物列表或选项响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RLineagePersonList'
    LineagePersonTreeResult:
      description: 世系树响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RLineagePersonTreeList'
    LineagePersonPageResult:
      description: 世系人物分页响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LineagePersonPageResult'
    FamilyFeedCommentResult:
      description: 家族圈评论对象响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RFamilyFeedComment'
    FamilyFeedCommentListResult:
      description: 家族圈评论列表响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RFamilyFeedCommentList'
    FamilyFeedCommentPageResult:
      description: 家族圈评论分页响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FamilyFeedCommentPageResult'
  securitySchemes:
    SaToken:
      type: apiKey
      in: header
      name: Authorization
      description: 登录后返回的 token。若本地配置使用 sa-token 名称，请按项目实际 token-name 调整。
servers: []
security:
  - SaToken: []