openapi: 3.0.3
info:
  title: 信用服务API
  version: 1.0.0
paths:
  /credits/auth:
    post:
      tags: [节点执行]
      operationId: CreateNodeExecution
      summary: 创建节点执行
      security:
        - userType:
            - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NodeExecutionCreateRequest"
      responses:
        "201":
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NodeExecutionResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"

    put:
      tags: [节点执行]
      operationId: UpdateNodeExecution
      summary: 更新节点执行
      security:
        - userType:
            - users
            - ms_users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NodeExecutionUpdateRequest"
      responses:
        "200":
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NodeExecutionResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"

  /credits/callback:
    post:
      tags: [节点执行]
      operationId: Callback
      summary: 回调
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CallbackRequest"
      responses:
        "200":
          description: 回调成功
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"

  /credits/realnames:
    get:
      tags: [实名信息]
      operationId: GetRealnameInfo
      summary: 获取实名信息
      security:
        - userType:
            - users
            - ms_users
      parameters:
        - name: userIds
          in: query
          required: true
          schema:
            type: array
            items:
              type: integer
        - name: expand
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - person
              x-enum-values:
                - person
              x-enum-varnames:
                - person
      responses:
        "200":
          description: 查询成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/BaseResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/RealNameResponseWrapper"
        "404":
          $ref: "#/components/responses/ErrorResponse"

  /credits/contracts:
    get:
      tags: [合同]
      operationId: GetContracts
      summary: 获取合同
      security:
        - userType:
            - users
            - ms_users
      parameters:
        - name: userId
          in: query
          schema:
            type: integer
        - name: record
          in: query
          required: true
          schema:
            type: string
        - name: recordId
          in: query
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"

