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

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

    约定：
    - APP 路径前缀为 `/genealogy/app`
    - PC/H5 路径前缀为 `/genealogy/pc`
    - 后台管理接口不包含在本文件内
    - 登录后接口需要携带 token，且请求 Header 需携带 `clientid`
servers:
  - url: https://backend-api.ddxcjp.cn
    description: Production API
  - url: http://127.0.0.1:8080
    description: Local Java backend
  - url: http://127.0.0.1:9527/dev-api
    description: Local frontend proxy
tags:
  - name: 业务字典
    description: APP/PC 当前租户可公开的业务选项
  - name: 验证中心
    description: 统一验证码、天爱行为验证码和系统图形验证码
  - name: 认证登录
    description: APP/PC 登录注册与账号资料
  - name: 文件上传
    description: APP/PC 统一文件上传与业务引用绑定
  - name: 行政区划
    description: 行政区划
  - name: 家谱
    description: 家谱主体、加入申请与概览
  - name: 家谱成员
    description: 家谱成员
  - name: 字辈谱
    description: 字辈谱
  - name: 世系人物
    description: 世系人物与世系树
  - name: 人生大事
    description: 世系人物的人生事件时间轴
  - name: 家族圈
    description: 家族圈动态、点赞、评论
  - name: 内容文章
    description: 谱文、官网文章、帮助、推广
  - name: 相册
    description: 相册与照片
  - name: 视频
    description: 家谱视频
  - name: 祭祀
    description: 祭祀与献礼
  - name: 族务记录
    description: 成长、备忘、亲友、功德等记录
  - name: VIP
    description: VIP 套餐与订单
  - name: 消息通知
    description: 消息通知
  - name: 意见反馈
    description: 意见反馈
security:
  - SaToken: []
paths:
  /genealogy/app/dictionaries/{dictType}:
    get:
      tags: [业务字典]
      summary: 查询当前租户业务字典
      description: 仅允许公开白名单类型；tenantId 查询参数不会改变登录租户。
      parameters:
        - name: dictType
          in: path
          required: true
          schema:
            type: string
          example: gen_feedback_type
      responses:
        '200':
          description: 当前登录租户的业务字典选项
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RBusinessDictionaryOptions'
        '400':
          description: 业务字典类型不支持
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RBusinessDictionaryError'
              example:
                code: 400
                msg: 业务字典类型不支持
                data: null
        '401':
          description: 未登录或登录已失效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RBusinessDictionaryError'
              example:
                code: 401
                msg: 认证失败，无法访问系统资源
                data: null
  /genealogy/app/auth/verification/{operationCode}/require:
    get:
      tags: [验证中心]
      summary: 查询 APP 认证动作是否需要验证
      description: 服务端按 operationCode 对应 APP 路由的当前激活绑定解析验证场景，前端不得提交 sceneCode。
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: operationCode
          description: APP 认证业务动作
          in: path
          required: true
          schema:
            type: string
            enum: [password-login, sms-login, register, forgot-password, phone-change, account-deactivate]
        - name: tenantId
          description: 租户ID，用于区分不同租户的数据和验证策略
          in: query
          required: true
          schema:
            type: string
          example: "000000"
        - name: subject
          description: 验证主体，通常为手机号、用户ID或登录账号
          in: query
          schema:
            type: string
          example: "13800000000"
      responses:
        '200':
          $ref: '#/components/responses/VerificationRequireResult'
  /genealogy/app/auth/verification/{operationCode}/challenge:
    post:
      tags: [验证中心]
      summary: 生成 APP 认证动作验证挑战
      description: 服务端按 operationCode 的激活绑定解析场景。tenantId、subject 必须完整提交；clientid 仅从 Header 读取，前端不得提交 clientId 或 sceneCode。
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: operationCode
          description: APP 认证业务动作
          in: path
          required: true
          schema:
            type: string
            enum: [password-login, sms-login, register, forgot-password, phone-change, account-deactivate]
      requestBody:
        $ref: '#/components/requestBodies/VerificationChallenge'
      responses:
        '200':
          $ref: '#/components/responses/VerificationChallengeResult'
  /genealogy/app/auth/verification/{operationCode}/verify:
    post:
      tags: [验证中心]
      summary: 校验 APP 认证动作验证结果并换取 validToken
      description: 必须使用生成挑战时相同的 operationCode、tenantId、subject 和 challengeId。clientid 仅从 Header 读取；服务端重新解析同一路由的激活场景，前端不得提交 clientId 或 sceneCode。
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: operationCode
          description: APP 认证业务动作
          in: path
          required: true
          schema:
            type: string
            enum: [password-login, sms-login, register, forgot-password, phone-change, account-deactivate]
      requestBody:
        $ref: '#/components/requestBodies/VerificationCheck'
      responses:
        '200':
          $ref: '#/components/responses/VerificationCheckResult'
  /genealogy/app/auth/register:
    post:
      tags: [认证登录]
      summary: APP 用户注册
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/PasswordRegister'
      responses:
        '200':
          $ref: '#/components/responses/LoginResult'
        '400':
          description: 短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带 validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RVoid'
  /genealogy/app/auth/login:
    post:
      tags: [认证登录]
      summary: APP 密码登录
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/PasswordLogin'
      responses:
        '200':
          $ref: '#/components/responses/LoginResult'
        '400':
          description: 后端按 APP_PASSWORD_LOGIN 路由的当前激活绑定解析场景；该场景策略要求验证时必须提交匹配的 validToken，不要求验证时 validToken 可为空；请求携带已废弃的 sceneCode 或其他未知字段返回 HTTP 400。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RVoid'
  /genealogy/app/auth/login/sms:
    post:
      tags: [认证登录]
      summary: APP 短信登录
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/SmsLogin'
      responses:
        '200':
          $ref: '#/components/responses/LoginResult'
        '400':
          description: 短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带 validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RVoid'
  /genealogy/app/auth/login/wechat:
    post:
      tags: [认证登录]
      summary: APP 微信授权码登录
      description: 请求体只接收微信一次性 code；clientid、tenant-id 只从 Header 读取。未绑定返回 ACCOUNT_BINDING_REQUIRED，服务端不会自动创建重复账号。
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/TenantIdHeader'
      requestBody: { $ref: '#/components/requestBodies/WechatCode' }
      responses:
        '200': { $ref: '#/components/responses/WechatLoginResult' }
  /genealogy/app/auth/wechat/bind:
    post:
      tags: [认证登录]
      summary: 当前 APP 用户绑定微信身份
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody: { $ref: '#/components/requestBodies/WechatCode' }
      responses:
        '200': { $ref: '#/components/responses/VoidResult' }
  /genealogy/app/referrals/me:
    get:
      tags: [认证登录]
      summary: 当前 APP 用户推荐卡
      description: 推荐关系独立于家谱邀请；响应不暴露内部用户 ID。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200': { $ref: '#/components/responses/ReferralMeResult' }
  /genealogy/app/auth/sms/{operationCode}/code:
    post:
      tags: [认证登录]
      summary: APP 发送短信验证码
      description: operationCode 决定短信业务动作，服务端按对应 APP 路由的激活绑定解析验证场景。策略开启时需提交 validToken，关闭时可为空；前端不得提交 sceneCode 或短信供应商配置 ID。
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: operationCode
          description: 支持发送短信验证码的 APP 认证业务动作
          in: path
          required: true
          schema:
            type: string
            enum: [sms-login, register, forgot-password, phone-change, account-deactivate]
      requestBody:
        $ref: '#/components/requestBodies/SmsCode'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
        '400':
          description: 拒绝原因：票据缺失；票据与租户不匹配（错租户）；票据与客户端不匹配（错客户端）；票据与场景不匹配（错场景）；票据过期；票据已被使用（重复使用）；手机号主体不匹配；请求携带供应商配置或历史字段。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RVoid'
  /genealogy/app/auth/profile:
    get:
      tags: [认证登录]
      summary: APP 当前用户资料
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/AppProfileResult'
    put:
      tags: [认证登录]
      summary: APP 修改用户资料
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/ProfileUpdate'
      responses:
        '200':
          $ref: '#/components/responses/AppProfileResult'
  /genealogy/app/auth/password:
    put:
      tags: [认证登录]
      summary: APP 修改密码
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/PasswordChange'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/app/auth/password/reset:
    put:
      tags: [认证登录]
      summary: APP 找回密码
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/PasswordReset'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
        '400':
          description: 短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带 validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RVoid'
  /genealogy/app/auth/phone:
    put:
      tags: [认证登录]
      summary: APP 换绑手机号
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/PhoneChange'
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
        '400':
          description: 短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带 validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RVoid'
  /genealogy/app/auth/account/deactivate:
    post:
      tags: [认证登录]
      summary: APP 注销账号
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/AccountDeactivate'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
        '400':
          description: 短信验证码必须为 4 位数字；验证码错误、过期、重复使用，或租户、客户端、场景不匹配时拒绝；携带 validToken、code、uuid、供应商配置等旧字段返回 HTTP 400。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RVoid'
  /genealogy/app/auth/logout:
    delete:
      tags: [认证登录]
      summary: APP 退出登录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'

  /genealogy/app/files/resumable/init:
    post:
      tags: [文件上传]
      summary: APP 分片上传初始化
      description: 所有文件统一使用分片上传；普通小文件可设置为一个分片。返回 instant=true 时直接使用返回的 OSS 信息，跳过分片上传和合并。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/ResumableInit'
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
  /genealogy/app/files/resumable/chunk:
    post:
      tags: [文件上传]
      summary: APP 上传分片
      description: uploadId 已绑定初始化契约。除最后一片外，分片实际大小必须等于 chunkSize；最后一片必须等于剩余字节数。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/ChunkUpload'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/app/files/resumable/complete:
    post:
      tags: [文件上传]
      summary: APP 完成分片上传
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/ResumableComplete'
      responses:
        '200':
          $ref: '#/components/responses/FileUploadResult'
  /genealogy/app/region/children:
    get:
      tags: [行政区划]
      summary: 查询下级行政区划
      security: []
      parameters:
        - name: parentCode
          description: 父级行政区划编码，不传或传0查省级
          in: query
          required: false
          schema:
            type: string
          example: "51"
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
  /genealogy/app/region/path/{regionCode}:
    get:
      tags: [行政区划]
      summary: 查询行政区划路径
      security: []
      parameters:
        - $ref: '#/components/parameters/RegionCode'
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
  /genealogy/app/region/search:
    get:
      tags: [行政区划]
      summary: 搜索行政区划
      security: []
      parameters:
        - name: keyword
          description: 搜索关键词，支持地区名称或编码模糊查询
          in: query
          required: true
          schema:
            type: string
          example: 北京
        - name: level
          description: 行政区划级别，1省、2市、3区县、4乡镇街道、5村社区
          in: query
          required: false
          schema:
            type: integer
          example: 3
        - name: limit
          description: 返回数量上限
          in: query
          required: false
          schema:
            type: integer
          example: 20
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
  /genealogy/app/region/{regionCode}:
    get:
      tags: [行政区划]
      summary: 查询行政区划详情
      security: []
      parameters:
        - $ref: '#/components/parameters/RegionCode'
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
  /genealogy/app/site/articles:
    get:
      tags: [官网内容]
      summary: APP 查询官网文章
      security: []
      parameters:
        - name: articleType
          description: 文章类型，不传则查询全部已发布文章
          in: query
          required: false
          schema: { type: string }
        - name: limit
          description: 返回数量上限
          in: query
          required: false
          schema: { type: integer }
      responses:
        '200': { $ref: '#/components/responses/AppArticleListResult' }
  /genealogy/app/site/pages/{pageKey}:
    get:
      tags: [官网内容]
      summary: APP 查询官网单页
      security: []
      parameters:
        - name: pageKey
          description: 单页唯一标识
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/ObjectResult' }

  /genealogy/app/genealogies:
    post:
      tags: [家谱]
      summary: APP 创建家谱
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/GenealogyCreate'
      responses:
        '200':
          $ref: '#/components/responses/AppGenealogyResult'
  /genealogy/app/genealogies/mine:
    get:
      tags: [家谱]
      summary: APP 我的家谱
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/AppGenealogyListResult'
  /genealogy/app/genealogies/mine/order:
    put:
      tags: [家谱]
      summary: APP 保存我的家谱排序
      description: 必须提交当前可见家谱的完整、无重复编号集合；保存后返回后端确认的精确顺序。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/GenealogyUserOrder'
      responses:
        '200':
          $ref: '#/components/responses/AppGenealogyListResult'
  /genealogy/app/genealogies/quota:
    get:
      tags: [家谱]
      summary: APP 查询当前用户家谱配额
      description: 查询已创建和已加入的家谱数量、上限、剩余额度及是否还能继续操作。加入总数包含自己创建的家谱；limit 和 remaining 为 -1 时表示不限。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/GenealogyQuotaResult'
  /genealogy/app/genealogies/public:
    get:
      tags: [家谱]
      summary: APP 公开家谱
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/AppGenealogyListResult'
  /genealogy/app/genealogies/options:
    get:
      tags: [家谱]
      summary: APP 家谱下拉选项
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
  /genealogy/app/genealogies/{genealogyId}:
    get:
      tags: [家谱]
      summary: APP 家谱详情
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/AppGenealogyResult'
    put:
      tags: [家谱]
      summary: APP 修改家谱
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/GenealogyUpdate'
      responses:
        '200':
          $ref: '#/components/responses/AppGenealogyResult'
  /genealogy/app/genealogies/{genealogyId}/overview:
    get:
      tags: [家谱]
      summary: APP 家谱概览
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
  /genealogy/app/genealogies/{genealogyId}/completeness:
    get:
      tags: [家谱]
      summary: APP 查询家谱资料完整度
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/GenealogyCompletenessResult'
  /genealogy/app/genealogies/{genealogyId}/archive:
    put:
      tags: [家谱]
      summary: APP 归档家谱
      description: 仅谱主可操作；归档后家谱保持可读，内容写入被拒绝。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/AppGenealogyResult'
  /genealogy/app/genealogies/{genealogyId}/restore:
    put:
      tags: [家谱]
      summary: APP 恢复已归档家谱
      description: 仅谱主可恢复；处于物理删除任务中的家谱不能恢复。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/AppGenealogyResult'
  /genealogy/app/genealogies/{genealogyId}/join-applies:
    post:
      tags: [家谱]
      summary: APP 申请加入家谱
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/GenealogyJoinApply'
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'
  /genealogy/app/genealogies/{genealogyId}/invitations:
    post:
      tags: [家谱邀请]
      summary: APP 签发一次性家谱邀请
      description: 仅当前家谱有效成员可签发；原始 token 只在本次响应返回，有效期默认 7 天。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/GenealogyInvitationIssueBody' }
      responses:
        '200':
          $ref: '#/components/responses/GenealogyInvitationResult'
  /genealogy/app/genealogies/invitations/preview:
    get:
      tags: [家谱邀请]
      summary: APP 预览家谱邀请
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: token
          in: query
          required: true
          schema: { type: string, maxLength: 128 }
      responses:
        '200':
          $ref: '#/components/responses/GenealogyInvitationResult'
  /genealogy/app/genealogies/invitations/redeem:
    post:
      tags: [家谱邀请]
      summary: APP 兑换家谱邀请
      description: 邀请只可成功兑换一次；结果服从家谱加入模式，服务端从 token 推导邀请人。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenealogyInvitationRedeemBody'
      responses:
        '200':
          $ref: '#/components/responses/GenealogyInvitationResult'
  /genealogy/app/genealogies/invitations/mine:
    get:
      tags: [家谱邀请]
      summary: APP 我的家谱邀请记录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/GenealogyInvitationListResult'
  /genealogy/app/genealogies/invitations/{inviteId}:
    delete:
      tags: [家谱邀请]
      summary: APP 撤销本人发出的未使用邀请
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: inviteId
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/app/genealogies/join-applies/mine:
    get:
      tags: [家谱]
      summary: APP 我的加入申请
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
  /genealogy/app/genealogies/{genealogyId}/join-applies/pending:
    get:
      tags: [家谱]
      summary: APP 待审核加入申请
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
  /genealogy/app/genealogies/{genealogyId}/join-applies/{applyId}/audit:
    put:
      tags: [家谱]
      summary: APP 审核加入申请
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: applyId
          description: 加入家谱申请ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        $ref: '#/components/requestBodies/GenealogyJoinAudit'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/app/genealogies/join-applies/{applyId}:
    delete:
      tags: [家谱]
      summary: APP 撤销加入申请
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: applyId
          description: 加入家谱申请ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'

  /genealogy/app/genealogies/{genealogyId}/members:
    get:
      tags: [家谱成员]
      summary: APP 家谱成员列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/AppGenealogyMemberListResult'
  /genealogy/app/genealogies/{genealogyId}/members/options:
    get:
      tags: [家谱成员]
      summary: APP 家谱成员选项
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/GenealogyMemberOptionListResult'
  /genealogy/app/genealogies/{genealogyId}/members/{memberId}:
    put:
      tags: [家谱成员]
      summary: APP 修改成员
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/MemberId'
      requestBody:
        $ref: '#/components/requestBodies/GenealogyMemberUpdate'
      responses:
        '200':
          $ref: '#/components/responses/AppGenealogyMemberResult'
    delete:
      tags: [家谱成员]
      summary: APP 移除成员
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/MemberId'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/app/genealogies/{genealogyId}/members/{memberId}/lineage-person:
    delete:
      tags: [家谱成员]
      summary: APP 解除成员与世系人物绑定
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/MemberId'
      responses:
        '200': { $ref: '#/components/responses/VoidResult' }
  /genealogy/app/genealogies/{genealogyId}/members/me:
    delete:
      tags: [家谱成员]
      summary: APP 退出家谱
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/app/genealogies/{genealogyId}/members/owner-transfer:
    put:
      tags: [家谱成员]
      summary: APP 转让家谱所有者
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/GenealogyOwnerTransfer'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'

  /genealogy/app/genealogies/{genealogyId}/generation-poems:
    get:
      tags: [字辈谱]
      summary: APP 查询正常字辈谱
      description: 对可查看家谱的业务用户开放；仅返回正常状态字辈，供世系人物录入和展示使用。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/GenerationPoemListResult'
    post:
      tags: [字辈谱]
      summary: APP 新增字辈
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/GenerationPoem'
      responses:
        '200':
          $ref: '#/components/responses/GenerationPoemResult'
  /genealogy/app/genealogies/{genealogyId}/generation-poems/management:
    get:
      tags: [字辈谱]
      summary: APP 查询字辈维护列表
      description: 仅家谱内容编辑者可访问，返回正常和停用字辈，用于恢复、纠错和排序调整。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/GenerationPoemListResult'
  /genealogy/app/genealogies/{genealogyId}/generation-poems/batch/preview:
    post:
      tags: [字辈谱]
      summary: APP 批量字辈预览
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/GenerationPoemBatch'
      responses:
        '200':
          $ref: '#/components/responses/GenerationPoemBatchPreviewResult'
  /genealogy/app/genealogies/{genealogyId}/generation-poems/batch/save:
    post:
      tags: [字辈谱]
      summary: APP 批量保存字辈
      description: 保存时会重新按当前数据生成差异；停用不删除历史字辈记录。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/GenerationPoemBatch'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/app/genealogies/{genealogyId}/generation-poems/{poemId}:
    put:
      tags: [字辈谱]
      summary: APP 修改、停用或恢复字辈
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: poemId
          description: 字辈记录ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        $ref: '#/components/requestBodies/GenerationPoem'
      responses:
        '200':
          $ref: '#/components/responses/GenerationPoemResult'

  /genealogy/app/genealogies/{genealogyId}/lineage/persons:
    get:
      tags: [世系人物]
      summary: APP 世系人物列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonListResult'
    post:
      tags: [世系人物]
      summary: APP 新增世系人物
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/LineagePerson'
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonDetailResult'
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/page:
    get:
      tags: [世系人物]
      summary: APP 世系人物分页
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/PageNum'
        - $ref: '#/components/parameters/PageSize'
        - name: keyword
          description: 姓名、别名或人物编号关键词
          in: query
          required: false
          schema:
            type: string
        - name: generation
          description: 世代序号
          in: query
          required: false
          schema:
            type: integer
            format: int64
        - name: personStatus
          description: "字典 gen_lineage_person_status：0=健在，1=已故，2=未知"
          in: query
          required: false
          schema:
            type: string
            enum: ["0", "1", "2"]
            example: "0"
            x-dict-type: gen_lineage_person_status
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonPageResult'
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/options:
    get:
      tags: [世系人物]
      summary: APP 世系人物选项
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: keyword
          description: 姓名、别名或人物编号关键词
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonListResult'
  /genealogy/app/genealogies/{genealogyId}/lineage/ranks:
    get:
      tags: [世系人物]
      summary: APP 世系人物排行选项
      description: 按当前家谱、世代和性别返回可用排行。第一世可返回“始祖”，其他世代返回“长子、次子、长女、次女”等配置。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: generation
          description: 世代序号
          in: query
          required: true
          schema: { type: integer, format: int64, minimum: 1, example: 2 }
        - name: sex
          description: "字典 sys_user_sex：0=男，1=女，2=未知"
          in: query
          required: true
          schema: { type: string, enum: ["0", "1", "2"], example: "0", x-dict-type: sys_user_sex }
      responses:
        '200':
          $ref: '#/components/responses/LineageRankOptionListResult'
  /genealogy/app/genealogies/{genealogyId}/lineage/tree:
    get:
      tags: [世系人物]
      summary: APP 世系树
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonTreeResult'
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}:
    get:
      tags: [世系人物]
      summary: APP 世系人物详情
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/PersonId'
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonDetailResult'
    put:
      tags: [世系人物]
      summary: APP 修改世系人物
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/PersonId'
      requestBody:
        $ref: '#/components/requestBodies/LineagePerson'
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonDetailResult'
    delete:
      tags: [世系人物]
      summary: APP 停用世系人物
      description: 逻辑停用人物，不执行物理删除；存在正常子女时拒绝停用。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/PersonId'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/sensitive-profile:
    get:
      tags: [世系人物]
      summary: APP 读取世系人物敏感健康资料
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/PersonId'
      responses:
        '200': { $ref: '#/components/responses/LineagePersonSensitiveProfileResult' }
    put:
      tags: [世系人物]
      summary: APP 保存世系人物敏感健康资料
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/PersonId'
      requestBody: { $ref: '#/components/requestBodies/LineagePersonSensitiveProfile' }
      responses:
        '200': { $ref: '#/components/responses/LineagePersonSensitiveProfileResult' }
    delete:
      tags: [世系人物]
      summary: APP 清空世系人物敏感健康资料
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/PersonId'
      responses:
        '200': { $ref: '#/components/responses/LineagePersonSensitiveProfileResult' }
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/relations:
    delete:
      tags: [世系人物]
      summary: APP 删除指定世系关系
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/PersonId'
      requestBody: { $ref: '#/components/requestBodies/LineageRelationRemove' }
      responses:
        '200': { $ref: '#/components/responses/VoidResult' }
  /genealogy/app/genealogies/{genealogyId}/permission-catalog:
    get:
      tags: [家谱成员]
      summary: APP 查询家谱管理员权限目录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200': { $ref: '#/components/responses/GenealogyMemberPermissionCatalogListResult' }
  /genealogy/app/genealogies/{genealogyId}/members/{memberId}/permissions:
    get:
      tags: [家谱成员]
      summary: APP 查询家谱管理员权限
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/MemberId'
      responses:
        '200': { $ref: '#/components/responses/GenealogyMemberPermissionResult' }
    put:
      tags: [家谱成员]
      summary: APP 完整替换家谱管理员权限
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/MemberId'
      requestBody: { $ref: '#/components/requestBodies/GenealogyMemberPermission' }
      responses:
        '200': { $ref: '#/components/responses/GenealogyMemberPermissionResult' }
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/sort-order:
    put:
      tags: [世系人物]
      summary: APP 调整世系人物排行
      description: 仅家谱所有者或管理员可调用，只更新 sortOrder。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/PersonId'
      requestBody: { $ref: '#/components/requestBodies/LineagePersonSortOrder' }
      responses:
        '200': { $ref: '#/components/responses/LineagePersonResult' }
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/children:
    post:
      tags: [世系人物]
      summary: APP 给人物添加子女
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/PersonId'
      requestBody:
        $ref: '#/components/requestBodies/LineagePerson'
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonResult'
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/parents:
    post:
      tags: [世系人物]
      summary: APP 给人物添加父母
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/PersonId'
      requestBody:
        $ref: '#/components/requestBodies/LineagePerson'
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonResult'
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/siblings:
    post:
      tags: [世系人物]
      summary: APP 给人物添加兄弟姐妹
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/PersonId'
      requestBody:
        $ref: '#/components/requestBodies/LineagePerson'
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonResult'
  /genealogy/app/genealogies/{genealogyId}/lineage/persons/{personId}/spouses:
    post:
      tags: [世系人物]
      summary: APP 给人物添加配偶
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/PersonId'
      requestBody:
        $ref: '#/components/requestBodies/LineagePerson'
      responses:
        '200':
          $ref: '#/components/responses/LineagePersonResult'

  /genealogy/app/genealogies/{genealogyId}/feeds:
    get:
      tags: [家族圈]
      summary: APP 家族圈动态列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedListResult'
    post:
      tags: [家族圈]
      summary: APP 发布家族圈动态
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/FamilyFeed'
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedResult'
  /genealogy/app/genealogies/{genealogyId}/feeds/page:
    get:
      tags: [家族圈]
      summary: APP 家族圈动态分页
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/PageNum'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedPageResult'
  /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}:
    get:
      tags: [家族圈]
      summary: APP 家族圈动态详情
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/FeedId'
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedResult'
    put:
      tags: [家族圈]
      summary: APP 修改家族圈动态
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/FeedId'
      requestBody:
        $ref: '#/components/requestBodies/FamilyFeed'
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedResult'
    delete:
      tags: [家族圈]
      summary: APP 删除家族圈动态
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/FeedId'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/likes:
    post:
      tags: [家族圈]
      summary: APP 点赞动态
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/FeedId'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
    delete:
      tags: [家族圈]
      summary: APP 取消点赞动态
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/FeedId'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/comments:
    get:
      tags: [家族圈]
      summary: APP 动态一级评论列表
      description: 仅返回正常展示的一级评论；每条评论的 replyCount 为正常展示的直接回复数量。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/FeedId'
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedCommentListResult'
    post:
      tags: [家族圈]
      summary: APP 评论动态
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/FeedId'
      requestBody:
        $ref: '#/components/requestBodies/FamilyFeedComment'
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedCommentResult'
  /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/comments/page:
    get:
      tags: [家族圈]
      summary: APP 动态一级评论分页
      description: 仅返回正常展示的一级评论；展开回复时请调用 replies 接口。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/FeedId'
        - $ref: '#/components/parameters/PageNum'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedCommentPageResult'
  /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/comments/{commentId}/replies:
    get:
      tags: [家族圈]
      summary: APP 获取评论的直接回复列表
      description: 仅返回指定正常评论的正常展示直接回复；回复的 replyCount 可用于继续按需展开下一层。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/FeedId'
        - name: commentId
          description: 父评论 ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedCommentListResult'
  /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/comments/{commentId}/replies/page:
    get:
      tags: [家族圈]
      summary: APP 分页获取评论的直接回复
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/FeedId'
        - name: commentId
          description: 父评论 ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - $ref: '#/components/parameters/PageNum'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          $ref: '#/components/responses/FamilyFeedCommentPageResult'
  /genealogy/app/genealogies/{genealogyId}/feeds/{feedId}/comments/{commentId}:
    delete:
      tags: [家族圈]
      summary: APP 删除本人动态评论；有回复时保留删除占位
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - $ref: '#/components/parameters/FeedId'
        - name: commentId
          description: 评论ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'

  /genealogy/app/genealogies/{genealogyId}/article-categories:
    get:
      tags: [内容文章]
      summary: APP 谱文分类
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/AppArticleCategoryOptionListResult'
    post:
      tags: [内容文章]
      summary: APP 新增谱文分类
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/ArticleCategory'
      responses:
        '200':
          $ref: '#/components/responses/AppArticleCategoryResult'
  /genealogy/app/genealogies/{genealogyId}/article-categories/{categoryId}:
    put:
      tags: [内容文章]
      summary: APP 修改谱文分类
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: categoryId
          description: 谱文分类ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        $ref: '#/components/requestBodies/ArticleCategory'
      responses:
        '200':
          $ref: '#/components/responses/AppArticleCategoryResult'
  /genealogy/app/genealogies/{genealogyId}/articles:
    get:
      tags: [内容文章]
      summary: APP 谱文列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/AppArticleListResult'
    post:
      tags: [内容文章]
      summary: APP 新增谱文
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/Article'
      responses:
        '200':
          $ref: '#/components/responses/AppArticleResult'
  /genealogy/app/genealogies/{genealogyId}/articles/{articleId}:
    get:
      tags: [内容文章]
      summary: APP 谱文详情
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: X-Content-Access-Token, in: header, required: false, schema: { type: string }, description: 内容密码解锁后获得的短时访问令牌 }
        - name: articleId
          description: 谱文/官网文章ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/AppArticleResult'
    put:
      tags: [内容文章]
      summary: APP 修改谱文
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: articleId
          description: 谱文/官网文章ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        $ref: '#/components/requestBodies/Article'
      responses:
        '200':
          $ref: '#/components/responses/AppArticleResult'
    delete:
      tags: [内容文章]
      summary: APP 删除谱文
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: articleId
          description: 要删除的谱文ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { $ref: '#/components/responses/VoidResult' }
  /genealogy/app/help-articles:
    get:
      tags: [内容文章]
      summary: APP 帮助文章列表
      security: []
      responses:
        '200':
          $ref: '#/components/responses/HelpArticleListResult'
  /genealogy/app/help-articles/{helpId}:
    get:
      tags: [内容文章]
      summary: APP 帮助文章详情
      security: []
      parameters:
        - name: helpId
          description: 帮助文章ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/HelpArticleResult'
  /genealogy/app/promotions:
    get:
      tags: [内容文章]
      summary: APP 应用推广列表
      security: []
      parameters:
        - name: platform
          in: query
          required: true
          description: 客户端平台；all 仅供后台投放配置，客户端请求应传自身平台
          schema: { type: string, enum: [app, pc, wechat] }
        - name: placement
          in: query
          required: true
          description: 推广位稳定编码
          schema: { type: string, enum: [home_banner, home_bottom, message_bottom, profile_bottom] }
      responses:
        '200':
          $ref: '#/components/responses/AppPromotionListResult'

  /genealogy/app/genealogies/{genealogyId}/content-lifecycle/{resourceType}/{resourceId}:
    get:
      tags: [内容生命周期]
      summary: APP 查询内容生命周期状态
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: resourceType, in: path, required: true, schema: { type: string, enum: [family_feed, video, growth_record, relative_record, memo, merit_record, article, album, album_photo, ceremony] } }
        - { name: resourceId, in: path, required: true, schema: { type: integer, format: int64 } }
      responses:
        '200': { $ref: '#/components/responses/ContentLifecycleStatusResult' }
  /genealogy/app/genealogies/{genealogyId}/content-lifecycle/{resourceType}/{resourceId}/restore:
    put:
      tags: [内容生命周期]
      summary: APP 恢复停用内容
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: resourceType, in: path, required: true, schema: { type: string, enum: [family_feed, video, growth_record, relative_record, memo, merit_record, article, album, album_photo, ceremony] } }
        - { name: resourceId, in: path, required: true, schema: { type: integer, format: int64 } }
      responses:
        '200': { $ref: '#/components/responses/ContentLifecycleStatusResult' }

  /genealogy/app/genealogies/{genealogyId}/albums:
    get:
      tags: [相册]
      summary: APP 相册列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/AppAlbumListResult'
    post:
      tags: [相册]
      summary: APP 创建相册
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/Album'
      responses:
        '200':
          $ref: '#/components/responses/AppAlbumResult'
  /genealogy/app/genealogies/{genealogyId}/albums/{albumId}:
    put:
      tags: [相册]
      summary: APP 修改相册
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: albumId
          description: 相册ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        $ref: '#/components/requestBodies/Album'
      responses:
        '200':
          $ref: '#/components/responses/AppAlbumResult'
    delete:
      tags: [相册]
      summary: APP 删除相册
      description: 逻辑删除相册及其照片，并释放封面和照片文件引用。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: albumId
          description: 要删除的相册ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { $ref: '#/components/responses/VoidResult' }
  /genealogy/app/genealogies/{genealogyId}/albums/{albumId}/photos:
    get:
      tags: [相册]
      summary: APP 相册图片列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: albumId
          description: 相册ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/AppAlbumPhotoListResult'
    post:
      tags: [相册]
      summary: APP 上传相册图片记录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: albumId
          description: 相册ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        $ref: '#/components/requestBodies/AlbumPhoto'
      responses:
        '200':
          $ref: '#/components/responses/AppAlbumPhotoResult'
  /genealogy/app/genealogies/{genealogyId}/albums/{albumId}/photos/{photoId}:
    delete:
      tags: [相册]
      summary: APP 删除单张相册图片
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: albumId
          description: 相册ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
        - name: photoId
          description: 要删除的相册图片ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { $ref: '#/components/responses/VoidResult' }

  /genealogy/app/genealogies/{genealogyId}/videos:
    get:
      tags: [视频]
      summary: APP 视频列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200': { $ref: '#/components/responses/AppVideoListResult' }
    post:
      tags: [视频]
      summary: APP 新增视频
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/Video'
      responses:
        '200': { $ref: '#/components/responses/AppVideoResult' }
  /genealogy/app/genealogies/{genealogyId}/videos/{videoId}:
    get:
      tags: [视频]
      summary: APP 视频详情
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: videoId
          description: 视频ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { $ref: '#/components/responses/AppVideoResult' }
    put:
      tags: [视频]
      summary: APP 修改视频
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: videoId
          description: 视频ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
      requestBody:
        $ref: '#/components/requestBodies/Video'
      responses:
        '200': { $ref: '#/components/responses/AppVideoResult' }
    delete:
      tags: [视频]
      summary: APP 删除视频
      description: 逻辑删除视频，并释放视频文件和封面文件引用。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: videoId
          description: 要删除的视频ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { $ref: '#/components/responses/VoidResult' }

  /genealogy/app/genealogies/{genealogyId}/ceremonies:
    get:
      tags: [祭祀]
      summary: APP 祭祀列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/AppCeremonyListResult'
    post:
      tags: [祭祀]
      summary: APP 创建祭祀
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/Ceremony'
      responses:
        '200':
          $ref: '#/components/responses/AppCeremonyResult'
  /genealogy/app/genealogies/{genealogyId}/ceremonies/{ceremonyId}:
    get:
      tags: [祭祀]
      summary: APP 祭祀详情
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: ceremonyId
          description: 祭祀/活动ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/AppCeremonyResult'
    delete:
      tags: [祭祀]
      summary: APP 删除祭祀活动
      description: 逻辑删除祭祀活动及其祭品，并释放活动封面文件引用。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: ceremonyId
          description: 要删除的祭祀活动ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { $ref: '#/components/responses/VoidResult' }
    put:
      tags: [祭祀]
      summary: APP 修改祭祀
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: ceremonyId
          description: 祭祀/活动ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        $ref: '#/components/requestBodies/Ceremony'
      responses:
        '200':
          $ref: '#/components/responses/AppCeremonyResult'
  /genealogy/app/genealogies/{genealogyId}/ceremonies/{ceremonyId}/gifts:
    get:
      tags: [祭祀]
      summary: APP 祭祀献礼列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: ceremonyId
          description: 祭祀/活动ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/AppCeremonyGiftListResult'
    post:
      tags: [祭祀]
      summary: APP 新增祭祀献礼
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: ceremonyId
          description: 祭祀/活动ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        $ref: '#/components/requestBodies/CeremonyGift'
      responses:
        '200':
          $ref: '#/components/responses/AppCeremonyGiftResult'
  /genealogy/app/genealogies/{genealogyId}/ceremonies/{ceremonyId}/gifts/{giftId}:
    delete:
      tags: [祭祀]
      summary: APP 删除单条祭品
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: ceremonyId
          description: 祭祀活动ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
        - name: giftId
          description: 要删除的祭品ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { $ref: '#/components/responses/VoidResult' }

  /genealogy/app/genealogies/{genealogyId}/ceremonies/{ceremonyId}/invitee-options:
    get:
      tags: [贺礼邀约]
      summary: APP 查询可邀请成员候选
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: ceremonyId, in: path, required: true, schema: { type: integer, format: int64 } }
        - { name: keyword, in: query, required: false, schema: { type: string } }
      responses:
        '200': { $ref: '#/components/responses/CeremonyInviteeOptionListResult' }
  /genealogy/app/genealogies/{genealogyId}/ceremonies/{ceremonyId}/invitees:
    put:
      tags: [贺礼邀约]
      summary: APP 替换活动受邀人
      description: 使用完整名单替换当前待响应受邀人；仅家谱内容管理员可操作，受邀人必须是同一家谱的正常成员。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: ceremonyId, description: 贺礼活动ID, in: path, required: true, schema: { type: integer, format: int64 } }
      requestBody:
        $ref: '#/components/requestBodies/CeremonyInvitees'
      responses:
        '200': { $ref: '#/components/responses/CeremonyInvitationListResult' }
  /genealogy/app/genealogies/{genealogyId}/ceremonies/{ceremonyId}/invitations:
    get:
      tags: [贺礼邀约]
      summary: APP 查询活动邀请名单
      description: 查询受邀人及其待响应、接受、拒绝或取消状态，仅家谱内容管理员可见。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: ceremonyId, description: 贺礼活动ID, in: path, required: true, schema: { type: integer, format: int64 } }
      responses:
        '200': { $ref: '#/components/responses/CeremonyInvitationListResult' }
  /genealogy/app/genealogies/{genealogyId}/ceremonies/{ceremonyId}/invitations/me:
    put:
      tags: [贺礼邀约]
      summary: APP 响应当前用户的活动邀请
      description: 当前登录用户接受或拒绝自己的待响应邀请，不能代替其他用户操作。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: ceremonyId, description: 贺礼活动ID, in: path, required: true, schema: { type: integer, format: int64 } }
      requestBody:
        $ref: '#/components/requestBodies/CeremonyInvitationResponse'
      responses:
        '200': { $ref: '#/components/responses/CeremonyInvitationResult' }
  /genealogy/app/genealogies/ceremony-invitations/mine:
    get:
      tags: [贺礼邀约]
      summary: APP 查询我的活动邀请
      description: 查询当前租户下发给当前业务用户且活动仍正常的邀请。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200': { $ref: '#/components/responses/CeremonyInvitationListResult' }

  /genealogy/app/genealogies/{genealogyId}/growth-records:
    get:
      tags: [族务记录]
      summary: APP 成长记录列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/AppGrowthRecordListResult'
    post:
      tags: [族务记录]
      summary: APP 新增成长记录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/GrowthRecord'
      responses:
        '200':
          $ref: '#/components/responses/AppGrowthRecordResult'
  /genealogy/app/genealogies/{genealogyId}/growth-records/{recordId}:
    get:
      tags: [族务记录]
      summary: APP 成长记录详情
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: X-Content-Access-Token, in: header, required: false, schema: { type: string }, description: 内容密码解锁后获得的短时访问令牌 }
        - name: recordId
          description: 记录ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/AppGrowthRecordResult'
    delete:
      tags: [族务记录]
      summary: APP 删除成长记录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: recordId
          description: 要删除的成长记录ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { $ref: '#/components/responses/VoidResult' }
    put:
      tags: [族务记录]
      summary: APP 修改成长记录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: recordId
          description: 记录ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        $ref: '#/components/requestBodies/GrowthRecord'
      responses:
        '200':
          $ref: '#/components/responses/AppGrowthRecordResult'
  /genealogy/app/genealogies/{genealogyId}/lineage-persons/{lineagePersonId}/life-events:
    get:
      tags: [人生大事]
      summary: APP 查询世系人物人生大事
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: lineagePersonId, description: 世系人物ID, in: path, required: true, schema: { type: integer, format: int64 } }
      responses:
        '200': { $ref: '#/components/responses/LifeEventListResult' }
    post:
      tags: [人生大事]
      summary: APP 新增世系人物人生大事
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: lineagePersonId, description: 世系人物ID, in: path, required: true, schema: { type: integer, format: int64 } }
      requestBody:
        $ref: '#/components/requestBodies/LifeEvent'
      responses:
        '200': { $ref: '#/components/responses/LifeEventResult' }
  /genealogy/app/genealogies/{genealogyId}/lineage-persons/{lineagePersonId}/life-events/{eventId}:
    get:
      tags: [人生大事]
      summary: APP 查询人生大事详情
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: lineagePersonId, description: 世系人物ID, in: path, required: true, schema: { type: integer, format: int64 } }
        - { name: eventId, description: 人生大事ID, in: path, required: true, schema: { type: integer, format: int64 } }
      responses:
        '200': { $ref: '#/components/responses/LifeEventResult' }
    put:
      tags: [人生大事]
      summary: APP 修改世系人物人生大事
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: lineagePersonId, description: 世系人物ID, in: path, required: true, schema: { type: integer, format: int64 } }
        - { name: eventId, description: 人生大事ID, in: path, required: true, schema: { type: integer, format: int64 } }
      requestBody:
        $ref: '#/components/requestBodies/LifeEvent'
      responses:
        '200': { $ref: '#/components/responses/LifeEventResult' }
    delete:
      tags: [人生大事]
      summary: APP 删除世系人物人生大事
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: lineagePersonId, description: 世系人物ID, in: path, required: true, schema: { type: integer, format: int64 } }
        - { name: eventId, description: 人生大事ID, in: path, required: true, schema: { type: integer, format: int64 } }
      responses:
        '200': { $ref: '#/components/responses/VoidResult' }
  /genealogy/app/genealogies/{genealogyId}/memos:
    get:
      tags: [族务记录]
      summary: APP 备忘录列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/AppMemoListResult'
    post:
      tags: [族务记录]
      summary: APP 新增备忘录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/Memo'
      responses:
        '200':
          $ref: '#/components/responses/AppMemoResult'
  /genealogy/app/genealogies/{genealogyId}/memos/{memoId}:
    get:
      tags: [族务记录]
      summary: APP 备忘录详情
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: memoId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/AppMemoResult'
    delete:
      tags: [族务记录]
      summary: APP 删除备忘录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: memoId
          description: 要删除的备忘录ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { $ref: '#/components/responses/VoidResult' }
    put:
      tags: [族务记录]
      summary: APP 修改备忘录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: memoId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        $ref: '#/components/requestBodies/Memo'
      responses:
        '200':
          $ref: '#/components/responses/AppMemoResult'

  /genealogy/app/genealogies/{genealogyId}/relative-records:
    get:
      tags: [族务记录]
      summary: APP 亲友记录列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200': { $ref: '#/components/responses/AppRelativeRecordListResult' }
    post:
      tags: [族务记录]
      summary: APP 新增亲友记录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/RelativeRecord'
      responses:
        '200': { $ref: '#/components/responses/AppRelativeRecordResult' }
  /genealogy/app/genealogies/{genealogyId}/relative-records/{relativeId}:
    get:
      tags: [族务记录]
      summary: APP 亲友记录详情
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: relativeId, description: 亲友记录ID, in: path, required: true, schema: { type: integer, format: int64 } }
      responses:
        '200': { $ref: '#/components/responses/AppRelativeRecordResult' }
    put:
      tags: [族务记录]
      summary: APP 修改亲友记录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - { name: relativeId, description: 亲友记录ID, in: path, required: true, schema: { type: integer, format: int64 } }
      requestBody:
        $ref: '#/components/requestBodies/RelativeRecord'
      responses:
        '200': { $ref: '#/components/responses/AppRelativeRecordResult' }
    delete:
      tags: [族务记录]
      summary: APP 删除亲友记录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: relativeId
          description: 要删除的亲友记录ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { $ref: '#/components/responses/VoidResult' }
  /genealogy/app/genealogies/{genealogyId}/merit-records:
    get:
      tags: [族务记录]
      summary: APP 功德记录列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      responses:
        '200':
          $ref: '#/components/responses/AppMeritRecordListResult'
    post:
      tags: [族务记录]
      summary: APP 新增功德记录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
      requestBody:
        $ref: '#/components/requestBodies/MeritRecord'
      responses:
        '200':
          $ref: '#/components/responses/AppMeritRecordResult'
  /genealogy/app/genealogies/{genealogyId}/merit-records/{meritId}:
    get:
      tags: [族务记录]
      summary: APP 功德记录详情
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: meritId
          description: 功德记录ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { $ref: '#/components/responses/AppMeritRecordResult' }
    put:
      tags: [族务记录]
      summary: APP 修改功德记录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: meritId
          description: 功德记录ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
      requestBody:
        $ref: '#/components/requestBodies/MeritRecord'
      responses:
        '200': { $ref: '#/components/responses/AppMeritRecordResult' }
    delete:
      tags: [族务记录]
      summary: APP 删除功德记录
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/GenealogyId'
        - name: meritId
          description: 要删除的功德记录ID
          in: path
          required: true
          schema: { type: integer, format: int64 }
      responses:
        '200': { $ref: '#/components/responses/VoidResult' }

  /genealogy/app/notifications:
    get:
      tags: [消息通知]
      summary: APP 消息通知列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: readStatus
          description: "字典 gen_notification_read_status：0=未读，1=已读；不传则查询全部"
          in: query
          required: false
          schema:
            type: string
            enum: ['0', '1']
            example: "0"
            x-dict-type: gen_notification_read_status
      responses:
        '200':
          $ref: '#/components/responses/AppNotificationListResult'
  /genealogy/app/notifications/{notificationId}:
    get:
      tags: [消息通知]
      summary: APP 消息通知详情
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: notificationId
          description: 通知ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/AppNotificationResult'
  /genealogy/app/notifications/{notificationId}/read:
    post:
      tags: [消息通知]
      summary: APP 标记通知已读
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: notificationId
          description: 通知ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/app/notifications/unread-count:
    get:
      tags: [消息通知]
      summary: APP 查询未读通知数量
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/LongResult'
  /genealogy/app/notifications/read-all:
    post:
      tags: [消息通知]
      summary: APP 全部标记已读
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/VoidResult'
  /genealogy/app/feedback:
    get:
      tags: [意见反馈]
      summary: APP 我的反馈列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/ListResult'
    post:
      tags: [意见反馈]
      summary: APP 提交反馈
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/Feedback'
      responses:
        '200':
          $ref: '#/components/responses/ObjectResult'

  /genealogy/app/vip/capability:
    get:
      tags: [VIP]
      summary: 查询 APP VIP 购买能力
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/VipPurchaseCapabilityResult'
  /genealogy/app/vip/packages:
    get:
      tags: [VIP]
      summary: APP VIP 套餐列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/VipPackageListResult'
  /genealogy/app/vip/orders:
    get:
      tags: [VIP]
      summary: APP VIP 订单列表
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          $ref: '#/components/responses/VipOrderListResult'
    post:
      tags: [VIP]
      summary: APP 创建 VIP 订单
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        $ref: '#/components/requestBodies/VipOrder'
      responses:
        '200':
          $ref: '#/components/responses/PaymentOrderResult'
  /genealogy/app/vip/orders/{transactionId}/payment:
    get:
      operationId: appGetVipOrderPayment
      tags: [VIP]
      summary: APP 查询 VIP 订单支付状态
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: transactionId
          description: 支付流水ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/PaymentTransactionStatusResult'
  /genealogy/app/vip/orders/{transactionId}/close:
    post:
      tags: [VIP]
      summary: APP 关闭未支付 VIP 订单
      description: 用户主动取消当前未支付订单。超过支付有效期仍为 CREATED/PAYING 的订单由内部 SnailJob 任务 paymentAutoCloseJob 自动关闭，不需要客户端调用本接口。
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: transactionId
          description: 支付流水ID
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          $ref: '#/components/responses/PaymentTransactionStatusResult'

  /genealogy/app/earnings/summary:
    get:
      tags: [收益与提现]
      summary: 查询当前用户收益汇总
      responses:
        '200': { description: 收益汇总, content: { application/json: { schema: { $ref: '#/components/schemas/REarningSummary' } } } }
  /genealogy/app/earnings/ledger:
    get:
      tags: [收益与提现]
      summary: 查询当前用户不可变收益流水
      parameters:
        - { name: pageNum, in: query, schema: { type: integer, minimum: 1 } }
        - { name: pageSize, in: query, schema: { type: integer, minimum: 1 } }
      responses:
        '200': { description: 收益流水分页, content: { application/json: { schema: { $ref: '#/components/schemas/EarningLedgerPage' } } } }
  /genealogy/app/earnings/withdrawals:
    get:
      tags: [收益与提现]
      summary: 查询当前用户提现记录
      parameters:
        - { name: pageNum, in: query, schema: { type: integer, minimum: 1 } }
        - { name: pageSize, in: query, schema: { type: integer, minimum: 1 } }
      responses:
        '200': { description: 提现分页, content: { application/json: { schema: { $ref: '#/components/schemas/EarningWithdrawalPage' } } } }
    post:
      tags: [收益与提现]
      summary: 申请提现并冻结可用收益
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/EarningWithdrawalBody' } } } }
      responses:
        '200': { description: 提现申请, content: { application/json: { schema: { $ref: '#/components/schemas/REarningWithdrawal' } } } }
  /genealogy/app/earnings/withdrawals/{withdrawalId}/cancel:
    post:
      tags: [收益与提现]
      summary: 取消待审核提现并解冻余额
      parameters:
        - { name: withdrawalId, in: path, required: true, schema: { type: integer, format: int64 } }
      responses:
        '200': { description: 已取消提现, content: { application/json: { schema: { $ref: '#/components/schemas/REarningWithdrawal' } } } }

  /genealogy/app/genealogies/{genealogyId}/person-documents:
    get:
      tags: [重要证件档案]
      summary: 查询人物证件档案
      parameters:
        - $ref: '#/components/parameters/GenealogyId'
        - { name: lineagePersonId, in: query, required: false, schema: { type: integer, format: int64 } }
      responses:
        '200': { description: 档案列表, content: { application/json: { schema: { $ref: '#/components/schemas/RPersonDocumentList' } } } }
    post:
      tags: [重要证件档案]
      summary: 创建人物证件档案
      parameters: [ { $ref: '#/components/parameters/GenealogyId' } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/PersonDocumentBody' } } } }
      responses:
        '200': { description: 已创建档案, content: { application/json: { schema: { $ref: '#/components/schemas/RPersonDocument' } } } }
  /genealogy/app/genealogies/{genealogyId}/person-documents/{documentId}:
    parameters:
      - $ref: '#/components/parameters/GenealogyId'
      - { name: documentId, in: path, required: true, schema: { type: integer, format: int64 } }
    get:
      tags: [重要证件档案]
      summary: 查询证件档案详情
      parameters: [ { $ref: '#/components/parameters/ContentAccessToken' } ]
      responses:
        '200': { description: 档案详情；未解锁时资源脱敏, content: { application/json: { schema: { $ref: '#/components/schemas/RPersonDocument' } } } }
    put:
      tags: [重要证件档案]
      summary: 更新证件档案元数据
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/PersonDocumentBody' } } } }
      responses: { '200': { description: 已更新, content: { application/json: { schema: { $ref: '#/components/schemas/RPersonDocument' } } } } }
    delete:
      tags: [重要证件档案]
      summary: 删除证件档案并释放文件引用
      responses: { '200': { description: 已删除, content: { application/json: { schema: { $ref: '#/components/schemas/RVoid' } } } } }
  /genealogy/app/genealogies/{genealogyId}/person-documents/{documentId}/resources:
    post:
      tags: [重要证件档案]
      summary: 添加证件文件引用
      parameters:
        - $ref: '#/components/parameters/GenealogyId'
        - { name: documentId, in: path, required: true, schema: { type: integer, format: int64 } }
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/PersonDocumentResourceBody' } } } }
      responses: { '200': { description: 已添加, content: { application/json: { schema: { $ref: '#/components/schemas/RPersonDocumentResource' } } } } }
  /genealogy/app/genealogies/{genealogyId}/person-documents/{documentId}/resources/{resourceId}:
    parameters:
      - $ref: '#/components/parameters/GenealogyId'
      - { name: documentId, in: path, required: true, schema: { type: integer, format: int64 } }
      - { name: resourceId, in: path, required: true, schema: { type: integer, format: int64 } }
    put:
      tags: [重要证件档案]
      summary: 替换证件文件并释放旧引用
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/PersonDocumentResourceBody' } } } }
      responses: { '200': { description: 已替换, content: { application/json: { schema: { $ref: '#/components/schemas/RPersonDocumentResource' } } } } }
    delete:
      tags: [重要证件档案]
      summary: 删除证件文件引用
      responses: { '200': { description: 已删除, content: { application/json: { schema: { $ref: '#/components/schemas/RVoid' } } } } }
  /genealogy/app/genealogies/{genealogyId}/person-documents/{documentId}/resources/{resourceId}/access:
    get:
      tags: [重要证件档案]
      summary: 获取证件文件短时访问地址
      parameters:
        - $ref: '#/components/parameters/GenealogyId'
        - { name: documentId, in: path, required: true, schema: { type: integer, format: int64 } }
        - { name: resourceId, in: path, required: true, schema: { type: integer, format: int64 } }
        - $ref: '#/components/parameters/ContentAccessToken'
      responses: { '200': { description: 短时文件访问对象, content: { application/json: { schema: { $ref: '#/components/schemas/RBusinessFileAccess' } } } } }
  /genealogy/app/genealogies/{genealogyId}/person-documents/{documentId}/content-protection:
    parameters:
      - $ref: '#/components/parameters/GenealogyId'
      - { name: documentId, in: path, required: true, schema: { type: integer, format: int64 } }
    put:
      tags: [内容密码保护]
      summary: 设置或重置证件档案内容密码
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ContentPasswordBody' } } } }
      responses: { '200': { description: 已设置, content: { application/json: { schema: { $ref: '#/components/schemas/RVoid' } } } } }
    delete:
      tags: [内容密码保护]
      summary: 关闭证件档案内容密码
      responses: { '200': { description: 已关闭, content: { application/json: { schema: { $ref: '#/components/schemas/RVoid' } } } } }
  /genealogy/app/genealogies/{genealogyId}/person-documents/{documentId}/content-unlock:
    post:
      tags: [内容密码保护]
      summary: 解锁证件档案内容
      parameters:
        - $ref: '#/components/parameters/GenealogyId'
        - { name: documentId, in: path, required: true, schema: { type: integer, format: int64 } }
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ContentPasswordBody' } } } }
      responses: { '200': { description: 15 分钟访问授权, content: { application/json: { schema: { $ref: '#/components/schemas/RContentAccessGrant' } } } } }
  /genealogy/app/genealogies/{genealogyId}/articles/{articleId}/content-protection:
    parameters:
      - $ref: '#/components/parameters/GenealogyId'
      - { name: articleId, in: path, required: true, schema: { type: integer, format: int64 } }
    put: { tags: [内容密码保护], summary: 设置或重置谱文内容密码, requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ContentPasswordBody' } } } }, responses: { '200': { description: 已设置, content: { application/json: { schema: { $ref: '#/components/schemas/RVoid' } } } } } }
    delete: { tags: [内容密码保护], summary: 关闭谱文内容密码, responses: { '200': { description: 已关闭, content: { application/json: { schema: { $ref: '#/components/schemas/RVoid' } } } } } }
  /genealogy/app/genealogies/{genealogyId}/articles/{articleId}/content-unlock:
    post: { tags: [内容密码保护], summary: 解锁谱文内容, parameters: [ { $ref: '#/components/parameters/GenealogyId' }, { name: articleId, in: path, required: true, schema: { type: integer, format: int64 } } ], requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ContentPasswordBody' } } } }, responses: { '200': { description: 15 分钟访问授权, content: { application/json: { schema: { $ref: '#/components/schemas/RContentAccessGrant' } } } } } }
  /genealogy/app/genealogies/{genealogyId}/growth-records/{recordId}/content-protection:
    parameters:
      - $ref: '#/components/parameters/GenealogyId'
      - { name: recordId, in: path, required: true, schema: { type: integer, format: int64 } }
    put: { tags: [内容密码保护], summary: 设置或重置成长记录内容密码, requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ContentPasswordBody' } } } }, responses: { '200': { description: 已设置, content: { application/json: { schema: { $ref: '#/components/schemas/RVoid' } } } } } }
    delete: { tags: [内容密码保护], summary: 关闭成长记录内容密码, responses: { '200': { description: 已关闭, content: { application/json: { schema: { $ref: '#/components/schemas/RVoid' } } } } } }
  /genealogy/app/genealogies/{genealogyId}/growth-records/{recordId}/content-unlock:
    post: { tags: [内容密码保护], summary: 解锁成长记录内容, parameters: [ { $ref: '#/components/parameters/GenealogyId' }, { name: recordId, in: path, required: true, schema: { type: integer, format: int64 } } ], requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ContentPasswordBody' } } } }, responses: { '200': { description: 15 分钟访问授权, content: { application/json: { schema: { $ref: '#/components/schemas/RContentAccessGrant' } } } } } }
  /genealogy/app/genealogies/{genealogyId}/content-password-recovery/{resourceType}/{resourceId}/capability:
    get:
      tags: [内容密码找回]
      summary: 查询当前用户是否可通过实名手机号找回内容密码
      parameters: [ { $ref: '#/components/parameters/GenealogyId' }, { name: resourceType, in: path, required: true, schema: { type: string, enum: [ARTICLE, GROWTH_RECORD, PERSON_DOCUMENT] } }, { name: resourceId, in: path, required: true, schema: { type: integer, format: int64 } } ]
      responses: { '200': { description: 找回能力, content: { application/json: { schema: { $ref: '#/components/schemas/RContentPasswordRecoveryCapability' } } } } }
  /genealogy/app/genealogies/{genealogyId}/content-password-recovery/{resourceType}/{resourceId}/code:
    post:
      tags: [内容密码找回]
      summary: 向当前实名手机号发送内容密码找回验证码
      parameters: [ { $ref: '#/components/parameters/GenealogyId' }, { name: resourceType, in: path, required: true, schema: { type: string, enum: [ARTICLE, GROWTH_RECORD, PERSON_DOCUMENT] } }, { name: resourceId, in: path, required: true, schema: { type: integer, format: int64 } } ]
      requestBody: { required: false, content: { application/json: { schema: { $ref: '#/components/schemas/ContentPasswordRecoveryCodeBody' } } } }
      responses: { '200': { $ref: '#/components/responses/VoidResult' } }
  /genealogy/app/genealogies/{genealogyId}/content-password-recovery/{resourceType}/{resourceId}/reset:
    post:
      tags: [内容密码找回]
      summary: 校验一次性短信码并重置内容密码
      parameters: [ { $ref: '#/components/parameters/GenealogyId' }, { name: resourceType, in: path, required: true, schema: { type: string, enum: [ARTICLE, GROWTH_RECORD, PERSON_DOCUMENT] } }, { name: resourceId, in: path, required: true, schema: { type: integer, format: int64 } } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ContentPasswordRecoveryResetBody' } } } }
      responses: { '200': { $ref: '#/components/responses/VoidResult' } }
  /genealogy/app/genealogies/{genealogyId}/permanent-deletion/capability:
    get:
      tags: [家谱永久删除]
      summary: 查询家谱永久删除资格和阻断原因
      parameters: [{ $ref: '#/components/parameters/GenealogyId' }]
      responses: { '200': { description: 永久删除能力, content: { application/json: { schema: { $ref: '#/components/schemas/RGenealogyPermanentDeletionCapability' } } } } }
  /genealogy/app/genealogies/{genealogyId}/permanent-deletion/code:
    post:
      tags: [家谱永久删除]
      summary: 向家谱所有者实名手机号发送永久删除验证码
      parameters: [{ $ref: '#/components/parameters/GenealogyId' }]
      requestBody: { required: false, content: { application/json: { schema: { $ref: '#/components/schemas/GenealogyPermanentDeletionCodeBody' } } } }
      responses: { '200': { $ref: '#/components/responses/VoidResult' } }
  /genealogy/app/genealogies/{genealogyId}/permanent-deletion:
    post:
      tags: [家谱永久删除]
      summary: 校验精确家谱名与一次性短信码后提交永久删除任务
      parameters: [{ $ref: '#/components/parameters/GenealogyId' }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/GenealogyPermanentDeletionBody' } } } }
      responses: { '200': { description: 删除任务, content: { application/json: { schema: { $ref: '#/components/schemas/RGenealogyDeletionTask' } } } } }
  /genealogy/app/recommendation-preference:
    get: { tags: [个性化推荐], summary: 读取当前用户推荐偏好, responses: { '200': { description: 当前偏好, content: { application/json: { schema: { $ref: '#/components/schemas/RRecommendationPreference' } } } } } }
    put: { tags: [个性化推荐], summary: 显式开启或关闭个性化推荐, requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/RecommendationPreferenceBody' } } } }, responses: { '200': { description: 已保存, content: { application/json: { schema: { $ref: '#/components/schemas/RRecommendationPreference' } } } } } }
  /genealogy/app/genealogies/{genealogyId}/recommendation-events:
    post: { tags: [个性化推荐], summary: 记录允许列表内的家族圈行为事件, description: 仅在用户显式开启且租户策略启用时记录；tenantId、appUserId 和目标类型由服务端确定。, parameters: [{ $ref: '#/components/parameters/GenealogyId' }], requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/RecommendationEventBody' } } } }, responses: { '200': { description: 幂等事件, content: { application/json: { schema: { $ref: '#/components/schemas/RRecommendationEvent' } } } } } }
  /genealogy/app/genealogies/{genealogyId}/feed-recommendations:
    get: { tags: [个性化推荐], summary: 获取授权且可解释的家族圈推荐, description: 候选集先鉴权；关闭个性化或无信号时回退人工排序和时间排序。, parameters: [{ $ref: '#/components/parameters/GenealogyId' }], responses: { '200': { description: 推荐结果, content: { application/json: { schema: { $ref: '#/components/schemas/RFamilyFeedRecommendationList' } } } } } }
  /genealogy/app/compliance/documents/{documentKey}:
    get:
      tags: [合规文档]
      summary: APP 查询当前生效的合规文档
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/TenantIdHeader'
        - name: documentKey
          in: path
          required: true
          schema: { type: string, enum: [user_agreement, privacy_policy] }
      responses:
        '200': { $ref: '#/components/responses/ComplianceDocumentContentResult' }
  /genealogy/app/compliance/documents/{documentKey}/versions/{versionNo}:
    get:
      tags: [合规文档]
      summary: APP 查询合规文档历史版本
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/TenantIdHeader'
        - name: documentKey
          in: path
          required: true
          schema: { type: string, enum: [user_agreement, privacy_policy] }
        - name: versionNo
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/ComplianceDocumentContentResult' }
  /genealogy/app/genealogies/{genealogyId}/videos/{videoId}/likes:
    post:
      tags: [视频互动]
      summary: 点赞家谱视频
      parameters: [{ $ref: '#/components/parameters/ClientIdHeader' }, { $ref: '#/components/parameters/GenealogyId' }, { name: videoId, in: path, required: true, schema: { type: integer, format: int64 } }]
      responses: { '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/RVideoLike' } } } } }
    delete:
      tags: [视频互动]
      summary: 取消点赞家谱视频
      parameters: [{ $ref: '#/components/parameters/ClientIdHeader' }, { $ref: '#/components/parameters/GenealogyId' }, { name: videoId, in: path, required: true, schema: { type: integer, format: int64 } }]
      responses: { '200': { $ref: '#/components/responses/VoidResult' } }
  /genealogy/app/genealogies/{genealogyId}/videos/{videoId}/comments:
    get:
      tags: [视频互动]
      summary: 查询视频根评论
      parameters: [{ $ref: '#/components/parameters/ClientIdHeader' }, { $ref: '#/components/parameters/GenealogyId' }, { name: videoId, in: path, required: true, schema: { type: integer, format: int64 } }]
      responses: { '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/RVideoCommentList' } } } } }
    post:
      tags: [视频互动]
      summary: 发表评论或回复
      parameters: [{ $ref: '#/components/parameters/ClientIdHeader' }, { $ref: '#/components/parameters/GenealogyId' }, { name: videoId, in: path, required: true, schema: { type: integer, format: int64 } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/VideoCommentBody' } } } }
      responses: { '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/RVideoComment' } } } } }
  /genealogy/app/genealogies/{genealogyId}/videos/{videoId}/comments/{commentId}:
    delete:
      tags: [视频互动]
      summary: 删除本人视频评论
      parameters: [{ $ref: '#/components/parameters/ClientIdHeader' }, { $ref: '#/components/parameters/GenealogyId' }, { name: videoId, in: path, required: true, schema: { type: integer, format: int64 } }, { name: commentId, in: path, required: true, schema: { type: integer, format: int64 } }]
      responses: { '200': { $ref: '#/components/responses/VoidResult' } }
  /genealogy/app/genealogies/{genealogyId}/videos/{videoId}/comments/page:
    get:
      tags: [视频互动]
      summary: 分页查询视频根评论
      parameters: [{ $ref: '#/components/parameters/ClientIdHeader' }, { $ref: '#/components/parameters/GenealogyId' }, { name: videoId, in: path, required: true, schema: { type: integer, format: int64 } }]
      responses: { '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/VideoCommentPage' } } } } }
  /genealogy/app/genealogies/{genealogyId}/videos/{videoId}/comments/{commentId}/replies:
    get:
      tags: [视频互动]
      summary: 查询视频评论回复
      parameters: [{ $ref: '#/components/parameters/ClientIdHeader' }, { $ref: '#/components/parameters/GenealogyId' }, { name: videoId, in: path, required: true, schema: { type: integer, format: int64 } }, { name: commentId, in: path, required: true, schema: { type: integer, format: int64 } }]
      responses: { '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/RVideoCommentList' } } } } }
  /genealogy/app/genealogies/{genealogyId}/videos/{videoId}/comments/{commentId}/replies/page:
    get:
      tags: [视频互动]
      summary: 分页查询视频评论回复
      parameters: [{ $ref: '#/components/parameters/ClientIdHeader' }, { $ref: '#/components/parameters/GenealogyId' }, { name: videoId, in: path, required: true, schema: { type: integer, format: int64 } }, { name: commentId, in: path, required: true, schema: { type: integer, format: int64 } }]
      responses: { '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/VideoCommentPage' } } } } }
  /genealogy/app/platform-videos:
    get:
      tags: [平台宣传视频]
      summary: 查询有效平台宣传视频
      parameters: [{ name: placement, in: query, required: true, schema: { type: string, enum: [home_featured, video_center, profile_featured] } }]
      responses: { '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/RPlatformVideoList' } } } } }
  /genealogy/app/platform-videos/{id}:
    parameters: [{ name: id, in: path, required: true, schema: { type: integer, format: int64 } }]
    get: { tags: [平台宣传视频], summary: 查询平台宣传视频详情, responses: { '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/RPlatformVideo' } } } } } }
  /genealogy/app/platform-videos/{id}/likes:
    parameters: [{ name: id, in: path, required: true, schema: { type: integer, format: int64 } }]
    post: { tags: [平台宣传视频], summary: 点赞平台宣传视频, responses: { '200': { $ref: '#/components/responses/VoidResult' } } }
    delete: { tags: [平台宣传视频], summary: 取消点赞平台宣传视频, responses: { '200': { $ref: '#/components/responses/VoidResult' } } }
  /genealogy/app/platform-videos/{id}/comments:
    parameters: [{ name: id, in: path, required: true, schema: { type: integer, format: int64 } }]
    get: { tags: [平台宣传视频], summary: 查询平台宣传视频评论, responses: { '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/RPlatformVideoCommentList' } } } } } }
    post: { tags: [平台宣传视频], summary: 评论或回复平台宣传视频, requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/PlatformVideoCommentBody' } } } }, responses: { '200': { description: 成功, content: { application/json: { schema: { $ref: '#/components/schemas/RPlatformVideoComment' } } } } } }
  /genealogy/app/platform-videos/{id}/comments/{commentId}:
    parameters: [{ name: id, in: path, required: true, schema: { type: integer, format: int64 } }, { name: commentId, in: path, required: true, schema: { type: integer, format: int64 } }]
    delete: { tags: [平台宣传视频], summary: 删除本人平台宣传视频评论, responses: { '200': { $ref: '#/components/responses/VoidResult' } } }
  /genealogy/app/genealogies/{genealogyId}/recycle-bin/page:
    parameters: [{ name: genealogyId, in: path, required: true, schema: { type: integer, format: int64 } }]
    get:
      tags: [内容回收站]
      summary: 分页查询家谱内容回收站
      description: 仅家谱所有者或拥有 RECYCLE_BIN_MANAGE 权限的管理员可访问。
      responses: { '200': { $ref: '#/components/responses/ContentRecycleItemPageResult' } }
  /genealogy/app/genealogies/{genealogyId}/recycle-bin/{resourceType}/{resourceId}/restore:
    parameters: [{ name: genealogyId, in: path, required: true, schema: { type: integer, format: int64 } }, { name: resourceType, in: path, required: true, schema: { type: string } }, { name: resourceId, in: path, required: true, schema: { type: integer, format: int64 } }]
    put:
      tags: [内容回收站]
      summary: 单项恢复已逻辑删除内容
      responses: { '200': { $ref: '#/components/responses/ContentRecycleItemResult' } }
components:
  securitySchemes:
    SaToken:
      type: apiKey
      in: header
      name: Authorization
      description: 登录后返回的 token。若本地配置使用 sa-token 名称，请按项目实际 token-name 调整。
  parameters:
    ContentAccessToken:
      name: X-Content-Access-Token
      in: header
      required: false
      description: 内容密码校验成功后返回的短时授权令牌
      schema: { type: string }
    ClientIdHeader:
      name: clientid
      description: APP 认证业务请求的 clientid Header 必填；是业务客户端唯一来源；请求体不得提交 clientId，且客户端 clientKey 必须为 app 并与 APP 路由一致。
      in: header
      required: true
      schema:
        type: string
      example: 428a8310cd442757ae699df5d894f051
    TenantIdHeader:
      name: tenantId
      description: 匿名读取合规文档时必填，用于限定公开文档所属租户。
      in: header
      required: true
      schema: { type: string }
      example: '000000'
    PageNum:
      name: pageNum
      description: 页码，从1开始
      in: query
      required: false
      schema:
        type: integer
        default: 1
    PageSize:
      name: pageSize
      description: 每页条数
      in: query
      required: false
      schema:
        type: integer
        default: 10
    GenealogyId:
      name: genealogyId
      description: 家谱ID
      in: path
      required: true
      schema:
        type: integer
        format: int64
      example: 900001001
    MemberId:
      name: memberId
      description: 家谱成员ID
      in: path
      required: true
      schema:
        type: integer
        format: int64
    PersonId:
      name: personId
      description: 世系人物ID
      in: path
      required: true
      schema:
        type: integer
        format: int64
    FeedId:
      name: feedId
      description: 家族动态ID
      in: path
      required: true
      schema:
        type: integer
        format: int64
    RegionCode:
      name: regionCode
      description: 行政区划编码
      in: path
      required: true
      schema:
        type: string
      example: "510000"
  requestBodies:
    JsonObject:
      required: true
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    PasswordRegister:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PasswordRegisterBody'
          example:
            grantType: "password"
            tenantId: "000000"
            phone: "13800000000"
            password: "e10adc3949ba59abbe56e057f20f883e"
            nickName: "测试用户"
            registerSource: "app"
            smsCode: "1234"
            referralCode: "RABC123"
    WechatCode:
      required: true
      content:
        application/json:
          schema: { $ref: '#/components/schemas/WechatCodeBody' }
          example: { code: "wechat-one-time-code" }
    PasswordLogin:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PasswordLoginBody'
          example:
            grantType: "password"
            tenantId: "000000"
            phone: "13800000000"
            password: "e10adc3949ba59abbe56e057f20f883e"
            validToken: "valid-token-from-captcha-verify"
    SmsLogin:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SmsLoginBody'
          example:
            grantType: "sms"
            tenantId: "000000"
            phone: "13800000000"
            smsCode: "1234"
    SmsCode:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SmsCodeBody'
          example:
            tenantId: "000000"
            phone: "13800000000"
            grantType: "sms"
            validToken: "captcha-ticket"
    ProfileUpdate:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProfileUpdateBody'
          example:
            nickName: "张三"
            realName: "张三"
            avatar: 2060000000000000001
            sex: "0"
            birthday: "1990-01-01"
            email: "zhangsan@example.com"
    PasswordChange:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PasswordChangeBody'
          example:
            oldPassword: "e10adc3949ba59abbe56e057f20f883e"
            newPassword: "25d55ad283aa400af464c76d713c07ad"
    PasswordReset:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PasswordResetBody'
          example:
            grantType: "password"
            tenantId: "000000"
            phone: "13800000000"
            smsCode: "1234"
            newPassword: "25d55ad283aa400af464c76d713c07ad"
    PhoneChange:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PhoneChangeBody'
          example:
            phone: "13900000000"
            smsCode: "1234"
    AccountDeactivate:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountDeactivateBody'
          example:
            smsCode: "1234"
    ChunkUpload:
      required: true
      content:
        multipart/form-data:
          schema:
            type: object
            required: [uploadId, chunkIndex, chunkMd5, file]
            properties:
              uploadId:
                type: string
              chunkIndex:
                type: integer
                example: 0
              chunkMd5:
                type: string
                example: d41d8cd98f00b204e9800998ecf8427e
              file:
                type: string
                format: binary
    ResumableInit:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResumableInitBody'
          example:
            uploadId: "UPLOAD202607090001"
            fileName: "cover.jpg"
            fileMd5: "d41d8cd98f00b204e9800998ecf8427e"
            totalSize: 9532
            totalChunks: 1
            chunkSize: 4194304
            contentType: "image/jpeg"
    ResumableComplete:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResumableCompleteBody'
          example:
            uploadId: "UPLOAD202607090001"
            fileName: "cover.jpg"
            fileMd5: "d41d8cd98f00b204e9800998ecf8427e"
            totalSize: 9532
            totalChunks: 1
    GenerationPoemBatch:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenerationPoemBatchBody'
          example:
            poemText: "德承家亦\n忠厚传芳"
            disableMissing: false
    LineagePerson:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LineagePersonBody'
          example:
            bindingMode: NONE
            personNo: "P202607090001"
            name: "彭德明"
            aliasName: "德明"
            sex: "0"
            generation: 1
            generationName: "德"
            avatarOssId: "2060000000000000001"
            birthDate: "1950-01-01"
            birthLunar: "0"
            birthPlace: "江西吉安"
            personStatus: "0"
            biography: "第一世人物简介"
            sortOrder: 1
    LineagePersonSensitiveProfile:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LineagePersonSensitiveProfileBody'
          example:
            hereditaryMedicalHistory: "高血压家族史"
    LineagePersonSortOrder:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LineagePersonSortOrderBody'
          example:
            sortOrder: 100
    LineageRelationRemove:
      required: true
      content:
        application/json:
          schema: { $ref: '#/components/schemas/LineageRelationRemoveBody' }
          example: { relativePersonId: 900020002, relationType: spouse }
    FamilyFeed:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FamilyFeedBody'
          example:
            feedType: "text"
            feedContent: "今天上传一张老照片。"
            mediaOssIds: "2060000000000000001,2060000000000000002"
            sortOrder: 0
            status: "0"
    FamilyFeedComment:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FamilyFeedCommentBody'
          example:
            parentCommentId: null
            commentContent: "这张照片很有年代感。"
    GenealogyCreate:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenealogyCreateBody'
          example:
            genealogyName: "彭氏家谱"
            firstAncestorName: "彭氏始迁祖"
            requestId: "create-genealogy-20260824-001"
            ownerIsFirstAncestor: false
            surname: "彭"
            ancestralHall: "陇西堂"
            originPlace: "江西吉安"
            regionCode: "360800"
            addressDetail: "江西省吉安市"
            coverOssId: "2060000000000000001"
            intro: "彭氏家谱简介"
            visibility: "1"
            joinMode: "1"
    GenealogyUpdate:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenealogyUpdateBody'
          example:
            genealogyName: "彭氏家谱"
            surname: "彭"
            ancestralHall: "陇西堂"
            originPlace: "江西吉安"
            regionCode: "360800"
            addressDetail: "江西省吉安市"
            coverOssId: "2060000000000000001"
            intro: "更新后的家谱简介"
            visibility: "1"
            joinMode: "1"
    GenealogyUserOrder:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenealogyUserOrderBody'
          example:
            genealogyIds: ["2060000000000000001", "2060000000000000002"]
    GenealogyJoinApply:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenealogyJoinApplyBody'
          example:
            applicantName: "彭小明"
            phone: "13800000000"
            relationDesc: "本族成员"
            applyReason: "申请加入家谱维护"
    GenealogyJoinAudit:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenealogyJoinAuditBody'
          example:
            status: "1"
            auditRemark: "信息核验通过"
    GenealogyMemberUpdate:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenealogyMemberUpdateBody'
          example:
            memberName: "彭小明"
            relationName: "族亲"
            roleType: "member"
            lineagePersonId: 900020001
    GenealogyMemberPermission:
      required: true
      content:
        application/json:
          schema: { $ref: '#/components/schemas/GenealogyMemberPermissionBody' }
    GenealogyOwnerTransfer:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenealogyOwnerTransferBody'
          example:
            targetMemberId: 900010002
    GenerationPoem:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenerationPoemBody'
          example:
            generationNo: 5
            generationText: "忠"
            description: "fifth generation poem"
            sortOrder: 5
            status: "0"
    Article:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ArticleBody'
          example:
            categoryId: 900040001
            articleTitle: "族谱源流"
            articleSummary: "介绍本支源流"
            coverOssId: "2060000000000000001"
            articleContent: "<p>article content</p>"
            authorName: "族谱管理员"
            sortOrder: 1
            status: "0"
    ArticleCategory:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ArticleCategoryBody'
          example:
            categoryName: "姓氏源流"
            categoryDesc: "记录本支姓氏与迁徙源流"
            sortOrder: 10
            status: "0"
    Album:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AlbumBody'
          example:
            albumName: "老照片"
            albumDesc: "family old photos"
            coverOssId: "2060000000000000001"
            sortOrder: 1
            status: "0"
    AlbumPhoto:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AlbumPhotoBody'
          example:
            ossId: "2060000000000000001"
            photoTitle: "老宅合影"
            photoDesc: "old house photo"
            photographer: "彭小明"
            shootTime: "2026-07-09 10:00:00"
            sortOrder: 1
            status: "0"
    Ceremony:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CeremonyBody'
          example:
            ceremonyType: "ancestor"
            ceremonyTitle: "清明祭祖"
            ceremonyDesc: "online ancestor ceremony"
            ceremonyTime: "2026-04-04 09:00:00"
            location: "祠堂"
            locationAddress: "四川省成都市示例路1号"
            longitude: 104.0665410
            latitude: 30.5722690
            coverOssId: "2060000000000000001"
            sortOrder: 1
            status: "0"
    CeremonyInvitees:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CeremonyInviteesBody'
          example:
            inviteeUserIds: [900000001, 900000002]
    CeremonyInvitationResponse:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CeremonyInvitationResponseBody'
          example:
            inviteStatus: "ACCEPTED"
    CeremonyGift:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CeremonyGiftBody'
          example:
            giverName: "彭小明"
            giftAmount: 66.66
            giftMessage: "缅怀先祖"
    GrowthRecord:
      required: true
      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"
    LifeEvent:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LifeEventBody'
          example:
            eventType: EDUCATION
            eventTitle: 进入县立小学
            eventContent: 在县立小学完成启蒙教育
            eventDate: "1936-09-01"
            datePrecision: DAY
            eventPlace: 四川省成都市
            sourceDescription: 家谱手稿
            mediaOssIds: ["2060000000000000001"]
            sortOrder: 1
            status: "0"
    Memo:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MemoBody'
          example:
            memoType: "general"
            memoTitle: "修谱事项"
            memoContent: "contact family members"
            remindTime: "2026-08-01 09:00:00"
            completed: "0"
            mediaOssIds: "2060000000000000001"
            sortOrder: 1
            status: "0"
    RelativeRecord:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RelativeRecordBody'
          example:
            relativeName: "张三"
            relationName: "亲友"
            eventName: "礼尚往来"
            eventTime: "2026-07-16 10:00:00"
            giftAmount: 100.00
            recordContent: "往来记录"
            mediaOssIds: "2060000000000000001"
            sortOrder: 1
            status: "0"
    MeritRecord:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MeritRecordBody'
          example:
            donorName: "彭小明"
            meritType: "donation"
            meritTitle: "修谱捐款"
            meritContent: "support genealogy work"
            mediaOssIds: "2060000000000000001"
            amount: 100.0
            meritTime: "2026-07-09 10:00:00"
            sortOrder: 1
            status: "0"
    Video:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VideoBody'
          example:
            videoTitle: "家族活动记录"
            videoDesc: "2026 年清明祭祖活动"
            coverOssId: "2060000000000000001"
            videoOssId: "2060000000000000002"
            durationSeconds: 180
            sortOrder: 1
            status: "0"
    Feedback:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FeedbackBody'
          example:
            feedbackType: "bug"
            feedbackContent: "upload image failed"
            contactInfo: "13800000000"
    VipOrder:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AppVipOrderBody'
          example:
            packageId: 900060001
            genealogyId: 900001001
            paymentMethod: WECHAT
            requestId: app-vip-order-20260818-001
    VerificationChallenge:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VerificationChallengeBody'
          example:
            tenantId: "000000"
            subject: "13800000000"
    VerificationCheck:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VerificationCheckBody'
          examples:
            tianai_behavior:
              summary: 天爱滑块/旋转/滑动还原/文字点选验证
              value:
                tenantId: "000000"
                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
            system_image:
              summary: 系统图形验证码
              value:
                tenantId: "000000"
                subject: "13800000000"
                challengeId: "CAPTCHA_CHALLENGE_ID"
                providerCode: "ruoyi_image"
                captchaType: "math"
                payload:
                  uuid: "captcha-uuid"
                  code: "6"
  responses:
    ComplianceDocumentContentResult:
      description: 合规文档正文响应
      content:
        application/json:
          schema: { $ref: '#/components/schemas/RComplianceDocumentContent' }
    VoidResult:
      description: 通用成功响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RVoid'
    ObjectResult:
      description: 通用对象响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RObject'
    GenealogyQuotaResult:
      description: 当前业务用户家谱配额响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RGenealogyQuota'
    LongResult:
      description: 长整型数据响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RLong'
    ListResult:
      description: 通用列表响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RList'
    HelpArticleResult:
      description: 帮助文章详情响应
      content: { application/json: { schema: { $ref: '#/components/schemas/RHelpArticle' } } }
    HelpArticleListResult:
      description: 帮助文章列表响应
      content: { application/json: { schema: { $ref: '#/components/schemas/RHelpArticleList' } } }
    VipPurchaseCapabilityResult:
      description: VIP 购买能力响应
      content: { application/json: { schema: { $ref: '#/components/schemas/RVipPurchaseCapability' } } }
    VipPackageListResult:
      description: VIP 套餐列表响应
      content: { application/json: { schema: { $ref: '#/components/schemas/RVipPackageList' } } }
    VipOrderResult:
      description: VIP 订单详情响应
      content: { application/json: { schema: { $ref: '#/components/schemas/RVipOrder' } } }
    VipOrderListResult:
      description: VIP 订单列表响应
      content: { application/json: { schema: { $ref: '#/components/schemas/RVipOrderList' } } }
    PaymentOrderResult:
      description: 支付下单响应
      content: { application/json: { schema: { $ref: '#/components/schemas/RPaymentOrder' } } }
    PaymentTransactionStatusResult:
      description: 支付状态响应
      content: { application/json: { schema: { $ref: '#/components/schemas/RPaymentTransactionStatus' } } }
    GenealogyInvitationResult:
      description: 家谱邀请详情响应
      content: { application/json: { schema: { $ref: '#/components/schemas/RGenealogyInvitation' } } }
    GenealogyInvitationListResult:
      description: 家谱邀请列表响应
      content: { application/json: { schema: { $ref: '#/components/schemas/RGenealogyInvitationList' } } }
    AppPromotionListResult:
      description: 当前有效推广列表
      content:
        application/json:
          schema: { $ref: '#/components/schemas/RAppPromotionList' }
    ContentLifecycleStatusResult:
      description: 内容生命周期状态响应
      content:
        application/json:
          schema: { $ref: '#/components/schemas/RContentLifecycleStatus' }
    AppProfileResult:
      description: AppProfileResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppProfile'
    AppGenealogyResult:
      description: AppGenealogyResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppGenealogy'
    AppGenealogyListResult:
      description: AppGenealogyListResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppGenealogyList'
    GenealogyCompletenessResult:
      description: 家谱资料完整度响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RGenealogyCompleteness'
    AppGenealogyMemberResult:
      description: AppGenealogyMemberResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppGenealogyMember'
    AppGenealogyMemberListResult:
      description: AppGenealogyMemberListResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppGenealogyMemberList'
    GenealogyMemberOptionListResult:
      description: GenealogyMemberOptionListResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RGenealogyMemberOptionList'
    GenealogyMemberPermissionResult:
      description: 家谱管理员权限响应
      content:
        application/json:
          schema: { $ref: '#/components/schemas/RGenealogyMemberPermission' }
    GenealogyMemberPermissionCatalogListResult:
      description: 家谱管理员权限目录响应
      content:
        application/json:
          schema: { $ref: '#/components/schemas/RGenealogyMemberPermissionCatalogList' }
    AppNotificationResult:
      description: AppNotificationResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppNotification'
    AppNotificationListResult:
      description: AppNotificationListResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppNotificationList'
    AppGrowthRecordResult:
      description: AppGrowthRecordResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppGrowthRecord'
    AppGrowthRecordListResult:
      description: AppGrowthRecordListResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppGrowthRecordList'
    AppAlbumResult:
      description: AppAlbumResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppAlbum'
    AppAlbumListResult:
      description: AppAlbumListResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppAlbumList'
    AppAlbumPhotoResult:
      description: AppAlbumPhotoResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppAlbumPhoto'
    AppAlbumPhotoListResult:
      description: AppAlbumPhotoListResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppAlbumPhotoList'
    AppVideoResult:
      description: AppVideoResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppVideo'
    AppVideoListResult:
      description: AppVideoListResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppVideoList'
    AppArticleResult:
      description: AppArticleResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppArticle'
    AppArticleListResult:
      description: AppArticleListResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppArticleList'
    AppArticleCategoryOptionListResult:
      description: 谱文分类选项列表
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppArticleCategoryOptionList'
    AppArticleCategoryResult:
      description: 谱文分类详情
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppArticleCategory'
    AppCeremonyResult:
      description: AppCeremonyResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppCeremony'
    AppCeremonyListResult:
      description: AppCeremonyListResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppCeremonyList'
    AppCeremonyGiftResult:
      description: APP/PC 典礼礼金详情响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppCeremonyGift'
    AppCeremonyGiftListResult:
      description: APP/PC 典礼礼金列表响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppCeremonyGiftList'
    AppRelativeRecordResult:
      description: AppRelativeRecordResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppRelativeRecord'
    AppRelativeRecordListResult:
      description: AppRelativeRecordListResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppRelativeRecordList'
    AppMemoResult:
      description: AppMemoResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppMemo'
    AppMemoListResult:
      description: AppMemoListResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppMemoList'
    AppMeritRecordResult:
      description: AppMeritRecordResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppMeritRecord'
    AppMeritRecordListResult:
      description: AppMeritRecordListResult 专用响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RAppMeritRecordList'
    LifeEventResult:
      description: 人生大事详情响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RLifeEvent'
    LifeEventListResult:
      description: 人生大事列表响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RLifeEventList'
    CeremonyInvitationResult:
      description: 贺礼邀约详情响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RCeremonyInvitation'
    CeremonyInvitationListResult:
      description: 贺礼邀约列表响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RCeremonyInvitationList'
    CeremonyInviteeOptionListResult:
      description: 贺礼受邀候选列表响应
      content:
        application/json:
          schema: { $ref: '#/components/schemas/RCeremonyInviteeOptionList' }
    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'
    LineagePersonDetailResult:
      description: 世系人物受限详情响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RLineagePersonDetail'
    LineagePersonSensitiveProfileResult:
      description: 世系人物敏感健康资料响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RLineagePersonSensitiveProfile'
    LineageRankOptionListResult:
      description: 世系人物排行选项响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RLineageRankOptionList'
    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'
    PageResult:
      description: 通用分页响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PageResult'
    LoginResult:
      description: 登录结果
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RLogin'
    WechatLoginResult:
      description: 微信登录结果
      content:
        application/json:
          schema: { $ref: '#/components/schemas/RWechatLogin' }
    ReferralMeResult:
      description: 当前用户推荐卡
      content:
        application/json:
          schema: { $ref: '#/components/schemas/RReferralMe' }
    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'
    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'
    FamilyFeedResult:
      description: 家族圈动态对象响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RFamilyFeed'
    FamilyFeedListResult:
      description: 家族圈动态列表响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RFamilyFeedList'
    FamilyFeedPageResult:
      description: 家族圈动态分页响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FamilyFeedPageResult'
    NotificationResult:
      description: 消息通知详情响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RNotification'
    ContentRecycleItemPageResult:
      description: 内容回收站分页响应
      content: { application/json: { schema: { $ref: '#/components/schemas/ContentRecycleItemPageResult' } } }
    ContentRecycleItemResult:
      description: 内容回收站单项响应
      content: { application/json: { schema: { $ref: '#/components/schemas/RContentRecycleItem' } } }
  schemas:
    ComplianceDocumentContent:
      type: object
      additionalProperties: false
      properties:
        documentKey: { type: string, enum: [user_agreement, privacy_policy] }
        documentTitle: { type: string }
        versionNo: { type: string }
        documentContent: { type: string }
        contentHash: { type: string }
        effectiveAt: { type: string, format: date-time, nullable: true }
        publishedAt: { type: string, format: date-time }
    RComplianceDocumentContent:
      type: object
      properties:
        code: { type: integer, example: 200 }
        msg: { type: string, example: 操作成功 }
        data: { $ref: '#/components/schemas/ComplianceDocumentContent' }
    EarningWithdrawalBody:
      type: object
      additionalProperties: false
      required: [requestId, amount, payoutQrOssId, payoutAccountName]
      properties:
        requestId: { type: string, maxLength: 64, description: 客户端生成且重试保持不变的幂等请求号 }
        amount: { type: number, format: double, minimum: 0.01, multipleOf: 0.01 }
        payoutQrOssId: { type: integer, format: int64, description: 统一续传上传接口返回的私有 OSS ID }
        payoutAccountName: { type: string, maxLength: 64 }
    EarningSummary:
      type: object
      properties:
        availableAmount: { type: string, format: decimal, description: 人民币金额（元），精确到分 }
        frozenAmount: { type: string, format: decimal, description: 人民币金额（元），精确到分 }
        minimumWithdrawal: { type: string, format: decimal, nullable: true, description: 人民币金额（元），精确到分 }
        rewardRateBps: { type: integer, nullable: true, description: 基点，10000=100% }
        currency: { type: string, enum: [CNY] }
        withdrawalEnabled: { type: boolean }
    EarningLedger:
      type: object
      properties:
        ledgerId: { type: integer, format: int64 }
        entryType: { type: string, enum: [PAYMENT_REWARD, PAYMENT_REFUND_REVERSAL, WITHDRAWAL_FREEZE, WITHDRAWAL_CANCEL, WITHDRAWAL_REJECT, WITHDRAWAL_PAID, WITHDRAWAL_FAILED] }
        businessId: { type: integer, format: int64, nullable: true }
        availableDelta: { type: string, format: decimal, description: 人民币金额变动（元），可为负数 }
        frozenDelta: { type: string, format: decimal, description: 人民币冻结金额变动（元），可为负数 }
        availableAfter: { type: string, format: decimal, description: 变动后人民币可用金额（元） }
        frozenAfter: { type: string, format: decimal, description: 变动后人民币冻结金额（元） }
        currency: { type: string, enum: [CNY] }
        remark: { type: string }
        createTime: { type: string, format: date-time }
    EarningWithdrawal:
      type: object
      properties:
        withdrawalId: { type: integer, format: int64 }
        withdrawalNo: { type: string }
        amount: { type: string, format: decimal, description: 人民币提现金额（元），精确到分 }
        currency: { type: string, enum: [CNY] }
        payoutQrOssId: { type: integer, format: int64 }
        payoutAccountName: { type: string }
        withdrawalStatus: { type: string, enum: [PENDING, APPROVED, PAYING, PAID, REJECTED, FAILED, CANCELLED], x-dict-type: gen_earning_withdrawal_status }
        auditRemark: { type: string, nullable: true }
        payoutReference: { type: string, nullable: true }
        paidAt: { type: string, format: date-time, nullable: true }
        failureReason: { type: string, nullable: true }
        createTime: { type: string, format: date-time }
    REarningSummary:
      allOf:
        - $ref: '#/components/schemas/RVoid'
        - type: object
          properties: { data: { $ref: '#/components/schemas/EarningSummary' } }
    REarningWithdrawal:
      allOf:
        - $ref: '#/components/schemas/RVoid'
        - type: object
          properties: { data: { $ref: '#/components/schemas/EarningWithdrawal' } }
    EarningLedgerPage:
      type: object
      properties:
        code: { type: integer }
        msg: { type: string }
        rows: { type: array, items: { $ref: '#/components/schemas/EarningLedger' } }
        total: { type: integer, format: int64 }
    EarningWithdrawalPage:
      type: object
      properties:
        code: { type: integer }
        msg: { type: string }
        rows: { type: array, items: { $ref: '#/components/schemas/EarningWithdrawal' } }
        total: { type: integer, format: int64 }
    ContentPasswordBody:
      type: object
      additionalProperties: false
      required: [password]
      properties:
        password: { type: string, format: password, minLength: 8, maxLength: 128 }
    ContentPasswordRecoveryCodeBody:
      type: object
      additionalProperties: false
      properties:
        validToken: { type: string, description: 短信风险校验令牌；按租户短信策略要求填写 }
    ContentPasswordRecoveryResetBody:
      type: object
      additionalProperties: false
      required: [smsCode, newPassword]
      properties:
        smsCode: { type: string, description: 一次性短信验证码 }
        newPassword: { type: string, format: password, minLength: 8, maxLength: 128 }
    GenealogyPermanentDeletionCodeBody:
      type: object
      additionalProperties: false
      properties:
        validToken: { type: string, description: 短信风险校验令牌；按租户短信策略要求填写 }
    GenealogyPermanentDeletionBody:
      type: object
      additionalProperties: false
      required: [genealogyName, smsCode]
      properties:
        genealogyName: { type: string, description: 必须与当前家谱名称完全一致 }
        smsCode: { type: string, description: 一次性短信验证码 }
    ContentPasswordRecoveryCapability:
      type: object
      additionalProperties: false
      required: [available]
      properties:
        available: { type: boolean }
        mobileMasked: { type: string, nullable: true, description: 当前实名手机号脱敏值 }
        disabledReason: { type: string, nullable: true, description: 不可找回时的稳定原因 }
    GenealogyPermanentDeletionCapability:
      type: object
      additionalProperties: false
      required: [canDeletePermanently, disabledReasons]
      properties:
        canDeletePermanently: { type: boolean }
        verifiedMobileMasked: { type: string, nullable: true, description: 家谱所有者实名手机号脱敏值 }
        disabledReasons: { type: array, items: { type: string }, description: 资格阻断原因码 }
    GenealogyDeletionTask:
      type: object
      properties:
        taskId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        status: { type: string }
        requestedBy: { type: integer, format: int64 }
        startedAt: { type: string, format: date-time, nullable: true }
        completedAt: { type: string, format: date-time, nullable: true }
        failureReason: { type: string, nullable: true }
        resultSummary: { type: string, nullable: true }
    PersonDocumentBody:
      type: object
      additionalProperties: false
      required: [lineagePersonId, documentType, documentTitle]
      properties:
        lineagePersonId: { type: integer, format: int64 }
        documentType: { type: string, x-dict-type: gen_person_document_type }
        documentTitle: { type: string, maxLength: 100 }
        maskedIdentifier: { type: string, maxLength: 100 }
        description: { type: string, maxLength: 1000 }
        sortOrder: { type: integer, format: int64 }
        status: { type: string, enum: ['0', '1'] }
    PersonDocumentResourceBody:
      type: object
      additionalProperties: false
      required: [ossId, usageType]
      properties:
        ossId: { type: integer, format: int64, description: 统一上传接口返回的 OSS ID }
        usageType: { type: string, enum: [FRONT, BACK, ATTACHMENT] }
        sortOrder: { type: integer, format: int64 }
    PersonDocumentResource:
      type: object
      properties:
        resourceId: { type: integer, format: int64 }
        usageType: { type: string, enum: [FRONT, BACK, ATTACHMENT] }
        sortOrder: { type: integer, format: int64 }
        status: { type: string }
    PersonDocument:
      type: object
      properties:
        documentId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        lineagePersonId: { type: integer, format: int64 }
        lineagePersonName: { type: string }
        documentType: { type: string, x-dict-type: gen_person_document_type }
        documentTypeLabel: { type: string, nullable: true }
        documentTypeOptionState: { type: string, enum: [ACTIVE, DISABLED, UNKNOWN] }
        documentTitle: { type: string }
        maskedIdentifier: { type: string }
        description: { type: string }
        uploaderUserId: { type: integer, format: int64 }
        sortOrder: { type: integer, format: int64 }
        status: { type: string }
        contentProtected: { type: boolean }
        contentUnlocked: { type: boolean }
        canEdit: { type: boolean }
        canDelete: { type: boolean }
        resources: { type: array, items: { $ref: '#/components/schemas/PersonDocumentResource' } }
    ContentAccessGrant:
      type: object
      required: [accessToken, expiresAt]
      properties:
        accessToken: { type: string, description: 仅本次响应返回，不持久化原文 }
        expiresAt: { type: string, format: date-time }
    RPersonDocument:
      type: object
      properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/PersonDocument' } }
    RPersonDocumentList:
      type: object
      properties: { code: { type: integer }, msg: { type: string }, data: { type: array, items: { $ref: '#/components/schemas/PersonDocument' } } }
    RPersonDocumentResource:
      type: object
      properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/PersonDocumentResource' } }
    RContentAccessGrant:
      type: object
      properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/ContentAccessGrant' } }
    RBusinessFileAccess:
      type: object
      properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/BusinessFileAccess' } }
    BusinessDictionaryOption:
      type: object
      required: [code, label, value, sort, default, enabled]
      properties:
        code:
          type: integer
          format: int64
        label:
          type: string
        value:
          type: string
        sort:
          type: integer
        cssClass:
          type: string
          nullable: true
        listClass:
          type: string
          nullable: true
        default:
          type: boolean
        enabled:
          type: boolean
          description: 当前选项是否可用于新建或编辑；选择接口仅返回 true
    RBusinessDictionaryOptions:
      type: object
      required: [code, msg, data]
      properties:
        code:
          type: integer
          example: 200
        msg:
          type: string
          example: 操作成功
        data:
          type: array
          items:
            $ref: '#/components/schemas/BusinessDictionaryOption'
    RBusinessDictionaryError:
      type: object
      required: [code, msg]
      properties:
        code:
          type: integer
        msg:
          type: string
        data:
          nullable: true
    RVoid:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          nullable: true
    GenealogyQuota:
      type: object
      required: [createUsed, createLimit, createRemaining, canCreate, joinUsed, joinLimit, joinRemaining, canJoin]
      properties:
        createUsed: { description: 当前用户已创建的家谱数量, type: integer, format: int64, minimum: 0, example: 1 }
        createLimit: { description: 每用户可创建家谱上限，-1 表示不限，0 表示禁止，正数表示上限, type: integer, format: int64, minimum: -1, example: 3 }
        createRemaining: { description: 还可创建的家谱数量，-1 表示不限, type: integer, format: int64, minimum: -1, example: 2 }
        canCreate: { description: 当前用户是否还能创建家谱, type: boolean, example: true }
        joinUsed: { description: 已加入的家谱总数，包含自己创建的家谱, type: integer, format: int64, minimum: 0, example: 2 }
        joinLimit: { description: 每用户可加入家谱总数上限，-1 表示不限，0 表示禁止，正数表示上限, type: integer, format: int64, minimum: -1, example: 10 }
        joinRemaining: { description: 还可加入的家谱数量，-1 表示不限, type: integer, format: int64, minimum: -1, example: 8 }
        canJoin: { description: 当前用户是否还能加入其他家谱, type: boolean, example: true }
    RGenealogyQuota:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data: { $ref: '#/components/schemas/GenealogyQuota' }
    RObject:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          type: object
          additionalProperties: true
    RLong:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data: { description: 当前业务用户未读通知数量, type: integer, format: int64, example: 3 }
    RList:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          type: array
          items:
            type: object
            additionalProperties: true
    PageResult:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        rows:
          description: 分页数据列表
          type: array
          items:
            type: object
            additionalProperties: true
        total:
          type: integer
          example: 0
    RLogin:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/LoginVo'
    RWechatLogin:
      type: object
      properties:
        code: { type: integer, example: 200 }
        msg: { type: string, example: 操作成功 }
        data: { $ref: '#/components/schemas/WechatLoginVo' }
    RReferralMe:
      type: object
      properties:
        code: { type: integer, example: 200 }
        msg: { type: string, example: 操作成功 }
        data: { $ref: '#/components/schemas/ReferralMeVo' }
    RFileUpload:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: 操作成功
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/FileUploadVo'
    LoginVo:
      type: object
      additionalProperties: false
      required: [access_token]
      properties:
        access_token:
          type: string
    WechatCodeBody:
      type: object
      additionalProperties: false
      required: [code]
      properties:
        code:
          type: string
          description: 微信一次性授权码；不得提交 AppSecret、openId、unionId、userId 或 tenantId
    WechatLoginVo:
      type: object
      required: [status]
      properties:
        status: { type: string, enum: [AUTHENTICATED, ACCOUNT_BINDING_REQUIRED] }
        login:
          nullable: true
          allOf: [{ $ref: '#/components/schemas/LoginVo' }]
    ReferralMeVo:
      type: object
      required: [referralCode, referredUserCount, shareTitle, shareText, shareUrl]
      properties:
        referralCode: { type: string, description: 当前用户稳定推荐码 }
        referredUserCount: { type: integer, format: int64, minimum: 0 }
        shareTitle: { type: string }
        shareText: { type: string }
        shareUrl: { type: string, format: uri, description: 基于租户 HTTPS H5 域名和稳定推荐码生成的分享链接 }
    FileUploadVo:
      type: object
      properties:
        ossId:
          description: OSS文件ID，表单内部使用，用户侧应通过上传组件获取
          type: string
          pattern: '^[1-9][0-9]*$'
        url:
          type: string
        thumbnailUrl:
          type: string
          nullable: true
        fileName:
          description: 原始文件名
          type: string
        originalName:
          type: string
    PasswordRegisterBody:
      type: object
      additionalProperties: false
      required: [grantType, tenantId, phone, password, smsCode]
      properties:
        grantType:
          description: 授权类型，例如password、sms、wechat、apple
          type: string
          enum: [password]
          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
        referralCode:
          description: 可选稳定推荐码，独立于家谱邀请码
          type: string
        smsCode:
          description: 4 位短信验证码
          type: string
          pattern: '^\d{4}$'
          example: "1234"
    PasswordLoginBody:
      description: APP 用户密码登录请求；验证场景由后端按 APP_PASSWORD_LOGIN 路由的当前激活绑定解析，前端不得提交 sceneCode；validToken 是否需要由解析后场景的策略决定。
      type: object
      additionalProperties: false
      required: [grantType, tenantId, phone, password]
      properties:
        grantType:
          description: 授权类型，例如password、sms、wechat、apple
          type: string
          enum: [password]
          example: password
        tenantId:
          description: 租户ID，用于区分不同租户的数据和验证策略
          type: string
          example: "000000"
        phone:
          description: 登录手机号，也是行为验证票据绑定的验证主体。
          type: string
          example: "13800000000"
        password:
          type: string
          description: 32 位 MD5
          example: e10adc3949ba59abbe56e057f20f883e
        validToken:
          description: 验证中心通过后返回的一次性票据；后台验证策略关闭时可为空，开启时必须提交。
          type: string
    SmsLoginBody:
      type: object
      additionalProperties: false
      required: [grantType, tenantId, phone, smsCode]
      properties:
        grantType:
          description: 授权类型，例如password、sms、wechat、apple
          type: string
          enum: [sms]
          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: [grantType, tenantId, phone]
      properties:
        grantType:
          description: 授权类型，例如password、sms、wechat、apple
          type: string
          enum: [sms]
          example: sms
        tenantId:
          description: 租户ID，用于区分不同租户的数据和验证策略
          type: string
          example: "000000"
        phone:
          description: 手机号
          type: string
          example: "13800000000"
        validToken:
          description: 验证中心通过后返回的票据，仅用于发送短信验证码；后台验证策略关闭时可为空，开启时必填。
          type: string
    ProfileUpdateBody:
      type: object
      additionalProperties: false
      properties:
        nickName:
          description: 用户昵称
          type: string
          maxLength: 30
        realName:
          description: 真实姓名
          type: string
          maxLength: 30
        avatar:
          description: 头像文件OSS ID
          type: integer
          format: int64
        sex:
          description: "字典 sys_user_sex：0=男，1=女，2=未知"
          type: string
          enum: ["0", "1", "2"]
          example: "2"
          x-dict-type: sys_user_sex
        birthday:
          description: 生日，格式 yyyy-MM-dd
          type: string
          format: date
        email:
          description: 邮箱
          type: string
          format: email
          maxLength: 100
    PasswordChangeBody:
      type: object
      additionalProperties: false
      required: [oldPassword, newPassword]
      properties:
        oldPassword:
          type: string
          description: 32 位 MD5
        newPassword:
          type: string
          description: 32 位 MD5
    PasswordResetBody:
      type: object
      additionalProperties: false
      required: [grantType, tenantId, phone, smsCode, newPassword]
      properties:
        grantType:
          description: 授权类型
          type: string
          enum: [password]
          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: [phone, smsCode, currentPassword]
      properties:
        phone:
          description: 新手机号
          type: string
        smsCode:
          description: 4 位短信验证码
          type: string
          pattern: '^\d{4}$'
          example: "1234"
        currentPassword:
          description: 当前账户密码的32位MD5；校验成功且新手机号短信验证码有效后才允许换绑
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
    AccountDeactivateBody:
      type: object
      additionalProperties: false
      required: [smsCode]
      properties:
        smsCode:
          description: 4 位短信验证码
          type: string
          pattern: '^\d{4}$'
          example: "1234"
    ResumableInitBody:
      type: object
      additionalProperties: false
      required: [uploadId, fileName, fileMd5, totalSize, totalChunks, chunkSize]
      properties:
        uploadId:
          description: 客户端生成并在整个上传过程保持不变的上传任务ID
          type: string
        fileName:
          description: 原始文件名
          type: string
        fileMd5:
          description: 完整文件MD5，用于秒传和完整性校验
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        totalSize:
          description: 完整文件大小，单位字节
          type: integer
          format: int64
          minimum: 1
        totalChunks:
          description: 总分片数
          type: integer
          minimum: 1
        chunkSize:
          description: 单个分片大小，单位字节；除最后一片外每片必须严格等于该值
          type: integer
          format: int64
          minimum: 1
          example: 4194304
        contentType:
          description: 文件MIME类型，例如 image/jpeg、video/mp4
          type: string
    ResumableCompleteBody:
      type: object
      additionalProperties: false
      required: [uploadId, fileName, fileMd5, totalSize, totalChunks]
      properties:
        uploadId:
          description: 分片上传任务ID
          type: string
        fileName:
          description: 原始文件名，必须与初始化请求一致
          type: string
        fileMd5:
          description: 完整文件MD5，用于秒传和完整性校验
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        totalSize:
          description: 完整文件大小，单位字节
          type: integer
          format: int64
          minimum: 1
        totalChunks:
          description: 总分片数，必须与初始化请求一致
          type: integer
          minimum: 1
    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: "字典 sys_normal_disable：0=正常，1=停用"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: sys_normal_disable
    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
    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'
    RGenerationPoem:
      type: object
      properties:
        code:
          description: 响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
        data:
          $ref: '#/components/schemas/GenerationPoemView'
    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'
    GenerationPoemBatchBody:
      type: object
      required: [poemText]
      properties:
        poemText:
          description: 字辈文本。无分隔符时按单个字拆分；可用空格、逗号、分号、顿号、斜杠或竖线分隔多个字辈。单个字辈最多50个字符，一次最多500个世代。
          type: string
          maxLength: 26000
          example: "德承家亦\n忠厚传芳"
        disableMissing:
          description: 保存时是否停用未出现在新文本中的后续世代；不会删除历史记录。
          type: boolean
          example: false
    BusinessFileAccess:
      type: object
      description: 已完成业务资源授权校验的临时文件访问对象
      additionalProperties: false
      properties:
        fileId: { description: 文件业务ID, type: integer, format: int64 }
        ossId: { description: OSS对象ID, type: integer, format: int64 }
        fileName: { description: 文件名, type: string }
        mediaType: { description: 媒体类型, type: string }
        fileSize: { description: 文件大小（字节）, type: integer, format: int64 }
        accessUrl: { description: 有时效的授权访问地址, type: string }
        expiresAt: { description: 访问地址过期时间, type: string, format: date-time }
    GenealogyMemberCapabilities:
      type: object
      additionalProperties: false
      properties:
        canEdit: { description: 是否可编辑成员, type: boolean }
        canRemove: { description: 是否可移除成员, type: boolean }
        canLeave: { description: 是否可退出家谱, type: boolean }
        canTransferOwner: { description: 是否可转让家主, type: boolean }
    GenealogyMemberPermissionBody:
      type: object
      additionalProperties: false
      required: [permissionCodes]
      properties:
        permissionCodes:
          type: array
          uniqueItems: true
          items:
            type: string
            enum: [LINEAGE_MANAGE, SENSITIVE_PROFILE_MANAGE, MEMBER_MANAGE, INVITATION_MANAGE, CONTENT_MANAGE, RECYCLE_BIN_MANAGE]
        reason: { type: string }
    GenealogyMemberPermission:
      type: object
      additionalProperties: false
      required: [genealogyId, memberId, permissionCodes]
      properties:
        genealogyId: { type: integer, format: int64 }
        memberId: { type: integer, format: int64 }
        permissionCodes:
          type: array
          uniqueItems: true
          items:
            type: string
            enum: [LINEAGE_MANAGE, SENSITIVE_PROFILE_MANAGE, MEMBER_MANAGE, INVITATION_MANAGE, CONTENT_MANAGE, RECYCLE_BIN_MANAGE]
    RGenealogyMemberPermission:
      type: object
      properties:
        code: { type: integer, format: int32 }
        msg: { type: string }
        data: { $ref: '#/components/schemas/GenealogyMemberPermission' }
    GenealogyMemberPermissionCatalog:
      type: object
      additionalProperties: false
      required: [code, name, groupCode, groupName, description, sensitive, enabled]
      properties:
        code: { type: string, enum: [LINEAGE_MANAGE, SENSITIVE_PROFILE_MANAGE, MEMBER_MANAGE, INVITATION_MANAGE, CONTENT_MANAGE, RECYCLE_BIN_MANAGE] }
        name: { type: string }
        groupCode: { type: string, enum: [GENEALOGY, CONTENT] }
        groupName: { type: string }
        description: { type: string }
        sensitive: { type: boolean }
        enabled: { type: boolean }
        disabledReason: { type: string, nullable: true }
    RGenealogyMemberPermissionCatalogList:
      type: object
      properties:
        code: { type: integer, format: int32 }
        msg: { type: string }
        data:
          type: array
          items: { $ref: '#/components/schemas/GenealogyMemberPermissionCatalog' }
    AppGenealogyMember:
      type: object
      additionalProperties: false
      properties:
        memberId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        genealogyNo: { type: string }
        genealogyName: { type: string }
        firstAncestorName: { type: string, nullable: true, description: 建谱时登记的始迁祖姓名 }
        rootPersonId: { type: integer, format: int64, nullable: true, description: 始迁祖对应的世系人物ID }
        surname: { type: string }
        appUserId: { type: integer, format: int64 }
        appUserNickName: { type: string }
        lineagePersonId: { type: integer, format: int64, nullable: true }
        lineagePersonNo: { type: string }
        lineagePersonName: { type: string }
        memberName: { type: string }
        roleType: { type: string }
        relationName: { type: string }
        joinSource: { type: string }
        inviterUserId: { type: integer, format: int64, nullable: true }
        inviterNickName: { type: string }
        joinTime: { type: string, format: date-time }
        status: { type: string }
        capabilities: { $ref: '#/components/schemas/GenealogyMemberCapabilities' }
    GenealogyMemberOption:
      type: object
      additionalProperties: false
      properties:
        memberId: { type: integer, format: int64 }
        appUserId: { type: integer, format: int64 }
        memberName: { type: string }
        relationName: { type: string }
        roleType: { type: string }
        lineagePersonId: { type: integer, format: int64, nullable: true }
        eligible: { type: boolean }
        disabledReason: { type: string, nullable: true }
        capabilities: { $ref: '#/components/schemas/GenealogyMemberCapabilities' }
    AppNotification:
      type: object
      additionalProperties: false
      properties:
        notificationId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64, nullable: true }
        genealogyNo: { type: string }
        genealogyName: { type: string }
        senderUserId: { type: integer, format: int64, nullable: true }
        senderNickName: { type: string }
        noticeType: { type: string, enum: [join_apply, memo_reminder, family_feed, CEREMONY_INVITE] }
        noticeTypeLabel: { type: string, nullable: true, description: 通知类型中文标签 }
        noticeTitle: { type: string }
        noticeContent: { type: string }
        bizType: { type: string }
        bizId: { type: integer, format: int64, nullable: true }
        bizSummary: { type: string }
        publishTime: { type: string, format: date-time }
        readStatus: { description: "字典 gen_notification_read_status：0=未读，1=已读", type: string, enum: ["0", "1"], example: "0", x-dict-type: gen_notification_read_status }
        readTime: { type: string, format: date-time, nullable: true }
        status: { description: "字典 sys_normal_disable：0=正常，1=停用", type: string, enum: ["0", "1"], example: "0", x-dict-type: sys_normal_disable }
        remark: { type: string }
    AppProfile:
      type: object
      additionalProperties: false
      properties:
        userId: { type: integer, format: int64 }
        tenantId: { type: string }
        userNo: { type: string }
        phone: { description: 当前登录用户本人的手机号, type: string }
        nickName: { type: string }
        realName: { type: string }
        avatarFile: { $ref: '#/components/schemas/BusinessFileAccess' }
        sex: { type: string }
        birthday: { type: string, format: date-time, nullable: true }
        email: { type: string }
        registerSource: { type: string }
        loginIp: { type: string }
        loginDate: { type: string, format: date-time, nullable: true }
        status: { type: string }
        clientKey: { type: string }
        deviceType: { type: string }
    AppGenealogy:
      type: object
      additionalProperties: false
      properties:
        genealogyId: { type: integer, format: int64 }
        genealogyNo: { type: string }
        genealogyName: { type: string }
        firstAncestorName: { type: string, nullable: true, description: 建谱时登记的始迁祖姓名 }
        rootPersonId: { type: integer, format: int64, nullable: true, description: 始迁祖对应的世系人物ID }
        surname: { type: string }
        ancestralHall: { type: string }
        originPlace: { type: string }
        regionCode: { type: string }
        regionName: { type: string }
        regionFullName: { type: string }
        addressDetail: { type: string }
        coverFile: { $ref: '#/components/schemas/BusinessFileAccess' }
        intro: { type: string }
        ownerUserId: { type: integer, format: int64 }
        visibility: { type: string }
        joinMode: { type: string }
        memberCount: { type: integer, format: int64 }
        personCount: { type: integer, format: int64 }
        status: { type: string }
        roleType: { type: string }
        canManage: { type: boolean }
        canEditContent: { type: boolean }
        lifecycleStatus: { type: string, enum: [normal, archived, delete_pending] }
        archivedAt: { type: string, format: date-time, nullable: true }
        archivedBy: { type: string, pattern: '^[1-9][0-9]*$', nullable: true }
        canArchive: { type: boolean }
        canRestore: { type: boolean }
        canDeletePermanently: { type: boolean }
        deletePermanentlyDisabledReasons: { type: array, items: { type: string } }
        verifiedMobileMasked: { type: string, nullable: true }
        memberStatus: { type: string }
        createTime: { type: string, format: date-time, nullable: true, readOnly: true, description: 家谱记录的真实创建时间；不同成员读取同一家谱时一致 }
        joinTime: { type: string, format: date-time, nullable: true }
    AppGrowthRecord:
      type: object
      additionalProperties: false
      properties:
        canEdit: { type: boolean, description: 当前用户是否可编辑该资源 }
        canDelete: { type: boolean, description: 当前用户是否可删除该资源 }
        contentProtected: { type: boolean, description: 是否启用内容密码保护 }
        contentUnlocked: { type: boolean, description: 当前请求是否已通过短时令牌解锁 }
        canManageProtection: { type: boolean, description: 当前用户是否可设置或关闭内容密码 }
        recordId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        genealogyNo: { type: string }
        genealogyName: { type: string }
        surname: { type: string }
        appUserId: { type: integer, format: int64 }
        appUserNickName: { type: string }
        lineagePersonId: { type: integer, format: int64, nullable: true }
        lineagePersonNo: { type: string }
        lineagePersonName: { type: string }
        recordType: { type: string, description: 字典 gen_growth_record_type, x-dict-type: gen_growth_record_type }
        recordTypeLabel: { type: string, nullable: true }
        recordTypeOptionState: { type: string, enum: [ACTIVE, DISABLED, UNKNOWN] }
        recordTitle: { type: string }
        recordContent: { type: string }
        recordDate: { type: string, format: date-time, nullable: true }
        remindTime: { type: string, format: date-time, nullable: true }
        mediaFiles:
          type: array
          items: { $ref: '#/components/schemas/BusinessFileAccess' }
        sortOrder: { type: integer, format: int64 }
        status: { type: string }
        remark: { type: string }
    AppAlbum:
      type: object
      additionalProperties: false
      properties:
        canEdit: { type: boolean, description: 当前用户是否可编辑该资源 }
        canDelete: { type: boolean, description: 当前用户是否可删除该资源 }
        albumId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        genealogyNo: { type: string }
        genealogyName: { type: string }
        surname: { type: string }
        albumName: { type: string }
        albumDesc: { type: string }
        coverFile: { $ref: '#/components/schemas/BusinessFileAccess' }
        photoCount: { type: integer, format: int64 }
        sortOrder: { type: integer, format: int64 }
        status: { type: string }
        remark: { type: string }
    AppAlbumPhoto:
      type: object
      additionalProperties: false
      properties:
        canEdit: { type: boolean, description: 当前用户是否可编辑该资源 }
        canDelete: { type: boolean, description: 当前用户是否可删除该资源 }
        photoId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        genealogyNo: { type: string }
        genealogyName: { type: string }
        surname: { type: string }
        albumId: { type: integer, format: int64 }
        albumName: { type: string }
        photoFile: { $ref: '#/components/schemas/BusinessFileAccess' }
        photoTitle: { type: string }
        photoDesc: { type: string }
        photographer: { type: string }
        shootTime: { type: string, format: date-time, nullable: true }
        sortOrder: { type: integer, format: int64 }
        status: { type: string }
        remark: { type: string }
    AppVideo:
      type: object
      additionalProperties: false
      properties:
        videoId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        genealogyNo: { type: string }
        genealogyName: { type: string }
        surname: { type: string }
        videoTitle: { type: string }
        videoDesc: { type: string }
        coverFile: { $ref: '#/components/schemas/BusinessFileAccess' }
        videoFile: { $ref: '#/components/schemas/BusinessFileAccess' }
        durationSeconds: { type: integer, format: int64 }
        publisherUserId: { type: integer, format: int64 }
        publisherNickName: { type: string }
        publishTime: { type: string, format: date-time, nullable: true }
        viewCount: { type: integer, format: int64 }
        likeCount: { type: integer, format: int64 }
        commentCount: { type: integer, format: int64 }
        likedByCurrentUser: { type: boolean }
        sortOrder: { type: integer, format: int64 }
        status: { type: string }
        remark: { type: string }
        canEdit: { description: 当前用户是否可编辑, type: boolean }
        canDelete: { description: 当前用户是否可删除, type: boolean }
    AppArticleCategoryOption:
      type: object
      additionalProperties: false
      properties:
        categoryId: { type: integer, format: int64 }
        categoryName: { type: string }
        enabled: { type: boolean }
        sortOrder: { type: integer, format: int64 }
    AppArticleCategory:
      type: object
      additionalProperties: false
      required: [categoryId, genealogyId, categoryName, sortOrder, status]
      properties:
        categoryId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        genealogyNo: { type: string }
        genealogyName: { type: string }
        surname: { type: string }
        categoryCode: { type: string }
        categoryName: { type: string }
        categoryDesc: { type: string }
        sortOrder: { type: integer, format: int64 }
        status: { type: string }
        remark: { type: string }
        createTime: { type: string, format: date-time, nullable: true }
    AppArticle:
      type: object
      additionalProperties: false
      properties:
        canEdit: { type: boolean, description: 当前用户是否可编辑该资源 }
        canDelete: { type: boolean, description: 当前用户是否可删除该资源 }
        contentProtected: { type: boolean, description: 是否启用内容密码保护 }
        contentUnlocked: { type: boolean, description: 当前请求是否已通过短时令牌解锁 }
        canManageProtection: { type: boolean, description: 当前用户是否可设置或关闭内容密码 }
        articleId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        genealogyNo: { type: string }
        genealogyName: { type: string }
        surname: { type: string }
        categoryId: { type: integer, format: int64 }
        categoryName: { type: string }
        categoryCode: { type: string }
        articleTitle: { type: string }
        articleSummary: { type: string }
        coverFile: { $ref: '#/components/schemas/BusinessFileAccess' }
        mediaFiles: { type: array, description: 有序正文图片；未解锁时为空数组；不含永久公开地址, items: { $ref: '#/components/schemas/BusinessFileAccess' } }
        articleContent: { type: string, nullable: true, description: 未解锁时为 null }
        authorName: { type: string }
        publishTime: { type: string, format: date-time, nullable: true }
        viewCount: { type: integer, format: int64 }
        sortOrder: { type: integer, format: int64 }
        status: { type: string }
        remark: { type: string }
    AppCeremony:
      type: object
      additionalProperties: false
      properties:
        canEdit: { type: boolean, description: 当前用户是否可编辑该资源 }
        canDelete: { type: boolean, description: 当前用户是否可删除该资源 }
        ceremonyId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        genealogyNo: { type: string }
        genealogyName: { type: string }
        surname: { type: string }
        sponsorUserId: { type: integer, format: int64 }
        sponsorNickName: { type: string }
        ceremonyType: { type: string, description: 字典 gen_ceremony_type；返回当前租户稳定编码，中文名称由字典标签提供, x-dict-type: gen_ceremony_type }
        ceremonyTypeLabel: { type: string, nullable: true }
        ceremonyTypeOptionState: { type: string, enum: [ACTIVE, DISABLED, UNKNOWN] }
        ceremonyTitle: { type: string }
        ceremonyDesc: { type: string }
        ceremonyTime: { type: string, format: date-time, nullable: true }
        location: { type: string }
        locationAddress: { type: string }
        longitude: { type: number }
        latitude: { type: number }
        coverFile: { $ref: '#/components/schemas/BusinessFileAccess' }
        giftCount: { type: integer, format: int64 }
        giftAmount: { description: 人民币累计金额（元），0 至 9999999999.99, type: string, format: decimal }
        sortOrder: { type: integer, format: int64 }
        status: { type: string }
        remark: { type: string }
        createTime: { type: string, format: date-time, nullable: true }
    AppCeremonyGift:
      type: object
      additionalProperties: false
      properties:
        canEdit: { type: boolean, description: 当前用户是否可编辑该资源 }
        canDelete: { type: boolean, description: 当前用户是否可删除该资源 }
        giftId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        genealogyNo: { type: string }
        genealogyName: { type: string }
        surname: { type: string }
        ceremonyId: { type: integer, format: int64 }
        ceremonyTitle: { type: string }
        giverUserId: { type: integer, format: int64 }
        giverNickName: { type: string }
        giverName: { type: string }
        giftAmount: { description: 人民币金额（元），0 至 9999999999.99, type: string, format: decimal }
        giftMessage: { type: string }
        giftTime: { type: string, format: date-time, nullable: true }
        status: { type: string }
        remark: { type: string }
    AppLifeEvent:
      type: object
      additionalProperties: false
      properties:
        eventId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        lineagePersonId: { type: integer, format: int64 }
        creatorUserId: { type: integer, format: int64 }
        eventType: { type: string }
        eventTitle: { type: string }
        eventContent: { type: string }
        eventDate: { type: string, format: date }
        datePrecision: { type: string }
        eventPlace: { type: string }
        sourceDescription: { type: string }
        mediaFiles:
          type: array
          items: { $ref: '#/components/schemas/BusinessFileAccess' }
        sortOrder: { type: integer, format: int64 }
        status: { type: string }
        remark: { type: string }
        canEdit: { type: boolean, description: 当前用户是否可编辑 }
        canDelete: { type: boolean, description: 当前用户是否可删除 }
    AppRelativeRecord:
      type: object
      additionalProperties: false
      properties:
        canEdit: { type: boolean, description: 当前用户是否可编辑该资源 }
        canDelete: { type: boolean, description: 当前用户是否可删除该资源 }
        relativeId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        genealogyNo: { type: string }
        genealogyName: { type: string }
        surname: { type: string }
        appUserId: { type: integer, format: int64 }
        appUserNickName: { type: string }
        relativeName: { type: string }
        relationName: { type: string }
        eventName: { type: string }
        eventTime: { type: string, format: date-time, nullable: true }
        giftAmount: { description: 人民币金额（元），0 至 9999999999.99, type: string, format: decimal }
        recordContent: { type: string }
        mediaFiles:
          type: array
          items: { $ref: '#/components/schemas/BusinessFileAccess' }
        sortOrder: { type: integer, format: int64 }
        status: { type: string }
        remark: { type: string }
        createTime: { type: string, format: date-time, nullable: true }
    AppMemo:
      type: object
      additionalProperties: false
      properties:
        canEdit: { type: boolean, description: 当前用户是否可编辑该资源 }
        canDelete: { type: boolean, description: 当前用户是否可删除该资源 }
        memoId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        genealogyNo: { type: string }
        genealogyName: { type: string }
        surname: { type: string }
        appUserId: { type: integer, format: int64 }
        appUserNickName: { type: string }
        memoType: { type: string, enum: [general, benefactor], description: general=普通备忘，benefactor=家族恩人 }
        memoTitle: { type: string }
        memoContent: { type: string }
        remindTime: { type: string, format: date-time, nullable: true }
        completed: { type: string }
        mediaFiles:
          type: array
          items: { $ref: '#/components/schemas/BusinessFileAccess' }
        sortOrder: { type: integer, format: int64 }
        status: { type: string }
        remark: { type: string }
        createTime: { type: string, format: date-time, nullable: true }
    AppMeritRecord:
      type: object
      additionalProperties: false
      properties:
        canEdit: { type: boolean, description: 当前用户是否可编辑该资源 }
        canDelete: { type: boolean, description: 当前用户是否可删除该资源 }
        meritId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        genealogyNo: { type: string }
        genealogyName: { type: string }
        surname: { type: string }
        appUserId: { type: integer, format: int64 }
        appUserNickName: { type: string }
        donorName: { type: string }
        meritType: { type: string }
        meritTypeLabel: { type: string, nullable: true }
        meritTypeOptionState: { type: string, enum: [ACTIVE, DISABLED, UNKNOWN] }
        meritTitle: { type: string }
        meritContent: { type: string }
        mediaFiles:
          type: array
          items: { $ref: '#/components/schemas/BusinessFileAccess' }
        amount: { description: 人民币金额（元），0 至 9999999999.99, type: string, format: decimal }
        meritTime: { type: string, format: date-time }
        sortOrder: { type: integer, format: int64 }
        status: { type: string }
        remark: { type: string }
        createTime: { type: string, format: date-time, nullable: true }
    LineageRelationRemoveBody:
      type: object
      additionalProperties: false
      required: [relativePersonId, relationType]
      properties:
        relativePersonId: { type: integer, format: int64 }
        relationType: { type: string, enum: [spouse, father, mother, child, sibling] }
    AppPromotionVo:
      type: object
      additionalProperties: false
      properties:
        promotionId: { type: integer, format: int64 }
        promotionKey: { type: string }
        promotionTitle: { type: string }
        promotionDesc: { type: string }
        coverFile:
          allOf: [{ $ref: '#/components/schemas/BusinessFileAccess' }]
          nullable: true
        targetUrl: { type: string }
        platform: { type: string, enum: [app, pc, wechat, all] }
        placement: { type: string, enum: [home_banner, home_bottom, message_bottom, profile_bottom] }
        startAt: { type: string, format: date-time, nullable: true }
        endAt: { type: string, format: date-time, nullable: true }
        sortOrder: { type: integer, format: int64 }
        status: { type: string }
        remark: { type: string }
    ContentLifecycleStatusVo:
      type: object
      additionalProperties: false
      required: [genealogyId, resourceType, resourceId, status, canRestore]
      properties:
        genealogyId: { type: integer, format: int64 }
        resourceType: { type: string, enum: [family_feed, video, growth_record, relative_record, memo, merit_record, article, album, album_photo, ceremony] }
        resourceId: { type: integer, format: int64 }
        status: { type: string, enum: ['0', '1'] }
        canRestore: { type: boolean }
    RAppPromotionList:
      type: object
      properties:
        code: { type: integer, example: 200 }
        msg: { type: string }
        data: { type: array, items: { $ref: '#/components/schemas/AppPromotionVo' } }
    RContentLifecycleStatus:
      type: object
      properties:
        code: { type: integer, example: 200 }
        msg: { type: string }
        data: { $ref: '#/components/schemas/ContentLifecycleStatusVo' }

    RAppProfile:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppProfile'
    RAppGenealogy:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppGenealogy'
    RAppGenealogyList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/AppGenealogy' }
    GenealogyUserOrderBody:
      type: object
      additionalProperties: false
      required: [genealogyIds]
      properties:
        genealogyIds:
          type: array
          uniqueItems: true
          items: { type: string, pattern: '^[1-9][0-9]*$' }
    GenealogyCompletenessItem:
      type: object
      additionalProperties: false
      required: [code, displayText, targetPage]
      properties:
        code: { type: string, example: genealogy_name }
        displayText: { type: string, example: 请完善家谱名称 }
        targetPage: { type: string, enum: [genealogy-profile], example: genealogy-profile }
    GenealogyCompleteness:
      type: object
      additionalProperties: false
      required: [ruleVersion, totalCount, completedCount, completionRate, missingItems]
      properties:
        ruleVersion: { type: string, example: v1 }
        totalCount: { type: integer, example: 10 }
        completedCount: { type: integer, example: 8 }
        completionRate: { type: integer, minimum: 0, maximum: 100, example: 80 }
        missingItems:
          type: array
          items: { $ref: '#/components/schemas/GenealogyCompletenessItem' }
    RGenealogyCompleteness:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data: { $ref: '#/components/schemas/GenealogyCompleteness' }
    RAppGenealogyMember:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppGenealogyMember'
    RAppGenealogyMemberList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/AppGenealogyMember' }
    RGenealogyMemberOptionList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/GenealogyMemberOption' }
    RAppNotification:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppNotification'
    RAppNotificationList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/AppNotification' }
    RAppGrowthRecord:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppGrowthRecord'
    RAppGrowthRecordList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/AppGrowthRecord' }
    RAppAlbum:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppAlbum'
    RAppAlbumList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/AppAlbum' }
    RAppAlbumPhoto:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppAlbumPhoto'
    RAppAlbumPhotoList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/AppAlbumPhoto' }
    RAppVideo:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppVideo'
    RAppVideoList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/AppVideo' }
    RAppArticle:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppArticle'
    RAppArticleList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/AppArticle' }
    RAppArticleCategoryOptionList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/AppArticleCategoryOption' }
    RAppArticleCategory:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppArticleCategory'
    RAppCeremony:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppCeremony'
    RAppCeremonyList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/AppCeremony' }
    RAppCeremonyGift:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppCeremonyGift'
    RAppCeremonyGiftList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/AppCeremonyGift' }
    RAppRelativeRecord:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppRelativeRecord'
    RAppRelativeRecordList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/AppRelativeRecord' }
    RAppMemo:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppMemo'
    RAppMemoList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/AppMemo' }
    RAppMeritRecord:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/AppMeritRecord'
    RAppMeritRecordList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/AppMeritRecord' }
    LineagePersonSortOrderBody:
      type: object
      additionalProperties: false
      required: [sortOrder]
      properties:
        sortOrder:
          description: 人物在当前家谱中的排行值
          type: integer
          format: int64
          example: 100
    LineagePersonBody:
      type: object
      additionalProperties: false
      required: [bindingMode, name]
      properties:
        bindingMode:
          description: "账号绑定方式：NONE=不绑定账号；SELF=绑定当前登录业务用户；SPECIFIED=由有管理权限的操作者指定 appUserId"
          type: string
          enum: [NONE, SELF, SPECIFIED]
          example: NONE
        appUserId:
          description: 仅 bindingMode=SPECIFIED 时必填；NONE/SELF 时必须不传。指定用户必须属于当前租户、状态正常，且未绑定当前家谱的其他有效世系人物
          type: integer
          format: int64
        personNo:
          description: 人物编号；不传时由服务端生成
          type: string
        name:
          description: 姓名
          type: string
        aliasName:
          description: 别名或曾用名
          type: string
        courtesyName:
          description: 字
          type: string
        zodiacCode:
          description: 生肖稳定编码，从租户业务字典 gen_zodiac 选择
          type: string
          x-dict-type: gen_zodiac
        educationCode:
          description: 学历分类稳定编码，从业务字典 gen_education_type 选择
          type: string
          x-dict-type: gen_education_type
        deathExpressionCode:
          description: 过世类型稳定编码，从业务字典 gen_death_expression 选择
          type: string
          x-dict-type: gen_death_expression
        relationVariantCode:
          description: 添加父母或配偶关系时使用的显示修饰稳定编码；父母取 gen_parent_relationship_variant，配偶取 gen_spouse_relationship_variant
          type: string
        sex:
          description: "字典 sys_user_sex：0=男，1=女，2=未知"
          type: string
          enum: ["0", "1", "2"]
          example: "0"
          x-dict-type: sys_user_sex
        generation:
          description: 世代序号
          type: integer
          format: int64
        generationName:
          description: 字辈或辈分
          type: string
        rankId:
          description: 世系排行配置ID；从当前家谱的排行选项接口选择，留空表示不设置排行
          type: integer
          format: int64
          nullable: true
        fatherId:
          description: 父亲人物ID，必须属于当前家谱
          type: integer
          format: int64
        motherId:
          description: 母亲人物ID，必须属于当前家谱
          type: integer
          format: int64
        avatarOssId:
          description: 头像文件OSS ID；用户界面应通过统一上传组件获得，不允许手工录入
          type: string
          pattern: '^[1-9][0-9]*$'
          nullable: true
        birthDate:
          type: string
          format: date-time
          nullable: true
        birthLunar:
          description: "字典 gen_number_yes_no：0=否，1=是"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: gen_number_yes_no
        birthPlace:
          description: 出生地
          type: string
        currentAddress:
          description: 现居住地；仅人物详情按权限投影，列表和树不返回
          type: string
        mobile:
          description: 联系电话；详情默认脱敏，有权用户返回完整值
          type: string
        email:
          description: 邮箱；服务端保存为去首尾空白的小写值
          type: string
          format: email
        occupation:
          description: 职业
          type: string
        deathDate:
          type: string
          format: date-time
          nullable: true
        deathLunar:
          description: "字典 gen_number_yes_no：0=否，1=是"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: gen_number_yes_no
        deathPlace:
          description: 逝世地
          type: string
        burialPlace:
          description: 安葬地
          type: string
        deathAge:
          description: 享年，允许 0
          type: integer
          format: int32
          minimum: 0
        burialDate:
          description: 安葬日期
          type: string
          format: date
        personStatus:
          description: "字典 gen_lineage_person_status：0=健在，1=已故，2=未知"
          type: string
          enum: ["0", "1", "2"]
          example: "0"
          x-dict-type: gen_lineage_person_status
        biography:
          description: 人物简介
          type: string
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        remark:
          description: 备注
          type: string
        relationName:
          description: 通过添加配偶快捷接口提交时使用的关系显示名称
          type: string
    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 }
        courtesyName: { description: 字, type: string }
        zodiacCode: { description: 生肖稳定编码, type: string, x-dict-type: gen_zodiac }
        zodiacLabel: { description: 生肖显示名称, type: string, nullable: true }
        zodiacOptionState: { description: 生肖历史值状态, type: string, enum: [ACTIVE, DISABLED, UNKNOWN], nullable: true }
        educationCode: { description: 学历分类稳定编码, type: string, x-dict-type: gen_education_type }
        educationLabel: { description: 学历分类显示名称, type: string, nullable: true }
        educationOptionState: { description: 学历历史值状态, type: string, enum: [ACTIVE, DISABLED, UNKNOWN], nullable: true }
        deathExpressionCode: { description: 过世类型稳定编码, type: string, x-dict-type: gen_death_expression }
        deathExpressionLabel: { description: 过世类型显示名称, type: string, nullable: true }
        deathExpressionOptionState: { description: 过世类型历史值状态, type: string, enum: [ACTIVE, DISABLED, UNKNOWN], nullable: true }
        sex: { description: "字典 sys_user_sex：0=男，1=女，2=未知", type: string, enum: ["0", "1", "2"], example: "2", x-dict-type: sys_user_sex }
        generation: { description: 世代序号, type: integer, format: int64 }
        generationName: { description: 字辈或辈分, type: string }
        rankId: { description: 世系排行配置ID, type: integer, format: int64, nullable: true }
        rankName: { description: 世系排行名称，例如始祖、长子、次女, type: string, nullable: true }
        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 }
        avatarFile: { $ref: '#/components/schemas/BusinessFileAccess' }
        birthDate: { description: 出生日期, type: string, format: date-time, nullable: true }
        birthLunar: { description: "字典 gen_number_yes_no：0=否，1=是", type: string, enum: ["0", "1"], example: "0", x-dict-type: gen_number_yes_no }
        birthPlace: { description: 出生地, type: string }
        deathDate: { description: 逝世日期, type: string, format: date-time, nullable: true }
        deathLunar: { description: "字典 gen_number_yes_no：0=否，1=是", type: string, enum: ["0", "1"], example: "0", x-dict-type: gen_number_yes_no }
        deathPlace: { description: 逝世地, type: string }
        burialPlace: { description: 安葬地, type: string }
        occupation: { description: 职业, type: string }
        deathAge: { description: 享年，允许 0, type: integer, format: int32, minimum: 0, nullable: true }
        burialDate: { description: 安葬日期, type: string, format: date, nullable: true }
        personStatus: { description: "字典 gen_lineage_person_status：0=健在，1=已故，2=未知", type: string, enum: ["0", "1", "2"], example: "0", x-dict-type: gen_lineage_person_status }
        biography: { description: 人物简介, type: string }
        sortOrder: { description: 排序值, type: integer, format: int64 }
        status: { description: "字典 sys_normal_disable：0=正常，1=停用", type: string, enum: ["0", "1"], example: "0", x-dict-type: sys_normal_disable }
        canDisable: { type: boolean, description: 当前用户是否可停用该人物 }
        disabledReason: { type: string, nullable: true, description: 不可停用时的稳定原因 }
        canCreateDocument: { type: boolean, description: 当前用户是否可为该人物创建证件档案 }
        canManageDocuments: { type: boolean, description: 当前用户是否可管理该人物证件档案 }
        remark: { description: 备注, type: string }
    LineagePersonDetailView:
      allOf:
        - $ref: '#/components/schemas/LineagePersonView'
        - type: object
          properties:
            currentAddress: { description: 有权查看时返回完整现居住地，否则为空, type: string, nullable: true }
            mobile: { description: 默认脱敏；人物本人、谱主或具备成员管理权限的管理员返回完整号码, type: string, nullable: true }
            email: { description: 有权查看时返回完整邮箱，否则为空, type: string, format: email, nullable: true }
            canManageSensitiveMedicalHistory: { description: 当前用户是否可管理敏感健康资料, type: boolean }
    LineagePersonSensitiveProfileBody:
      type: object
      additionalProperties: false
      required: [hereditaryMedicalHistory]
      properties:
        hereditaryMedicalHistory: { description: 遗传病史正文，仅写入独立加密表, type: string }
    LineagePersonSensitiveProfileView:
      type: object
      properties:
        personId: { description: 世系人物ID, type: integer, format: int64 }
        hereditaryMedicalHistory: { description: 遗传病史正文，仅授权用户可读, type: string, nullable: true }
        present: { description: 当前人物是否存在敏感档案, type: boolean }
        updatedAt: { description: 最近更新时间, type: string, format: date-time, nullable: true }
        canManage: { description: 当前用户是否可管理该敏感档案, type: boolean }
    LineagePersonTreeView:
      allOf:
        - $ref: '#/components/schemas/LineagePersonView'
        - type: object
          properties:
            relationType: { description: "固定结构关系：father=父亲，mother=母亲，spouse=配偶；child/sibling 仅为命令类型，不持久化", type: string, enum: [father, mother, spouse], example: spouse, x-dict-type: gen_lineage_relation_type }
            relationName: { description: 关系显示名称, type: string }
            relationVariantCode: { description: 关系显示修饰稳定编码, type: string, nullable: true }
            relationVariantLabel: { description: 关系显示修饰名称, type: string, nullable: true }
            relationVariantOptionState: { description: 关系修饰历史值状态, type: string, enum: [ACTIVE, DISABLED, UNKNOWN], nullable: true }
            spouses:
              description: 配偶节点
              type: array
              items: { $ref: '#/components/schemas/LineagePersonTreeView' }
            children:
              description: 子女节点
              type: array
              items: { $ref: '#/components/schemas/LineagePersonTreeView' }
    RLineagePerson:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data: { $ref: '#/components/schemas/LineagePersonView' }
    RLineagePersonDetail:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data: { $ref: '#/components/schemas/LineagePersonDetailView' }
    RLineagePersonSensitiveProfile:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data: { $ref: '#/components/schemas/LineagePersonSensitiveProfileView' }
    LineageRankOption:
      type: object
      properties:
        rankId: { description: 世系排行配置ID, type: integer, format: int64 }
        rankCode: { description: 排行编码，例如 ANCESTOR、SON_01、DAUGHTER_01, type: string }
        rankName: { description: 排行名称，例如始祖、长子、长女, type: string }
        rankType: { description: "排行类型：ANCESTOR=始祖，GENERATION=世代排行", type: string, enum: [ANCESTOR, GENERATION] }
        genderScope: { description: "适用性别：0=男，1=女，2=通用", type: string, enum: ["0", "1", "2"] }
        rankOrder: { description: 同性别同世代内的排行序号, type: integer, format: int64 }
    RLineageRankOptionList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/LineageRankOption' }
    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' }
    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 }
    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: "字典 sys_normal_disable：0=正常，1=停用；未传时默认为0"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: sys_normal_disable
    FamilyFeedView:
      type: object
      properties:
        canEdit: { type: boolean, description: 当前用户是否可编辑该资源 }
        canDelete: { type: boolean, description: 当前用户是否可删除该资源 }
        feedId: { description: 动态ID, type: integer, format: int64 }
        genealogyId: { description: 所属家谱ID, type: integer, format: int64 }
        genealogyNo: { description: 家谱编号, type: string }
        genealogyName: { description: 家谱名称, type: string }
        publisherUserId: { description: 发布业务用户ID, type: integer, format: int64 }
        publisherNickName: { description: 发布用户昵称, type: string }
        publisherStatus: { description: 发布用户状态, type: string }
        feedType: { description: 动态类型, type: string }
        feedContent: { description: 动态内容, type: string }
        mediaFiles:
          type: array
          items: { $ref: '#/components/schemas/BusinessFileAccess' }
        likedByMe: { description: 当前登录用户是否已点赞, type: boolean, example: false }
        likeCount: { description: 点赞数量, type: integer, format: int64 }
        commentCount: { description: 评论数量, type: integer, format: int64 }
        pinned: { description: "字典 gen_number_yes_no：0=否，1=是", type: string, enum: ["0", "1"], example: "0", x-dict-type: gen_number_yes_no }
        pinnedTime: { description: 置顶时间, type: string, format: date-time, nullable: true }
        sortOrder: { description: 排序值, type: integer, format: int64 }
        status: { description: "字典 sys_normal_disable：0=正常，1=停用", type: string, enum: ["0", "1"], example: "0", x-dict-type: sys_normal_disable }
        remark: { description: 备注, type: string }
        createTime: { description: 发布时间, type: string, format: date-time }
        updateTime: { description: 更新时间, type: string, format: date-time }
    RFamilyFeed:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data: { $ref: '#/components/schemas/FamilyFeedView' }
    RFamilyFeedList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          type: array
          items: { $ref: '#/components/schemas/FamilyFeedView' }
    FamilyFeedPageResult:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        rows:
          type: array
          items: { $ref: '#/components/schemas/FamilyFeedView' }
        total: { description: 总记录数, type: integer, format: int64, example: 0 }
    NotificationView:
      type: object
      properties:
        notificationId: { description: 通知ID, type: integer, format: int64 }
        genealogyId: { description: 所属家谱ID, type: integer, format: int64, nullable: true }
        genealogyNo: { description: 家谱编号, type: string }
        genealogyName: { description: 家谱名称, type: string }
        senderUserId: { description: 发送业务用户ID, type: integer, format: int64, nullable: true }
        senderNickName: { description: 发送用户昵称, type: string }
        noticeType: { description: 通知类型, type: string }
        noticeTitle: { description: 通知标题, type: string }
        noticeContent: { description: 通知正文, type: string }
        bizType: { description: 关联业务类型, type: string }
        bizId: { description: 关联业务ID, type: integer, format: int64, nullable: true }
        bizSummary: { description: 关联业务摘要, type: string }
        publishTime: { description: 发布时间, type: string, format: date-time }
        readStatus: { description: "字典 gen_notification_read_status：0=未读，1=已读", type: string, enum: ["0", "1"], example: "0", x-dict-type: gen_notification_read_status }
        readTime: { description: 阅读时间, type: string, format: date-time, nullable: true }
        status: { description: "字典 sys_normal_disable：0=正常，1=停用", type: string, enum: ["0", "1"], example: "0", x-dict-type: sys_normal_disable }
        remark: { description: 备注, type: string }
    RNotification:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data: { $ref: '#/components/schemas/AppNotification' }
    FamilyFeedCommentBody:
      type: object
      required: [commentContent]
      properties:
        parentCommentId:
          description: 父评论 ID；不传或传 null 表示发布一级评论
          type: integer
          format: int64
          nullable: true
        commentContent:
          description: 评论内容，最多 1000 个字符
          type: string
    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"
        canDelete:
          description: 当前登录用户是否可删除该评论
          type: boolean
        replyCount:
          description: 正常展示的直接回复数量
          type: integer
          format: int64
        commentLevel:
          description: 评论层级，root 为一级评论，reply 为回复
          type: string
          enum: [root, reply]
        status:
          description: "字典 sys_normal_disable：0=正常展示，1=停用；会员接口仅返回0"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: sys_normal_disable
        createTime:
          description: 评论发布时间
          type: string
          format: date-time
    RFamilyFeedComment:
      type: object
      properties:
        code:
          description: 响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
        data:
          $ref: '#/components/schemas/FamilyFeedCommentView'
    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
    GenealogyCreateBody:
      type: object
      required: [genealogyName, firstAncestorName, requestId, surname, regionCode]
      properties:
        genealogyName:
          description: 家谱名称
          type: string
        firstAncestorName:
          description: 始迁祖姓名；建谱时同步创建根人物
          type: string
        requestId:
          description: 客户端建谱幂等请求号；同一次重试必须复用
          type: string
          maxLength: 64
        ownerIsFirstAncestor:
          description: 仅显式传 true 时将当前谱主账号绑定到始迁祖人物；默认 false
          type: boolean
          default: false
        surname:
          description: 姓氏
          type: string
        ancestralHall:
          description: 堂号/祠堂名称
          type: string
        originPlace:
          description: 籍贯/起源地
          type: string
        regionCode:
          description: 行政区划编码
          type: string
        addressDetail:
          description: 详细地址
          type: string
        coverOssId:
          description: 封面图片OSS ID；更新时省略保持原值，显式 null 清空，正整数替换
          type: string
          pattern: '^[1-9][0-9]*$'
          nullable: true
        intro:
          description: 简介
          type: string
        visibility:
          description: "字典 gen_genealogy_visibility：0=私密，1=公开，2=成员可见"
          type: string
          enum: ["0", "1", "2"]
          example: "1"
          x-dict-type: gen_genealogy_visibility
        joinMode:
          description: "字典 gen_genealogy_join_mode：0=关闭加入，1=申请审核，2=邀请码加入"
          type: string
          enum: ["0", "1", "2"]
          example: "1"
          x-dict-type: gen_genealogy_join_mode
      example:
        genealogyName: "彭氏家谱"
        firstAncestorName: "彭氏始迁祖"
        requestId: "create-genealogy-20260824-001"
        ownerIsFirstAncestor: false
        surname: "彭"
        ancestralHall: "陇西堂"
        originPlace: "江西吉安"
        regionCode: "360800"
        addressDetail: "江西省吉安市"
        coverOssId: "2060000000000000001"
        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；更新时省略保持原值，显式 null 清空，正整数替换
          type: string
          pattern: '^[1-9][0-9]*$'
          nullable: true
        intro:
          description: 简介
          type: string
        visibility:
          description: "字典 gen_genealogy_visibility：0=私密，1=公开，2=成员可见"
          type: string
          enum: ["0", "1", "2"]
          example: "1"
          x-dict-type: gen_genealogy_visibility
        joinMode:
          description: "字典 gen_genealogy_join_mode：0=关闭加入，1=申请审核，2=邀请码加入"
          type: string
          enum: ["0", "1", "2"]
          example: "1"
          x-dict-type: gen_genealogy_join_mode
      example:
        genealogyName: "彭氏家谱"
        surname: "彭"
        ancestralHall: "陇西堂"
        originPlace: "江西吉安"
        regionCode: "360800"
        addressDetail: "江西省吉安市"
        coverOssId: "2060000000000000001"
        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
      example:
        applicantName: "彭小明"
        phone: "13800000000"
        relationDesc: "本族成员"
        applyReason: "申请加入家谱维护"
    GenealogyInvitationIssueBody:
      type: object
      additionalProperties: false
      properties:
        lineagePersonId: { type: integer, format: int64, nullable: true, description: 可选的目标世系人物ID；为空时签发普通家谱邀请 }
    GenealogyJoinApplyVo:
      type: object
      properties:
        applyId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        appUserId: { type: integer, format: int64 }
        lineagePersonId: { type: integer, format: int64, nullable: true }
        lineagePersonName: { type: string, nullable: true }
        applicantName: { type: string }
        status: { type: string, enum: ['0', '1', '2', '3'] }
    GenealogyInvitationRedeemBody:
      type: object
      required: [token]
      properties:
        token: { type: string, maxLength: 128, description: 一次性原始邀请码 }
        applicantName: { type: string, maxLength: 50 }
        phone: { type: string, maxLength: 30 }
        relationDesc: { type: string, maxLength: 100 }
        applyReason: { type: string, maxLength: 500 }
    GenealogyJoinAuditBody:
      type: object
      required: [status]
      properties:
        status:
          description: "字典 gen_genealogy_join_apply_status：0=待审核，1=通过，2=拒绝，3=取消"
          type: string
          enum: ["0", "1", "2", "3"]
          example: "1"
          x-dict-type: gen_genealogy_join_apply_status
        auditRemark:
          description: 审核备注
          type: string
      example:
        status: "1"
        auditRemark: "信息核验通过"
    GenealogyMemberUpdateBody:
      type: object
      properties:
        memberName:
          description: 成员姓名
          type: string
        relationName:
          description: 成员关系名称
          type: string
        roleType:
          description: "字典 gen_genealogy_member_role：owner=谱主，admin=管理员，editor=编辑，member=成员，visitor=访客"
          type: string
          enum: [owner, admin, editor, member, visitor]
          example: member
          x-dict-type: gen_genealogy_member_role
        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: "字典 sys_normal_disable：0=正常，1=停用"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: sys_normal_disable
      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；更新时省略保持原值，显式 null 清空，正整数替换
          type: string
          pattern: '^[1-9][0-9]*$'
          nullable: true
        articleContent:
          description: 文章内容
          type: string
        mediaOssIds:
          type: string
          nullable: true
          description: 正文图片OSS ID用英文逗号分隔；创建缺失或空值为无图；更新省略保持，null或空白清空；非空整体替换，去除两侧空格并按首次出现顺序去重；仅允许正整数且规范值总长度不超过1000字符
          example: '2060000000000000002,2060000000000000003'
        authorName:
          description: 作者名称
          type: string
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: "字典 sys_normal_disable：0=正常，1=停用"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: sys_normal_disable
      example:
        categoryId: 900040001
        articleTitle: "族谱源流"
        articleSummary: "介绍本支源流"
        coverOssId: "2060000000000000001"
        articleContent: "<p>article content</p>"
        authorName: "族谱管理员"
        sortOrder: 1
        status: "0"
    ArticleCategoryBody:
      type: object
      required: [categoryName]
      properties:
        categoryName:
          description: 谱文分类名称
          type: string
          maxLength: 100
        categoryDesc:
          description: 谱文分类说明
          type: string
          maxLength: 500
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: "字典 sys_normal_disable：0=正常，1=停用"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: sys_normal_disable
      example:
        categoryName: "姓氏源流"
        categoryDesc: "记录本支姓氏与迁徙源流"
        sortOrder: 10
        status: "0"
    AlbumBody:
      type: object
      required: [albumName]
      properties:
        albumName:
          description: 相册名称
          type: string
        albumDesc:
          description: 相册说明
          type: string
        coverOssId:
          description: 封面图片OSS ID
          type: string
          pattern: '^[1-9][0-9]*$'
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: "字典 sys_normal_disable：0=正常，1=停用"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: sys_normal_disable
      example:
        albumName: "老照片"
        albumDesc: "family old photos"
        coverOssId: "2060000000000000001"
        sortOrder: 1
        status: "0"
    AlbumPhotoBody:
      type: object
      required: [ossId]
      properties:
        ossId:
          description: OSS文件ID，表单内部使用，用户侧应通过上传组件获取
          type: string
          pattern: '^[1-9][0-9]*$'
        photoTitle:
          description: 图片标题
          type: string
        photoDesc:
          description: 图片说明
          type: string
        photographer:
          description: 拍摄人
          type: string
        shootTime:
          description: 拍摄时间
          type: string
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: "字典 sys_normal_disable：0=正常，1=停用"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: sys_normal_disable
      example:
        ossId: "2060000000000000001"
        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
          x-dict-type: gen_ceremony_type
        ceremonyTitle:
          description: 祭祀/活动标题
          type: string
        ceremonyDesc:
          description: 祭祀/活动说明
          type: string
        ceremonyTime:
          description: 祭祀/活动时间
          type: string
        location:
          description: 地点名称，例如祠堂或酒店名称
          type: string
        locationAddress:
          description: 详细地址
          type: string
          maxLength: 300
        longitude:
          description: 经度，必须与纬度同时提供
          type: number
          minimum: -180
          maximum: 180
        latitude:
          description: 纬度，必须与经度同时提供
          type: number
          minimum: -90
          maximum: 90
        coverOssId:
          description: 封面图片OSS ID；更新时省略保持原值，显式 null 清空，正整数替换
          type: string
          pattern: '^[1-9][0-9]*$'
          nullable: true
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: "字典 sys_normal_disable：0=正常，1=停用"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: sys_normal_disable
      example:
        ceremonyType: "ancestor"
        ceremonyTitle: "清明祭祖"
        ceremonyDesc: "online ancestor ceremony"
        ceremonyTime: "2026-04-04 09:00:00"
        location: "祠堂"
        locationAddress: "四川省成都市示例路1号"
        longitude: 104.0665410
        latitude: 30.5722690
        coverOssId: "2060000000000000001"
        sortOrder: 1
        status: "0"
    CeremonyInviteesBody:
      type: object
      required: [inviteeUserIds]
      properties:
        inviteeUserIds:
          description: 完整受邀业务用户ID列表；空数组表示取消全部尚未响应的邀请
          type: array
          uniqueItems: true
          items: { type: integer, format: int64 }
      example:
        inviteeUserIds: [900000001, 900000002]
    CeremonyInviteeOptionVo:
      type: object
      additionalProperties: false
      properties:
        memberId: { type: integer, format: int64 }
        appUserId: { type: integer, format: int64 }
        displayName: { type: string }
        memberRole: { type: string }
        eligible: { type: boolean }
        disabledReason: { type: string, nullable: true }
        sortOrder: { type: integer, format: int64 }
    RCeremonyInviteeOptionList:
      type: object
      properties:
        code: { type: integer, example: 200 }
        msg: { type: string }
        data: { type: array, items: { $ref: '#/components/schemas/CeremonyInviteeOptionVo' } }
    CeremonyInvitationResponseBody:
      type: object
      required: [inviteStatus]
      properties:
        inviteStatus:
          description: 当前用户的邀约响应，只允许接受或拒绝
          type: string
          enum: [ACCEPTED, DECLINED]
      example:
        inviteStatus: "ACCEPTED"
    CeremonyInvitationVo:
      type: object
      properties:
        invitationId: { description: 邀约ID, type: integer, format: int64 }
        genealogyId: { description: 家谱ID, type: integer, format: int64 }
        ceremonyId: { description: 贺礼活动ID, type: integer, format: int64 }
        inviteeUserId: { description: 受邀业务用户ID, type: integer, format: int64 }
        inviteStatus: { description: 邀约状态, type: string, enum: [PENDING, ACCEPTED, DECLINED, CANCELED] }
        inviteVersion: { description: 邀请版本，取消后重新邀请时递增, type: integer }
        deliveredTime: { description: 邀请投递时间, type: string, format: date-time }
        readTime: { description: 邀请阅读时间, type: string, format: date-time }
        responseTime: { description: 接受或拒绝时间, type: string, format: date-time }
        ceremonyTitle: { description: 贺礼活动标题, type: string }
        ceremonyTime: { description: 贺礼活动时间, type: string, format: date-time }
        location: { description: 地点名称, type: string }
        locationAddress: { description: 详细地址, type: string }
        longitude: { description: 经度, type: number }
        latitude: { description: 纬度, type: number }
    RCeremonyInvitation:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          $ref: '#/components/schemas/CeremonyInvitationVo'
    RCeremonyInvitationList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          description: 贺礼邀约列表
          type: array
          items:
            $ref: '#/components/schemas/CeremonyInvitationVo'
    CeremonyGiftBody:
      type: object
      required: [giftAmount]
      properties:
        giverName:
          description: 赠送人/献礼人姓名
          type: string
        giftAmount:
          description: 人民币金额（元）
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
          multipleOf: 0.01
        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
          x-dict-type: gen_growth_record_type
        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: "字典 sys_normal_disable：0=正常，1=停用"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: sys_normal_disable
      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"
    LifeEventBody:
      type: object
      required: [eventType, eventTitle, eventDate, datePrecision]
      properties:
        eventType:
          description: "字典 gen_life_event_type：BIRTH=出生，EDUCATION=求学，CAREER=事业，MARRIAGE=婚姻，MIGRATION=迁居，HONOR=荣誉，MAJOR_ACHIEVEMENT=重要成就，DEATH=逝世，OTHER=其他"
          type: string
          enum: [BIRTH, EDUCATION, CAREER, MARRIAGE, MIGRATION, HONOR, MAJOR_ACHIEVEMENT, DEATH, OTHER]
          example: EDUCATION
          x-dict-type: gen_life_event_type
        eventTitle: { description: 事件标题, type: string, example: 进入县立小学 }
        eventContent: { description: 事件详细内容, type: string, example: 在县立小学完成启蒙教育 }
        eventDate:
          description: 事件日期；精度为 YEAR 时传当年 01-01，MONTH 时传当月 01 日
          type: string
          format: date
          example: "1936-09-01"
        datePrecision:
          description: "日期精度：YEAR=年，MONTH=月，DAY=日"
          type: string
          enum: [YEAR, MONTH, DAY]
          example: DAY
        eventPlace: { description: 事件地点, type: string, example: 四川省成都市 }
        sourceDescription: { description: 资料来源说明, type: string, example: 家谱手稿 }
        mediaOssIds:
          description: 媒体文件 OSS ID 数组；使用统一 APP 文件上传接口取得字符串 ID
          type: array
          items: { type: string, pattern: '^[1-9][0-9]*$' }
          example: ["2060000000000000001"]
        sortOrder: { description: 排序值，数值越小越靠前, type: integer, format: int64, example: 1 }
        status:
          description: "字典 sys_normal_disable：0=正常，1=停用"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: sys_normal_disable
        remark: { description: 备注, type: string }
    LifeEventView:
      allOf:
        - $ref: '#/components/schemas/LifeEventBody'
        - type: object
          properties:
            eventId: { description: 人生大事ID, type: integer, format: int64, example: 2072800000000000100 }
            genealogyId: { description: 家谱ID, type: integer, format: int64, example: 900001001 }
            lineagePersonId: { description: 世系人物ID, type: integer, format: int64, example: 900020001 }
            creatorUserId: { description: 创建人的业务用户ID, type: integer, format: int64, example: 900000001 }
    RLifeEvent:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data: { $ref: '#/components/schemas/AppLifeEvent' }
    RLifeEventList:
      type: object
      properties:
        code: { description: 响应状态码, type: integer, example: 200 }
        msg: { description: 响应消息, type: string, example: 操作成功 }
        data:
          description: 人生大事列表
          type: array
          items: { $ref: '#/components/schemas/AppLifeEvent' }
    MemoBody:
      type: object
      required: [memoTitle]
      properties:
        memoType:
          description: 备忘类型；省略时默认 general
          type: string
          enum: [general, benefactor]
          default: general
        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: "字典 sys_normal_disable：0=正常，1=停用"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: sys_normal_disable
      example:
        memoType: "general"
        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, format: double, minimum: 0, maximum: 9999999999.99, multipleOf: 0.01 }
        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: "字典 sys_normal_disable：0=正常，1=停用", type: string, enum: ["0", "1"], example: "0", x-dict-type: sys_normal_disable }
    MeritRecordBody:
      type: object
      required: [donorName, meritTitle]
      properties:
        donorName:
          description: 功德人/捐赠人姓名
          type: string
        meritType:
          description: "字典 gen_merit_type：donation=捐赠，repair=修祠，public=公益，other=其他"
          type: string
          example: donation
          x-dict-type: gen_merit_type
        meritTitle:
          description: 功德标题
          type: string
        meritContent:
          description: 功德内容
          type: string
        mediaOssIds:
          description: 媒体文件 OSS ID 列表；多个正整数 ID 使用英文逗号分隔，空字符串清空
          type: string
          pattern: '^$|^[1-9][0-9]*(,[1-9][0-9]*)*$'
        amount:
          description: 人民币金额（元）
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
          multipleOf: 0.01
        meritTime:
          description: 功德时间
          type: string
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: "字典 sys_normal_disable：0=正常，1=停用"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: sys_normal_disable
      example:
        donorName: "彭小明"
        meritType: "donation"
        meritTitle: "修谱捐款"
        meritContent: "support genealogy work"
        mediaOssIds: "2060000000000000001"
        amount: 100.0
        meritTime: "2026-07-09 10:00:00"
        sortOrder: 1
        status: "0"
    VideoBody:
      type: object
      additionalProperties: false
      required: [videoTitle, videoOssId]
      properties:
        videoTitle:
          description: 视频标题
          type: string
        videoDesc:
          description: 视频说明
          type: string
        coverOssId:
          description: 视频封面文件 OSS ID；更新时省略保持原值，显式 null 清空，正整数替换
          type: string
          pattern: '^[1-9][0-9]*$'
          nullable: true
        videoOssId:
          description: 视频文件 OSS ID
          type: string
          pattern: '^[1-9][0-9]*$'
        durationSeconds:
          description: 视频时长，单位秒
          type: integer
          format: int64
        sortOrder:
          description: 排序值，数值越小越靠前
          type: integer
          format: int64
        status:
          description: "字典 sys_normal_disable：0=正常，1=停用"
          type: string
          enum: ["0", "1"]
          example: "0"
          x-dict-type: sys_normal_disable
    FeedbackBody:
      type: object
      required: [feedbackContent]
      properties:
        feedbackType:
          description: "字典 gen_feedback_type：advice=建议，bug=故障，complaint=投诉，other=其他"
          type: string
          example: bug
          x-dict-type: gen_feedback_type
        feedbackContent:
          description: 反馈内容
          type: string
        contactInfo:
          description: 联系方式
          type: string
      example:
        feedbackType: "bug"
        feedbackContent: "upload image failed"
        contactInfo: "13800000000"
    AppVipOrderBody:
      type: object
      additionalProperties: false
      required: [packageId, paymentMethod, requestId]
      properties:
        packageId:
          description: VIP套餐ID
          type: integer
          format: int64
        genealogyId:
          description: 家谱ID；购买家谱维度套餐时填写
          type: integer
          format: int64
          nullable: true
        paymentMethod:
          description: APP 支付方式；由购买能力接口决定当前租户可用项
          type: string
          enum: [WECHAT, ALIPAY, BALANCE]
        requestId:
          description: 客户端幂等请求号；同一购买动作重试必须复用
          type: string
          maxLength: 64
      example:
        packageId: 900060001
        genealogyId: 900001001
        paymentMethod: WECHAT
        requestId: app-vip-order-20260818-001
    HelpArticleVo:
      type: object
      properties:
        helpId: { type: integer, format: int64, description: 帮助文章ID }
        helpCategory: { type: string, enum: [common, member, lineage], description: 稳定帮助分类码 }
        helpCategoryLabel: { type: string, nullable: true, description: 帮助分类中文标签 }
        helpTitle: { type: string, description: 标题 }
        helpContent: { type: string, description: 内容 }
        coverOssId: { type: integer, format: int64, description: 封面文件ID }
        sortOrder: { type: integer, format: int64, description: 排序 }
        viewCount: { type: integer, format: int64, description: 浏览量 }
        status: { type: string, description: 状态 }
        remark: { type: string, description: 备注 }
    GenealogyInvitationVo:
      type: object
      properties:
        inviteId: { type: integer, format: int64, description: 邀请ID }
        genealogyId: { type: integer, format: int64, description: 家谱ID }
        genealogyNo: { type: string, description: 家谱编号 }
        genealogyName: { type: string, description: 家谱名称 }
        inviterUserId: { type: integer, format: int64, description: 服务端确定的邀请人ID，只读 }
        lineagePersonId: { type: integer, format: int64, nullable: true, description: 指定绑定的世系人物ID }
        lineagePersonName: { type: string, nullable: true, description: 指定绑定的世系人物姓名 }
        status: { type: string, description: 邀请状态 }
        expiresAt: { type: string, format: date-time, description: 过期时间 }
        redeemedBy: { type: integer, format: int64, description: 兑换用户ID }
        redeemedAt: { type: string, format: date-time, description: 兑换时间 }
        revokedAt: { type: string, format: date-time, description: 撤销时间 }
        createTime: { type: string, format: date-time, description: 创建时间 }
        token: { type: string, description: 仅签发成功的本次响应返回原始一次性 token }
        redemptionResult: { type: string, description: 兑换结果 }
        applyId: { type: integer, format: int64, description: 审核模式生成的申请ID }
        memberId: { type: integer, format: int64, description: 直接加入模式生成或恢复的成员ID }
    RHelpArticle: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/HelpArticleVo' } } }
    RHelpArticleList: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { type: array, items: { $ref: '#/components/schemas/HelpArticleVo' } } } }
    VipPurchaseCapability:
      type: object
      required: [enabled, paymentMethods]
      properties:
        enabled: { type: boolean, description: 当前租户和支付渠道是否允许购买 }
        disabledReason: { type: string, nullable: true, description: 不可购买时的可展示原因 }
        paymentMethods:
          type: array
          description: APP 当前租户的支付方式能力；仅 enabled=true 的方式可以下单
          items: { $ref: '#/components/schemas/VipPaymentMethodCapability' }
    VipPaymentMethodCapability:
      type: object
      required: [method, enabled]
      properties:
        method: { type: string, enum: [WECHAT, ALIPAY, BALANCE], description: 支付方式稳定码 }
        enabled: { type: boolean, description: 当前租户是否可使用该支付方式 }
        disabledReason: { type: string, nullable: true, description: 当前方式不可用时的原因 }
    RVipPurchaseCapability: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/VipPurchaseCapability' } } }
    RContentPasswordRecoveryCapability: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/ContentPasswordRecoveryCapability' } } }
    RGenealogyPermanentDeletionCapability: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/GenealogyPermanentDeletionCapability' } } }
    RGenealogyDeletionTask: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/GenealogyDeletionTask' } } }
    RVipPackageList: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { type: array, items: { $ref: '#/components/schemas/VipPackageVo' } } } }
    RVipOrder: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/VipOrderVo' } } }
    RVipOrderList: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { type: array, items: { $ref: '#/components/schemas/VipOrderVo' } } } }
    RPaymentOrder: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/PaymentOrderVo' } } }
    RPaymentTransactionStatus: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/PaymentTransactionStatusVo' } } }
    RGenealogyInvitation: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/GenealogyInvitationVo' } } }
    RGenealogyInvitationList: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { type: array, items: { $ref: '#/components/schemas/GenealogyInvitationVo' } } } }
    VipPackageVo:
      type: object
      properties:
        packageId: { type: integer, format: int64, description: 套餐ID }
        packageName: { type: string, description: 套餐名称 }
        packageType: { type: string, description: 套餐类型 }
        packageDesc: { type: string, description: 套餐说明 }
        price: { type: number, description: 当前售价 }
        originalPrice: { type: number, description: 原价 }
        durationValue: { type: integer, format: int64, description: 有效期数值 }
        durationUnit: { type: string, description: 有效期单位 }
        genealogyLimit: { type: integer, format: int64, description: 可用家谱数量限制 }
        memberLimit: { type: integer, format: int64, description: 成员数量限制 }
        storageLimitMb: { type: integer, format: int64, description: 存储空间限制，单位MB }
        featureJson: { type: string, description: 套餐功能JSON }
        sortOrder: { type: integer, format: int64, description: 排序 }
        status: { type: string, description: 状态，0正常、1停用 }
        remark: { type: string, description: 备注 }
    VipOrderVo:
      type: object
      properties:
        orderId: { type: integer, format: int64, description: VIP订单ID }
        orderNo: { type: string, description: VIP业务订单号 }
        packageId: { type: integer, format: int64, description: 套餐ID }
        packageName: { type: string, description: 套餐名称 }
        appUserId: { type: integer, format: int64, description: 业务用户ID }
        appUserNickName: { type: string, description: 会员昵称 }
        appUserPhone: { type: string, description: 会员手机号 }
        genealogyId: { type: integer, format: int64, description: 家谱ID }
        genealogyNo: { type: string, description: 家谱编号 }
        genealogyName: { type: string, description: 家谱名称 }
        orderAmount: { type: number, description: 订单金额 }
        payAmount: { type: number, description: 实付金额 }
        payType: { type: string, description: 支付方式，由后端确定 }
        payStatus: { type: string, description: VIP订单支付状态 }
        payTime: { type: string, format: date-time, description: 支付时间 }
        expireTime: { type: string, format: date-time, description: 订单过期时间 }
        status: { type: string, description: 业务状态 }
        remark: { type: string, description: 备注 }
        transactionId: { type: integer, format: int64, nullable: true, description: 当前 APP 支付流水ID }
        canRefreshPayment: { type: boolean, description: 是否可刷新支付状态 }
        canClose: { type: boolean, description: 是否可关闭支付 }
    PaymentOrderVo:
      type: object
      description: APP VIP 下单结果；按 paymentMethod 使用对应字段，未使用字段为 null
      properties:
        order:
          $ref: '#/components/schemas/VipOrderVo'
        transactionId:
          type: integer
          format: int64
          description: 支付流水ID
        outTradeNo:
          type: string
          description: 商户支付单号
        tradeType:
          type: string
          enum: [APP]
          description: APP 端交易类型；微信、支付宝和余额均固定为 APP
        paymentMethod:
          type: string
          enum: [WECHAT, ALIPAY, BALANCE]
          description: 本次订单实际支付方式
        expiresAt:
          type: string
          format: date-time
          description: 支付单过期时间
        prepayId:
          type: string
          nullable: true
          description: APP 微信预支付ID
        appId:
          type: string
          description: 微信开放平台应用ID
        partnerId:
          type: string
          description: 微信支付商户号
        packageValue:
          type: string
          description: 调起微信支付使用的 package 值
        nonceStr:
          type: string
          description: 随机字符串
        timestamp:
          type: string
          description: 支付签名时间戳
        sign:
          type: string
          description: 调起微信支付使用的签名
        orderString:
          type: string
          nullable: true
          description: 支付宝 APP SDK 调起支付使用的完整订单字符串
        completed:
          type: boolean
          description: 是否已在本次请求内完成支付；余额成功扣款时为 true
    PaymentTransactionStatusVo:
      type: object
      properties:
        transactionId:
          type: integer
          format: int64
          description: 支付流水ID
        orderNo:
          type: string
          description: VIP业务订单号
        outTradeNo:
          type: string
          description: 商户支付单号
        status:
          type: string
          enum: [CREATED, PAYING, SUCCESS, CLOSED, REFUNDING, REFUNDED]
          description: 支付状态
        providerTradeState:
          type: string
          description: 微信支付侧交易状态
        providerTransactionId:
          type: string
          description: 微信支付订单号
        paidAt:
          type: string
          format: date-time
          description: 支付成功时间
        closedAt:
          type: string
          format: date-time
          description: 支付关闭时间
    VerificationChallengeBody:
      type: object
      additionalProperties: false
      required: [tenantId, subject]
      properties:
        tenantId:
          type: string
          description: 租户 ID
        subject:
          type: string
          description: 验证主体，如手机号/用户名/IP
      example:
        tenantId: "000000"
        subject: "13800000000"
    VerificationCheckBody:
      type: object
      additionalProperties: false
      required: [tenantId, subject, challengeId]
      properties:
        tenantId:
          description: 租户ID，用于区分不同租户的数据和验证策略
          type: string
        subject:
          description: 验证主体，通常为手机号、用户ID或登录账号
          type: string
        challengeId:
          description: 验证挑战ID，由验证挑战接口返回
          type: string
        providerCode:
          type: string
          description: 验证服务，tianai 或 ruoyi_image
        captchaType:
          type: string
          description: SLIDER/ROTATE/CONCAT/WORD_IMAGE_CLICK/math/char
        payload:
          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
          nullable: true
          additionalProperties: true
          description: 不同验证码类型附带的扩展数据，由天爱前端控件原样提交
    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: 用户填写的图形验证码答案
    VerificationRequireVo:
      type: object
      properties:
        required:
          description: 当前场景是否需要验证
          type: boolean
        providerCode:
          description: 第三方服务商编码
          type: string
        captchaType:
          description: 验证码类型，例如SLIDER、ROTATE、CONCAT、WORD_IMAGE_CLICK
          type: string
        sceneCode:
          description: 服务端按当前业务动作和激活绑定解析出的实际验证场景编码
          type: string
        ttlSeconds:
          description: 验证或票据有效秒数
          type: integer
      example:
        required: true
        providerCode: "tianai"
        captchaType: "SLIDER"
        sceneCode: "APP_LOGIN_ACTIVE_SCENE"
        ttlSeconds: 300
    VerificationChallengeVo:
      type: object
      properties:
        required:
          description: 当前场景是否需要验证
          type: boolean
        providerCode:
          description: 第三方服务商编码
          type: string
        captchaType:
          description: 验证码类型，例如SLIDER、ROTATE、CONCAT、WORD_IMAGE_CLICK
          type: string
        challengeId:
          description: 验证挑战ID，由验证挑战接口返回
          type: string
        uuid:
          type: string
          description: 系统图形验证码 uuid
        img:
          type: string
          description: 系统图形验证码 base64 图片
        payload:
          type: object
          additionalProperties: true
          description: 天爱验证码数据，包括背景图、模板图、尺寸等
        expireSeconds:
          description: 验证挑战过期秒数
          type: integer
      example:
        required: true
        providerCode: "tianai"
        captchaType: "SLIDER"
        challengeId: "CAPTCHA_CHALLENGE_ID"
        payload:
          backgroundImage: "data:image/png;base64,..."
          templateImage: "data:image/png;base64,..."
          backgroundImageWidth: 340
          backgroundImageHeight: 180
        expireSeconds: 300
    VerificationCheckVo:
      type: object
      properties:
        passed:
          description: 验证是否通过
          type: boolean
        validToken:
          type: string
          description: 验证通过后交给发送短信验证码接口的票据
        expireSeconds:
          description: 验证挑战过期秒数
          type: integer
        message:
          description: 返回消息
          type: string
      example:
        passed: true
        validToken: "captcha-ticket"
        expireSeconds: 300
        message: "验证通过"
    LegacyCaptchaVo:
      type: object
      properties:
        captchaEnabled:
          type: boolean
        uuid:
          description: 系统图形验证码UUID
          type: string
        img:
          type: string
          description: base64 图形验证码
      example:
        captchaEnabled: true
        uuid: "captcha-uuid"
        img: "data:image/png;base64,..."
    RVerificationRequire:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: "操作成功"
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/VerificationRequireVo'
    RVerificationChallenge:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: "操作成功"
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/VerificationChallengeVo'
    RVerificationCheck:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: "操作成功"
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/VerificationCheckVo'
    RLegacyCaptcha:
      type: object
      properties:
        code:
          description: 系统图形验证码或响应状态码
          type: integer
          example: 200
        msg:
          description: 响应消息
          type: string
          example: "操作成功"
        data:
          description: 响应数据主体
          $ref: '#/components/schemas/LegacyCaptchaVo'
    RecommendationPreferenceBody:
      type: object
      additionalProperties: false
      required: [enabled]
      properties: { enabled: { type: boolean } }
    RecommendationEventBody:
      type: object
      additionalProperties: false
      required: [eventKey, eventType, source, feedId]
      properties:
        eventKey: { type: string, maxLength: 64 }
        eventType: { type: string, enum: [VIEW, CLICK, HIDE, SHARE] }
        source: { type: string, enum: [FEED_LIST, FEED_DETAIL] }
        feedId: { type: integer, format: int64 }
    RecommendationPreferenceView:
      type: object
      required: [enabled, version, eventTrackingEnabled]
      properties:
        enabled: { type: boolean }
        version: { type: integer, minimum: 0 }
        updatedAt: { type: string, format: date-time, nullable: true }
        eventTrackingEnabled: { type: boolean }
        eventTrackingDisabledReason: { type: string, nullable: true, enum: [USER_DISABLED, TENANT_POLICY_DISABLED, TENANT_POLICY_INVALID] }
    VideoCommentBody:
      type: object
      additionalProperties: false
      required: [commentContent]
      properties:
        parentCommentId: { type: integer, format: int64, nullable: true }
        commentContent: { type: string, maxLength: 1000 }
    VideoLike:
      type: object
      properties: { likeId: { type: integer, format: int64 }, genealogyId: { type: integer, format: int64 }, videoId: { type: integer, format: int64 }, appUserId: { type: integer, format: int64 } }
    VideoComment:
      type: object
      properties:
        commentId: { type: integer, format: int64 }
        genealogyId: { type: integer, format: int64 }
        videoId: { type: integer, format: int64 }
        parentCommentId: { type: integer, format: int64, nullable: true }
        appUserId: { type: integer, format: int64 }
        appUserNickName: { type: string }
        commentContent: { type: string, nullable: true }
        userDeleted: { type: string, enum: ['0', '1'] }
        replyCount: { type: integer, format: int64 }
        createTime: { type: string, format: date-time }
        canDelete: { type: boolean }
    RVideoLike:
      type: object
      properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/VideoLike' } }
    RVideoComment:
      type: object
      properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/VideoComment' } }
    RVideoCommentList:
      type: object
      properties: { code: { type: integer }, msg: { type: string }, data: { type: array, items: { $ref: '#/components/schemas/VideoComment' } } }
    VideoCommentPage:
      type: object
      properties: { total: { type: integer, format: int64 }, rows: { type: array, items: { $ref: '#/components/schemas/VideoComment' } }, code: { type: integer }, msg: { type: string } }
    RecommendationEventView:
      type: object
      properties:
        eventId: { type: integer, format: int64 }
        eventKey: { type: string }
        genealogyId: { type: integer, format: int64 }
        targetType: { type: string, enum: [FAMILY_FEED] }
        targetId: { type: integer, format: int64 }
        eventType: { type: string, enum: [VIEW, CLICK, HIDE, SHARE] }
        source: { type: string, enum: [FEED_LIST, FEED_DETAIL] }
        occurredAt: { type: string, format: date-time }
        expiresAt: { type: string, format: date-time }
    FamilyFeedRecommendationView:
      type: object
      required: [feed, reasonCode, reasonText]
      properties:
        feed: { $ref: '#/components/schemas/FamilyFeedView' }
        reasonCode: { type: string, enum: [MANUAL_PRIORITY, FOLLOWED_INTERACTION, POPULAR_IN_GENEALOGY, RECENT_IN_GENEALOGY] }
        reasonText: { type: string }
    RRecommendationPreference:
      type: object
      properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/RecommendationPreferenceView' } }
    RRecommendationEvent:
      type: object
      properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/RecommendationEventView' } }
    RFamilyFeedRecommendationList:
      type: object
      properties: { code: { type: integer }, msg: { type: string }, data: { type: array, items: { $ref: '#/components/schemas/FamilyFeedRecommendationView' } } }
    ContentRecycleItem:
      type: object
      required: [itemId, genealogyId, resourceType, resourceId, recycleStatus, canRestore]
      properties: { itemId: { type: integer, format: int64 }, genealogyId: { type: integer, format: int64 }, resourceType: { type: string, enum: [family_feed, video, growth_record, relative_record, memo, merit_record, article, album, album_photo, ceremony] }, resourceId: { type: integer, format: int64 }, resourceTitle: { type: string, nullable: true }, resourceSummary: { type: string, nullable: true }, recycleStatus: { type: string, enum: [OPEN, RESTORED] }, deletedBy: { type: integer, format: int64, nullable: true }, deletedAt: { type: string, format: date-time }, restoredBy: { type: integer, format: int64, nullable: true }, restoredAt: { type: string, format: date-time, nullable: true }, canRestore: { type: boolean }, disabledReason: { type: string, enum: [ALREADY_RESTORED], nullable: true } }
    ContentRecycleItemPageResult: { type: object, properties: { code: { type: integer }, msg: { type: string }, total: { type: integer, format: int64 }, rows: { type: array, items: { $ref: '#/components/schemas/ContentRecycleItem' } } } }
    RContentRecycleItem: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/ContentRecycleItem' } } }
    PlatformVideoCommentBody:
      type: object
      required: [commentContent]
      properties: { commentContent: { type: string, maxLength: 1000 } }
    PlatformVideoComment:
      type: object
      properties: { commentId: { type: integer, format: int64 }, platformVideoId: { type: integer, format: int64 }, appUserId: { type: integer, format: int64 }, appUserNickName: { type: string }, commentContent: { type: string, nullable: true }, userDeleted: { type: string, enum: ['0','1'] }, createTime: { type: string, format: date-time }, canDelete: { type: boolean } }
    PlatformVideo:
      type: object
      required: [platformVideoId, videoTitle, platform, placement, likedByCurrentUser]
      properties: { platformVideoId: { type: integer, format: int64 }, videoTitle: { type: string }, videoDesc: { type: string }, coverFile: { $ref: '#/components/schemas/BusinessFileAccess' }, videoFile: { $ref: '#/components/schemas/BusinessFileAccess' }, durationSeconds: { type: integer, format: int64 }, platform: { type: string, enum: [app, pc, wechat, all] }, placement: { type: string, enum: [home_featured, video_center, profile_featured] }, startAt: { type: string, format: date-time, nullable: true }, endAt: { type: string, format: date-time, nullable: true }, viewCount: { type: integer, format: int64 }, likeCount: { type: integer, format: int64 }, commentCount: { type: integer, format: int64 }, likedByCurrentUser: { type: boolean } }
    RPlatformVideo: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/PlatformVideo' } } }
    RPlatformVideoList: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { type: array, items: { $ref: '#/components/schemas/PlatformVideo' } } } }
    RPlatformVideoComment: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { $ref: '#/components/schemas/PlatformVideoComment' } } }
    RPlatformVideoCommentList: { type: object, properties: { code: { type: integer }, msg: { type: string }, data: { type: array, items: { $ref: '#/components/schemas/PlatformVideoComment' } } } }