# 已废弃：本文件保留仅用于追溯此前的账号闭环方案。
# 正式接口源为 PC.openapi2.json；代码、测试和后续开发不得再以本文件为依据。
openapi: 3.0.3
info:
  title: 代代相传 PC 用户端 API
  version: 1.1.0
  description: |
    本文档是当前 PC 用户端唯一接口契约。
    范围仅包含账号认证、个人资料、安全设置、头像上传、验证码与行政区划。
    家谱、社区、内容、会员、支付及平台运营能力不在本期范围内。
servers:
  - url: https://{host}
    variables:
      host:
        default: api.example.com
        description: 由部署环境配置的 HTTPS API 域名
tags:
  - name: 认证登录
  - name: 验证中心
  - name: 文件上传
  - name: 行政区划
paths:
  /genealogy/pc/auth/register:
    post:
      tags: [认证登录]
      summary: PC 用户注册
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        '200':
          description: 注册结果；客户端不保存注册响应中的令牌
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
  /genealogy/pc/auth/login:
    post:
      tags: [认证登录]
      summary: PC 密码登录
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordLoginRequest'
      responses:
        '200':
          description: 登录成功并返回令牌
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
  /genealogy/pc/auth/login/sms:
    post:
      tags: [认证登录]
      summary: PC 短信登录
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmsLoginRequest'
      responses:
        '200':
          description: 登录成功并返回令牌
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
  /genealogy/pc/auth/sms/code:
    post:
      tags: [认证登录]
      summary: 发送短信验证码
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmsCodeRequest'
      responses:
        '200':
          description: 短信已受理
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoidResponse'
  /genealogy/pc/auth/profile:
    get:
      tags: [认证登录]
      summary: 获取当前用户资料
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          description: 当前登录用户资料
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
    put:
      tags: [认证登录]
      summary: 更新当前用户资料
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileUpdateRequest'
      responses:
        '200':
          description: 更新后的用户资料
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
  /genealogy/pc/auth/password:
    put:
      tags: [认证登录]
      summary: 修改当前用户密码
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordChangeRequest'
      responses:
        '200':
          description: 密码修改成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoidResponse'
  /genealogy/pc/auth/password/reset:
    put:
      tags: [认证登录]
      summary: 找回密码
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordResetRequest'
      responses:
        '200':
          description: 密码重置成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoidResponse'
  /genealogy/pc/auth/phone:
    put:
      tags: [认证登录]
      summary: 换绑手机号
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneChangeRequest'
      responses:
        '200':
          description: 换绑后的用户资料
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
  /genealogy/pc/auth/account/deactivate:
    post:
      tags: [认证登录]
      summary: 注销当前账号
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountDeactivateRequest'
      responses:
        '200':
          description: 注销申请已受理
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoidResponse'
  /genealogy/pc/auth/logout:
    delete:
      tags: [认证登录]
      summary: 退出登录
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      responses:
        '200':
          description: 服务端会话已退出
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoidResponse'
  /captcha/require:
    get:
      tags: [验证中心]
      summary: 查询场景是否需要验证码
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: tenantId
          in: query
          schema:
            type: string
            default: '000000'
        - name: clientId
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/SceneCode'
        - name: subject
          in: query
          description: 手机号或其他待验证主体
          schema:
            type: string
      responses:
        '200':
          description: 当前场景验证码策略
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaptchaRequirementResponse'
  /captcha/challenge:
    post:
      tags: [验证中心]
      summary: 创建验证码挑战
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaptchaChallengeRequest'
      responses:
        '200':
          description: 验证码挑战
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaptchaChallengeResponse'
  /captcha/verify:
    post:
      tags: [验证中心]
      summary: 校验验证码并换取业务票据
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaptchaVerifyRequest'
      responses:
        '200':
          description: 返回可提交给后续业务接口的 validToken
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaptchaVerifyResponse'
  /genealogy/pc/files/upload:
    post:
      tags: [文件上传]
      summary: 上传个人头像文件
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: 上传结果
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadResponse'
  /genealogy/region/children:
    get:
      tags: [行政区划]
      summary: 查询下级行政区划
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: parentCode
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 下级地区列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionListResponse'
  /genealogy/region/path/{regionCode}:
    get:
      tags: [行政区划]
      summary: 查询地区完整路径
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/RegionCode'
      responses:
        '200':
          description: 根节点到目标地区的路径
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionListResponse'
  /genealogy/region/search:
    get:
      tags: [行政区划]
      summary: 搜索行政区划
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - name: keyword
          in: query
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 50
      responses:
        '200':
          description: 匹配的地区列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionListResponse'
  /genealogy/region/{regionCode}:
    get:
      tags: [行政区划]
      summary: 查询行政区划详情
      security: []
      parameters:
        - $ref: '#/components/parameters/ClientIdHeader'
        - $ref: '#/components/parameters/RegionCode'
      responses:
        '200':
          description: 地区详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionResponse'
