# docs/openapi/custom-fields.yaml
openapi: 3.0.3
info:
  title: Custom Fields (Campos Personalizados)
  version: v1.0.0
  description: Endpoints RPC usados no Admin para gerir campos personalizados por contrato.
servers:
  - url: /adm/api
tags:
  - name: CustomFields
    description: Gestão de campos personalizados por contrato

paths:
  /CustomFields/list:
    post:
      tags: [CustomFields]
      summary: Listar campos personalizados
      description: Retorna os campos do contrato (com filtros opcionais).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id_contrato:
                  type: integer
                  description: ID do contrato (tenant). Se omitido/0, lista tudo (somente super admin).
                  example: 57
                q:
                  type: string
                  description: Busca por nome/tipo.
                  example: "cpf"
                is_visible:
                  type: integer
                  nullable: true
                  description: "Filtro visível (1/0)."
                  example: 1
                export:
                  type: integer
                  nullable: true
                  description: "Filtro exportável (1/0)."
                  example: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  __status: { type: integer, example: 200 }
                  ok: { type: integer, example: 1 }
                  data:
                    type: object
                    properties:
                      rows:
                        type: array
                        items:
                          $ref: "#/components/schemas/CustomFieldRow"
                      total:
                        type: integer
                        example: 12

  /CustomFields/get:
    post:
      tags: [CustomFields]
      summary: Obter campo por ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: integer, example: 12 }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  __status: { type: integer, example: 200 }
                  ok: { type: integer, example: 1 }
                  data:
                    $ref: "#/components/schemas/CustomFieldRow"
        "404":
          description: Não encontrado

  /CustomFields/save:
    post:
      tags: [CustomFields]
      summary: Criar/editar campo
      description: Cria (sem id) ou atualiza (com id). Para checkbox/radio/select, options é obrigatório.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomFieldSaveRequest"
      responses:
        "200":
          description: OK (atualização)
          content:
            application/json:
              schema:
                type: object
                properties:
                  __status: { type: integer, example: 200 }
                  ok: { type: integer, example: 1 }
                  id: { type: integer, example: 12 }
        "201":
          description: Created (criação)
          content:
            application/json:
              schema:
                type: object
                properties:
                  __status: { type: integer, example: 201 }
                  ok: { type: integer, example: 1 }
                  id: { type: integer, example: 13 }
        "409":
          description: Conflito (nome duplicado no contrato)
        "422":
          description: Validação

  /CustomFields/delete:
    post:
      tags: [CustomFields]
      summary: Excluir campo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: integer, example: 12 }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  __status: { type: integer, example: 200 }
                  ok: { type: integer, example: 1 }

components:
  schemas:
    CustomFieldRow:
      type: object
      properties:
        id: { type: integer, example: 12 }
        contrato: { type: integer, example: 57 }
        field_name: { type: string, example: "CPF do Responsável" }
        field_type:
          type: string
          enum: [text, textarea, checkbox, radio, select]
          example: "text"
        options:
          type: string
          nullable: true
          description: Opções concatenadas por "|" (pipe). Ex.: "A|B|C"
          example: "A|B|C"
        is_required: { type: integer, example: 1 }
        is_visible: { type: integer, example: 1 }
        export: { type: integer, example: 1 }
        created_at: { type: string, example: "2026-02-26 10:00:00" }
        updated_at: { type: string, example: "2026-02-26 10:10:00" }

    CustomFieldSaveRequest:
      type: object
      required: [id_contrato, field_name, field_type]
      properties:
        id:
          type: integer
          description: Se informado, atualiza.
          example: 12
        id_contrato:
          type: integer
          example: 57
        field_name:
          type: string
          example: "CPF do Responsável"
        field_type:
          type: string
          enum: [text, textarea, checkbox, radio, select]
          example: "text"
        options:
          oneOf:
            - type: array
              items: { type: string }
              example: ["Opção 1", "Opção 2"]
            - type: string
              example: "Opção 1|Opção 2"
          description: Obrigatório para checkbox/radio/select.
        is_required:
          type: integer
          description: 1 obrigatório / 0 não
          example: 1
        is_visible:
          type: integer
          description: 1 visível / 0 oculto
          example: 1
        export:
          type: integer
          description: 1 exportável / 0 não
          example: 1