components:
  schemas:
    BaseResponse:
      type: object
      properties:
        code:
          type: integer
          enum: [0]
          description: 响应代码（0表示成功）
        message:
          type: string
          description: 响应消息
        data:
          type: object
          description: 响应数据
      required: [code]

    EnabledStatus:
      type: integer
      enum: [0, 1]
      x-enum-varnames:
        - disabled
        - enabled
      description: |
        启用状态:
        0-禁用
        1-启用

    NodeExecutionStatus:
      type: string
      enum:
        [
          default,
          un_auth,
          auth_in_progress,
          willing_success,
          auth_success,
          auth_failed,
        ]
      description: |
        节点执行状态:
        default-默认
        un_auth-未认证
        auth_in_progress-认证中
        willing_success-意愿认证成功
        auth_success-认证成功
        auth_failed-认证失败

    AuthType:
      type: integer
      enum: [0, 1, 2, 3]
      x-enum-varnames:
        - none
        - person
        - company
        - operator
      description: |
        认证类型:
        0-无
        1-个人
        2-企业
        3-个人+企业

    PersonStatus:
      type: integer
      enum: [0, 1]
      x-enum-varnames:
        - not_passed
        - passed
      description: |
        个人状态:
        0-尚未通过
        1-通过

    AuthNode:
      type: object
      properties:
        id:
          type: integer
          description: ID
        authId:
          type: string
          description: 认证ID
        authUrl:
          type: string
          description: 认证URL
        sourceName:
          type: string
          description: 来源名称
        sourceId:
          type: integer
          description: 来源ID
        userId:
          type: integer
          description: 用户ID
        channelCode:
          $ref: "#/components/schemas/ChannelCode"
        nodeCode:
          $ref: "#/components/schemas/NodeCode"
        nodeEnabled:
          $ref: "#/components/schemas/EnabledStatus"
          description: 节点是否启用
        nodeStatus:
          $ref: "#/components/schemas/NodeExecutionStatus"
          description: 节点状态
        authTime:
          type: string
          format: date-time
          description: 认证时间
        payload:
          type: object
          description: 负载
        result:
          type: object
          description: 返回结果

    NodeExecutionCreateRequest:
      type: object
      required: [channelCode, sourceName, sourceId, userId]
      properties:
        channelCode:
          $ref: "#/components/schemas/ChannelCode"
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        sourceName:
          type: string
          description: 来源名称
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        sourceId:
          type: integer
          description: 来源ID
          x-oapi-codegen-extra-tags:
            binding: required
            validate: required
        userId:
          type: integer
          description: 用户ID

    NodeExecutionUpdateRequest:
      type: object
      allOf:
        - $ref: "#/components/schemas/NodeExecutionCreateRequest"
        - type: object
          required: [nodeCode, nodeStatus]
          properties:
            nodeCode:
              $ref: "#/components/schemas/NodeCode"
              x-oapi-codegen-extra-tags:
                binding: required
                validate: required
            nodeStatus:
              $ref: "#/components/schemas/NodeExecutionStatus"
              description: 节点状态
              x-oapi-codegen-extra-tags:
                binding: required
                validate: required

    ChannelCode:
      type: string
      description: 渠道编码
      enum:
        - free_deposit # 免押
        - pay_deposit # 押金
        - authentication # 认证

    NodeCode:
      type: string
      description: 节点编码
      enum:
        - default
        - realname
        - risk
        - willing
        - contract
        - transform
        - deposit

    NodeCodeDescriptions:
      type: object
      properties:
        default:
          type: string
          description: 默认
        realname:
          type: string
          description: 实名认证
        risk:
          type: string
          description: 风险认证
        willing:
          type: string
          description: 意愿认证
        contract:
          type: string
          description: 合同认证
        transform:
          type: string
          description: 转换认证
        deposit:
          type: string
          description: 押金支付

    NodeExecutionResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - type: object
          properties:
            data:
              type: array
              items:
                type: object
                $ref: "#/components/schemas/AuthNode"

    VerificationStatus:
      type: integer
      description: 实名认证状态
      enum: [0, 1]
      x-enum-varnames:
        - not_verified
        - verified

    RealNameResponseWrapper:
      type: object
      properties:
        list:
          type: array
          items:
            $ref: "#/components/schemas/RealNameResponse"

    RealNameResponse:
      type: object
      properties:
        id:
          type: integer
        userId:
          type: integer
          description: 用户ID
        personId:
          type: integer
          description: 个人实人信息ID
        personQualifiedTime:
          type: string
          format: date-time
          description: 个人认证时间
        companyId:
          type: integer
          description: 公司实人信息ID
        operatorId:
          type: integer
          description: 操作人ID
        companyQualifiedTime:
          type: string
          format: date-time
          description: 企业创建时间
        authType:
          $ref: "#/components/schemas/AuthType"
          description: 认证类型
        realName:
          type: string
          description: 实名
        authorizeImg:
          type: string
          description: 授权书URL
        channelId:
          type: integer
          description: 渠道ID
        email:
          type: string
          description: 邮箱
        person:
          type: object
          description: 个人实人信息（expand=person时返回）
          $ref: "#/components/schemas/RealPerson"
        verificationStatus:
          $ref: "#/components/schemas/VerificationStatus"

    RealPerson:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: 个人姓名
        idCard:
          type: string
          description: 个人身份证
        mobile:
          type: string
          description: 个人手机号
        bankCardNo:
          type: string
          description: 个人银行卡号
        idcardFrontImg:
          type: string
          description: 个人身份证正面URL
        idcardBackImg:
          type: string
          description: 个人身份证背面URL
        status:
          $ref: "#/components/schemas/PersonStatus"
          description: 状态
        approvalTime:
          type: string
          format: date-time
          description: 通过时间
        idcardImg:
          type: string
          description: 个人身份证正反面
        createdAt:
          type: string
          format: date-time
          description: 创建时间
        updatedAt:
          type: string
          format: date-time
          description: 更新时间

    ContractResponse:
      type: object
      required:
        [id, userId, type, record, recordId, authId, status, contractUrl]
      properties:
        id:
          type: integer
          description: 合同ID
        userId:
          type: integer
          description: 用户ID
        type:
          type: integer
          description: 合同类型
        record:
          type: string
          description: 合同记录
        recordId:
          type: integer
          description: 合同记录ID
        authId:
          type: string
          description: 认证ID
        status:
          type: integer
          description: 合同状态
        signTime:
          type: string
          format: date-time
          description: 签署时间
        contractUrl:
          type: string
          description: 合同URL

    CallbackRequest:
      type: object
      required: [authId]
      properties:
        authId:
          type: string
          description: 认证ID

  securitySchemes:
    userType:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 用户类型认证
      x-scopes:
        - ms_users
        - users

  parameters:
    page:
      name: page
      in: query
      schema:
        type: integer
        default: 1
      description: 页码
    pageSize:
      name: pageSize
      in: query
      schema:
        type: integer
        default: 20
      description: 每页数量

  responses:
    ErrorResponse:
      description: 错误响应
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                description: 错误代码
              message:
                type: string
                description: 错误信息
              data:
                type: object
                nullable: true
                description: 错误数据