components:
  parameters:
    ClientIdHeader:
      name: clientid
      in: header
      required: true
      description: PC 客户端标识
      schema:
        type: string
        example: ced7e5f0498645c6ec642dcf450b036f
    RegionCode:
      name: regionCode
      in: path
      required: true
      schema:
        type: string
        example: '110101'
    SceneCode:
      name: sceneCode
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/CaptchaSceneCode'
  schemas:
    CaptchaSceneCode:
      type: string
      enum:
        - WEB_H5_LOGIN
        - WEB_H5_REGISTER
        - WEB_H5_FORGOT_PASSWORD
        - WEB_H5_CHANGE_PASSWORD
        - WEB_H5_CHANGE_PHONE
    RegisterRequest:
      type: object
      required: [grantType, tenantId, phone, password]
      properties:
        grantType:
          type: string
          enum: [password]
        tenantId:
          type: string
          example: '000000'
        clientId:
          type: string
        phone:
          type: string
          pattern: '^1[3-9]\\d{9}$'
        password:
          type: string
          description: 32 位 MD5 值；传输层必须使用 HTTPS
          pattern: '^[a-fA-F0-9]{32}$'
        nickName:
          type: string
          maxLength: 32
        registerSource:
          type: string
          enum: [PC]
        validToken:
          type: string
    PasswordLoginRequest:
      type: object
      required: [grantType, tenantId, phone, password]
      properties:
        grantType:
          type: string
          enum: [password]
        tenantId:
          type: string
        clientId:
          type: string
        phone:
          type: string
          pattern: '^1[3-9]\\d{9}$'
        password:
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        validToken:
          type: string
    SmsLoginRequest:
      type: object
      required: [grantType, tenantId, phone, smsCode]
      properties:
        grantType:
          type: string
          enum: [sms]
        tenantId:
          type: string
        clientId:
          type: string
        phone:
          type: string
          pattern: '^1[3-9]\\d{9}$'
        smsCode:
          type: string
          pattern: '^\\d{4,8}$'
        validToken:
          type: string
    SmsCodeRequest:
      type: object
      required: [tenantId, phone, sceneCode]
      properties:
        tenantId:
          type: string
        clientId:
          type: string
        phone:
          type: string
          pattern: '^1[3-9]\\d{9}$'
        sceneCode:
          $ref: '#/components/schemas/CaptchaSceneCode'
        validToken:
          type: string
    PasswordChangeRequest:
      type: object
      required: [oldPassword, newPassword]
      properties:
        oldPassword:
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        newPassword:
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        validToken:
          type: string
    PasswordResetRequest:
      type: object
      required: [tenantId, phone, smsCode, newPassword]
      properties:
        tenantId:
          type: string
        phone:
          type: string
          pattern: '^1[3-9]\\d{9}$'
        smsCode:
          type: string
          pattern: '^\\d{4,8}$'
        newPassword:
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        validToken:
          type: string
    PhoneChangeRequest:
      type: object
      required: [newPhone, smsCode]
      properties:
        newPhone:
          type: string
          pattern: '^1[3-9]\\d{9}$'
        smsCode:
          type: string
          pattern: '^\\d{4,8}$'
        validToken:
          type: string
    AccountDeactivateRequest:
      type: object
      required: [password]
      properties:
        password:
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        reason:
          type: string
          maxLength: 200
    ProfileUpdateRequest:
      type: object
      properties:
        nickName:
          type: string
          maxLength: 32
        avatarOssId:
          type: integer
          format: int64
        sex:
          type: string
          enum: ['0', '1', '2']
        birthday:
          type: string
          format: date
        provinceCode:
          type: string
        cityCode:
          type: string
        districtCode:
          type: string
        addressDetail:
          type: string
          maxLength: 100
    Profile:
      type: object
      required: [userId, phone]
      properties:
        userId:
          type: integer
          format: int64
        phone:
          type: string
        nickName:
          type: string
        avatarOssId:
          type: integer
          format: int64
          nullable: true
        avatarUrl:
          type: string
          format: uri
          nullable: true
        sex:
          type: string
          nullable: true
        birthday:
          type: string
          format: date
          nullable: true
        provinceCode:
          type: string
          nullable: true
        cityCode:
          type: string
          nullable: true
        districtCode:
          type: string
          nullable: true
        addressDetail:
          type: string
          nullable: true
    LoginData:
      type: object
      required: [accessToken, userId, tenantId, clientId]
      properties:
        accessToken:
          type: string
        userId:
          type: integer
          format: int64
        tenantId:
          type: string
        clientId:
          type: string
    FileUpload:
      type: object
      required: [ossId, url, fileName, originalName]
      properties:
        ossId:
          type: integer
          format: int64
        url:
          type: string
          format: uri
        thumbnailUrl:
          type: string
          format: uri
          nullable: true
        fileName:
          type: string
        originalName:
          type: string
    Region:
      type: object
      required: [regionCode, regionName]
      properties:
        regionCode:
          type: string
        regionName:
          type: string
        parentCode:
          type: string
          nullable: true
        level:
          type: integer
          minimum: 0
    CaptchaRequirement:
      type: object
      required: [required, sceneCode]
      properties:
        required:
          type: boolean
        sceneCode:
          $ref: '#/components/schemas/CaptchaSceneCode'
        providerCode:
          type: string
          nullable: true
        captchaType:
          type: string
          nullable: true
    CaptchaChallengeRequest:
      type: object
      required: [tenantId, clientId, sceneCode]
      properties:
        tenantId:
          type: string
        clientId:
          type: string
        sceneCode:
          $ref: '#/components/schemas/CaptchaSceneCode'
        subject:
          type: string
    CaptchaChallenge:
      type: object
      required: [challengeId, providerCode, captchaType]
      properties:
        challengeId:
          type: string
        providerCode:
          type: string
        captchaType:
          type: string
        backgroundImage:
          type: string
          format: uri
          nullable: true
        templateImage:
          type: string
          format: uri
          nullable: true
        uuid:
          type: string
          nullable: true
        image:
          type: string
          nullable: true
    CaptchaVerifyRequest:
      type: object
      required: [tenantId, clientId, sceneCode, challengeId, providerCode, captchaType, payload]
      properties:
        tenantId:
          type: string
        clientId:
          type: string
        sceneCode:
          $ref: '#/components/schemas/CaptchaSceneCode'
        subject:
          type: string
        challengeId:
          type: string
        providerCode:
          type: string
        captchaType:
          type: string
        payload:
          oneOf:
            - $ref: '#/components/schemas/TianaiCaptchaPayload'
            - $ref: '#/components/schemas/SystemImageCaptchaPayload'
    TianaiCaptchaPayload:
      type: object
      required: [track]
      properties:
        track:
          type: object
          required: [trackList]
          properties:
            trackList:
              type: array
              items:
                type: object
                required: [x, y, t, type]
                properties:
                  x:
                    type: integer
                  y:
                    type: integer
                  t:
                    type: integer
                  type:
                    type: string
    SystemImageCaptchaPayload:
      type: object
      required: [uuid, code]
      properties:
        uuid:
          type: string
        code:
          type: string
    CaptchaVerify:
      type: object
      required: [validToken]
      properties:
        validToken:
          type: string
        expireAt:
          type: string
          format: date-time
          nullable: true
    VoidResponse:
      type: object
      required: [code, msg]
      properties:
        code:
          type: integer
          example: 200
        msg:
          type: string
        data:
          nullable: true
    LoginResponse:
      type: object
      required: [code, msg, data]
      properties:
        code:
          type: integer
        msg:
          type: string
        data:
          $ref: '#/components/schemas/LoginData'
    ProfileResponse:
      type: object
      required: [code, msg, data]
      properties:
        code:
          type: integer
        msg:
          type: string
        data:
          $ref: '#/components/schemas/Profile'
    FileUploadResponse:
      type: object
      required: [code, msg, data]
      properties:
        code:
          type: integer
        msg:
          type: string
        data:
          $ref: '#/components/schemas/FileUpload'
    RegionResponse:
      type: object
      required: [code, msg, data]
      properties:
        code:
          type: integer
        msg:
          type: string
        data:
          $ref: '#/components/schemas/Region'
    RegionListResponse:
      type: object
      required: [code, msg, data]
      properties:
        code:
          type: integer
        msg:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/Region'
    CaptchaRequirementResponse:
      type: object
      required: [code, msg, data]
      properties:
        code:
          type: integer
        msg:
          type: string
        data:
          $ref: '#/components/schemas/CaptchaRequirement'
    CaptchaChallengeResponse:
      type: object
      required: [code, msg, data]
      properties:
        code:
          type: integer
        msg:
          type: string
        data:
          $ref: '#/components/schemas/CaptchaChallenge'
    CaptchaVerifyResponse:
      type: object
      required: [code, msg, data]
      properties:
        code:
          type: integer
        msg:
          type: string
        data:
          $ref: '#/components/schemas/CaptchaVerify'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT