{
  "ok": true,
  "response_contract": "diet_ai_entrypoint_v1",
  "auth_mode": "public_ai",
  "primeiro_caminho": "/api/dieta/ia",
  "public_base_urls": {
    "preferencial": "https://api.harxy.com.br",
    "fallback_raiz": "https://harxy.com.br",
    "legado_fly": "https://fluence-portal-2926.fly.dev",
    "observacao": "Use api.harxy.com.br como principal. Se o executor do ChatGPT nao resolver o subdominio, tente harxy.com.br com o mesmo caminho."
  },
  "chatgpt_runtime_notes": {
    "status": "Alguns ambientes do ChatGPT conseguem ler este indice pela ferramenta web, mas o executor de POST pode falhar por DNS antes de chegar na API.",
    "erros_observados": [
      "curl: (6) Could not resolve host: api.harxy.com.br",
      "Python socket.gaierror [Errno -3] Temporary failure in name resolution"
    ],
    "diagnostico": "Se GET funcionar via navegador/web e POST falhar no executor com erro de DNS, trate como limitacao do runtime do ChatGPT, nao como erro de permissao nem de contrato.",
    "endpoints_absolutos_preferidos": {
      "principal": "https://api.harxy.com.br",
      "fallback_raiz": "https://harxy.com.br",
      "legado_fly": "https://fluence-portal-2926.fly.dev"
    },
    "ordem_de_tentativa": [
      "1. Leia https://api.harxy.com.br/api/dieta/ia.",
      "2. Teste POST https://api.harxy.com.br/api/dieta/ia/ping-write.",
      "3. Se o executor nao resolver api.harxy.com.br, tente o mesmo caminho em https://harxy.com.br.",
      "4. Se POST direto falhar mas algum POST funcionar, use /api/chatgpt/dieta/proxy com method, path e body.",
      "5. Se nenhum POST sair do runtime, nao invente sucesso: entregue payload validado, comando e explique que a chamada nao chegou por DNS."
    ],
    "regra_para_falar_com_raissa": "Diga claramente se voce executou a chamada ou se apenas montou o payload. Nunca declare gravacao real sem applied=true, persisted=true e requires_confirmation=false.",
    "regra_combo_importante": "Nao use flags nem diet_compatibility como lista. Use diet_normal/diet_vegetarian/diet_vegan no nivel do combo e diet_compatibility como objeto com permitido_em/ajuste_em/bloqueado_em/cautela_em.",
    "exemplo_combo_valido": {
      "schema": "fluence-meal-combos/v1",
      "nome": "Catalogo exemplo Harxy IA",
      "macro_precision": "estimado_taco_tbca",
      "modo_ativo": "combo_de_refeicao",
      "combos": [
        {
          "combo_id": "ia_exemplo_cafe_ovos_fruta_001",
          "nome": "Cafe da manha exemplo - ovos e fruta",
          "meal_keys": [
            "breakfast"
          ],
          "perfil_macro": "proteico",
          "combo_family": "exemplo_ia",
          "main_carb_family": "fruta",
          "main_protein_family": "ovo",
          "frequency_recommendation": "moderado",
          "cultural_coherence": "alta",
          "tags": [
            "exemplo_ia",
            "harxy"
          ],
          "itens": [
            {
              "item_id": "ovos_mexidos",
              "nome": "Ovos mexidos",
              "quantidade": 2,
              "unidade": "unidade",
              "peso_estimado_g": 100,
              "grupo": "proteina",
              "macros_estimados": {
                "kcal": 143,
                "proteina_g": 13,
                "carboidrato_g": 1,
                "gordura_g": 10
              }
            },
            {
              "item_id": "banana_prata",
              "nome": "Banana prata",
              "quantidade": 1,
              "unidade": "unidade",
              "peso_estimado_g": 70,
              "grupo": "fruta",
              "macros_estimados": {
                "kcal": 62,
                "proteina_g": 0.9,
                "carboidrato_g": 16,
                "gordura_g": 0.1
              }
            }
          ],
          "macros_estimados": {
            "kcal": 205,
            "proteina_g": 13.9,
            "carboidrato_g": 17,
            "gordura_g": 10.1
          },
          "diet_normal": true,
          "diet_vegetarian": false,
          "diet_vegan": false,
          "diet_compatibility": {
            "permitido_em": [
              "padrao"
            ],
            "ajuste_em": [],
            "bloqueado_em": [],
            "cautela_em": []
          },
          "observacao_clinica": "Exemplo tecnico para validar o contrato; revisar clinicamente antes de usar em paciente real."
        }
      ]
    }
  },
  "objetivo": "Guia raiz para a IA da Raissa conversar com o Harxy sobre combos, cálculo de dieta, criação de plano alimentar e entrega de PDF no chat.",
  "contexto_amplo": {
    "sistema": "Harxy - plataforma SaaS de saúde/nutrição. A Clínica Fluence é o primeiro cliente/piloto operacional e usa o motor de plano alimentar com catálogo oficial de combos por tenant.",
    "tenant_scope": "Todas as leituras e gravações das rotas IA respeitam o tenant padrão ou X-Fluence-Tenant-Id quando informado.",
    "seguranca_atual": "Exceção operacional temporária: somente os endpoints /api/dieta/ia/*, /api/dieta/combos/ia/* e /api/chatgpt/dieta/proxy aceitam leitura e escrita sem token. O restante do Portal continua exigindo sessão.",
    "regra_clinica": "A IA apoia criação e revisão operacional. A validação clínica final continua com a equipe Fluence."
  },
  "autonomia_operacional": {
    "resumo": "A IA pode alimentar a base Harxy da Clínica Fluence dentro dos endpoints expostos neste índice.",
    "pode_cadastrar": [
      "paciente",
      "combo alimentar",
      "plano alimentar"
    ],
    "pode_testar": [
      "preview de paciente",
      "validação de combo",
      "simulação de metas",
      "prévia de plano alimentar",
      "geração de PDF por job",
      "respostas de erro"
    ],
    "pode_ler": [
      "pacientes cadastrados pela busca",
      "combos existentes",
      "contrato do motor de cálculo",
      "status e artefatos de PDF",
      "erros possíveis",
      "regras e listas operacionais"
    ],
    "limite_clinico": "A autonomia é operacional e técnica; decisões clínicas finais continuam exigindo revisão humana da equipe da Clínica Fluence.",
    "regra_de_gravacao": "Nunca assuma que gravou apenas porque simulou. Confira applied, persisted e requires_confirmation em cada resposta."
  },
  "primeira_resposta_para_raissa": {
    "instrucao_para_ia": "Assim que ler este índice, antes de executar novas chamadas, responda para a Raissa dizendo que está ciente do acesso ao Harxy no contexto da Clínica Fluence e liste sua autonomia operacional.",
    "mensagem_sugerida": [
      "Raissa, estou ciente do contexto do Harxy para a Clínica Fluence e dos endpoints disponíveis.",
      "Tenho autonomia operacional para ler combos e pacientes, validar e gravar combos, cadastrar paciente, simular metas, criar prévias de plano alimentar, gravar plano alimentar quando houver confirmação, pedir PDF do plano para o chat e criticar inconsistências técnicas ou clínicas para revisão humana.",
      "Vou diferenciar claramente o que foi apenas prévia do que foi realmente gravado."
    ],
    "autonomia_para_listar": [
      "Ler este índice e o contexto completo do motor de cálculo.",
      "Ler combos existentes e exportações do catálogo oficial.",
      "Buscar pacientes cadastrados por nome ou CPF.",
      "Validar cadastro de paciente e gravar paciente quando confirmar_criacao for true.",
      "Validar JSON de combos, apontar erros estruturais e gravar combos quando confirmar_importacao for true.",
      "Simular metas de dieta sem gravar dados.",
      "Criar prévia de plano alimentar e gravar plano quando confirmar_criacao for true.",
      "Pedir PDF do plano alimentar com gerar_pdf: true, acompanhar status_url e baixar pdf_download_url quando o job ficar pronto.",
      "Testar entradas ruins e explicar mensagens de erro, bloqueios e próximos passos.",
      "Criticar combos, metas e planos incoerentes antes de pedir confirmação."
    ],
    "limite_para_declarar": "Deixe claro para a Raissa que esta é autonomia operacional do sistema; a validação clínica final continua com a equipe da Clínica Fluence."
  },
  "avaliacao_critica": {
    "postura": "Seja exigente. Aponte inconsistências antes de gravar e use os endpoints para testar hipóteses.",
    "criticar_se": [
      "paciente incompleto, CPF inválido ou data incoerente",
      "combo com meal_keys erradas, macros ausentes, compatibilidade confusa ou refeição culturalmente fraca",
      "plano com objetivo, refeições, proteína ou carboidrato incompatíveis",
      "motor retornar bloqueios metabólicos, alertas, partial true ou catálogo indisponível",
      "qualquer resposta vier sem ok/valid/feedback ou sem próximo passo claro"
    ],
    "resposta_esperada_da_ia": "Diga o que testou, o que gravou, o que ficou só em prévia, quais erros encontrou e qual correção recomenda."
  },
  "listas_rapidas": {
    "refeicoes_do_dia": [
      {
        "id": "breakfast",
        "label": "Café",
        "canonical_label": "Café da manhã",
        "motor_meal_id": "breakfast",
        "combo_meal_key": "breakfast"
      },
      {
        "id": "morning_snack",
        "label": "Lanche manhã",
        "canonical_label": "Lanche manhã",
        "motor_meal_id": "morning_snack",
        "combo_meal_key": "snack"
      },
      {
        "id": "lunch",
        "label": "Almoço",
        "canonical_label": "Almoço",
        "motor_meal_id": "lunch",
        "combo_meal_key": "lunch"
      },
      {
        "id": "afternoon_snack",
        "label": "Lanche tarde",
        "canonical_label": "Lanche tarde",
        "motor_meal_id": "afternoon_snack",
        "combo_meal_key": "snack"
      },
      {
        "id": "dinner",
        "label": "Jantar",
        "canonical_label": "Jantar",
        "motor_meal_id": "dinner",
        "combo_meal_key": "dinner"
      },
      {
        "id": "supper",
        "label": "Ceia",
        "canonical_label": "Ceia",
        "motor_meal_id": "supper",
        "combo_meal_key": "supper"
      },
      {
        "id": "pre_workout",
        "label": "Pré treino",
        "canonical_label": "Pré-treino",
        "motor_meal_id": "pre_workout",
        "combo_meal_key": "pre_workout"
      },
      {
        "id": "post_workout",
        "label": "Pós treino",
        "canonical_label": "Pós-treino",
        "motor_meal_id": "post_workout",
        "combo_meal_key": "post_workout"
      }
    ],
    "restricoes": [
      {
        "id": "sem_lactose",
        "label": "Sem lactose",
        "input_value": "sem lactose",
        "combo_flag": "lactose_free"
      },
      {
        "id": "sem_gluten",
        "label": "Sem glúten",
        "input_value": "sem glúten",
        "combo_flag": "gluten_free"
      },
      {
        "id": "low_fodmap",
        "label": "Low FODMAP",
        "input_value": "low fodmap",
        "combo_flag": "low_fodmap"
      }
    ],
    "tipos_de_dieta": [
      {
        "id": "normal",
        "label": "Normal",
        "input_values": [
          "Normal",
          "Dieta Padrão Fluence"
        ],
        "combo_flag": "diet_normal"
      },
      {
        "id": "vegetariana",
        "label": "Vegetariana",
        "input_values": [
          "Vegetariana"
        ],
        "combo_flag": "diet_vegetarian"
      },
      {
        "id": "vegana",
        "label": "Vegana",
        "input_values": [
          "Vegana"
        ],
        "combo_flag": "diet_vegan"
      }
    ],
    "objetivos": [
      {
        "id": "emagrecimento",
        "label": "Emagrecimento",
        "input_value": "emagrecimento"
      },
      {
        "id": "recomposicao_corporal",
        "label": "Recomposição corporal",
        "input_value": "recomposição corporal"
      },
      {
        "id": "manutencao",
        "label": "Manutenção",
        "input_value": "manutenção"
      },
      {
        "id": "ganho_massa",
        "label": "Ganho de massa",
        "input_value": "ganho de massa"
      }
    ],
    "proteina_alvo": [
      {
        "id": "auto",
        "label": "Automática",
        "input_fields": {
          "proteina_modo": "auto"
        }
      },
      {
        "id": "gkg_manual",
        "label": "g/kg manual",
        "input_fields": {
          "proteina_modo": "gkg",
          "proteina_gkg": "número em g/kg"
        }
      }
    ],
    "carboidrato_alvo": [
      {
        "id": "auto",
        "label": "Automático",
        "input_fields": {
          "carboidrato_modo": "auto"
        }
      },
      {
        "id": "percentual_manual",
        "label": "% manual",
        "input_fields": {
          "carboidrato_modo": "percentual",
          "carboidrato_percentual": "número percentual"
        }
      }
    ],
    "compatibilidades": [
      {
        "id": "padrao",
        "label": "Normal"
      },
      {
        "id": "aaa",
        "label": "Alto Padrão"
      },
      {
        "id": "emagrecimento",
        "label": "Emagrecimento"
      },
      {
        "id": "manutencao",
        "label": "Manutenção"
      },
      {
        "id": "ganho_massa",
        "label": "Ganho de massa"
      },
      {
        "id": "recomposicao_corporal",
        "label": "Recomposição corporal"
      },
      {
        "id": "jejum_intermitente",
        "label": "Jejum intermitente"
      },
      {
        "id": "low_fodmap",
        "label": "Low FODMAP"
      },
      {
        "id": "low_carb",
        "label": "Low carb"
      },
      {
        "id": "cetogenica",
        "label": "Cetogênica"
      },
      {
        "id": "mediterranea",
        "label": "Mediterrânea"
      },
      {
        "id": "dash",
        "label": "DASH"
      },
      {
        "id": "vegana",
        "label": "Vegana"
      },
      {
        "id": "vegetariana",
        "label": "Vegetariana"
      },
      {
        "id": "sem_lactose",
        "label": "Sem lactose"
      },
      {
        "id": "sem_gluten",
        "label": "Sem glúten"
      },
      {
        "id": "crohn_retocolite_remissao",
        "label": "Crohn/retocolite em remissão"
      },
      {
        "id": "dii_atividade",
        "label": "DII em atividade"
      },
      {
        "id": "industrializados_praticos",
        "label": "Industrializados práticos"
      },
      {
        "id": "tdah_autismo",
        "label": "TDAH/autismo"
      },
      {
        "id": "endometriose",
        "label": "Endometriose"
      }
    ]
  },
  "autenticacao": {
    "current_mode": "public_ai",
    "indice_publico": "GET /api/dieta/ia é público e apresenta todos os caminhos liberados para a IA.",
    "accepted": [
      "sem token nas rotas IA publicadas neste índice",
      "sessão Harxy/Fluence autenticada opcional"
    ],
    "tenant_header_opcional": "X-Fluence-Tenant-Id",
    "sem_token": "Sem token, a IA pode usar as rotas deste índice para ler e escrever paciente, plano alimentar e combo. Endpoints comuns fora de /api/dieta/ia/*, /api/dieta/combos/ia/* e /api/chatgpt/dieta/proxy continuam protegidos."
  },
  "endpoints": {
    "guia": "/api/dieta/ia",
    "ping_write": "/api/dieta/ia/ping-write",
    "chatgpt_proxy": "/api/chatgpt/dieta/proxy",
    "listar_pacientes": "/api/dieta/ia/pacientes?q=<nome ou cpf>",
    "contexto_calculo": "/api/dieta/ia/contexto-calculo",
    "criar_paciente": "/api/dieta/ia/criar-paciente",
    "simular": "/api/dieta/ia/simular",
    "criar_plano": "/api/dieta/ia/criar-plano",
    "criar_plano_com_pdf": "/api/dieta/ia/criar-plano",
    "listar_planos": "/api/dieta/ia/planos?cpf=<cpf opcional>",
    "detalhe_plano_ia": "/api/dieta/ia/planos/detalhe?arquivo=<arquivo>",
    "status_pdf_plano": "/api/dieta/ia/pdf/jobs/<job_id>",
    "artefatos_pdf_plano": "/api/dieta/ia/pdf/jobs/<job_id>/artifact",
    "baixar_pdf_plano": "/api/dieta/ia/pdf/jobs/<job_id>/artifact/pdf/download",
    "contexto_combos": "/api/dieta/combos/ia/contexto",
    "validar_combos": "/api/dieta/combos/ia/validar",
    "gravar_combos": "/api/dieta/combos/ia/upsert",
    "listar_combos_site": "/api/dieta/combos/ia/contexto",
    "exportar_combos_json": "/api/dieta/combos/ia/contexto?include_full=1",
    "importar_combos_json_site": "/api/dieta/combos/ia/upsert",
    "detalhe_plano_salvo": "/api/dieta/ia/planos/detalhe?arquivo=<arquivo>"
  },
  "diagnostico_chatgpt": {
    "ping_write": {
      "endpoint": "/api/dieta/ia/ping-write",
      "method": "POST",
      "body": {
        "origem": "chatgpt",
        "teste": true
      },
      "resposta_esperada": {
        "ok": true,
        "operation": "ping_write",
        "applied": true,
        "persisted": true,
        "requires_confirmation": false
      }
    },
    "proxy": {
      "endpoint": "/api/chatgpt/dieta/proxy",
      "method": "POST",
      "uso": "Use quando seu ambiente conseguir ler o índice, mas falhar em POST direto por DNS, CORS ou runtime. O Harxy chama a rota real internamente sem depender do DNS externo.",
      "allowed_paths": [
        "/api/dieta/ia",
        "/api/dieta/ia/*",
        "/api/dieta/combos/ia/*"
      ],
      "exemplos": {
        "ler_indice": {
          "method": "GET",
          "path": "/api/dieta/ia"
        },
        "validar_combo": {
          "method": "POST",
          "path": "/api/dieta/combos/ia/validar",
          "body": {
            "base_combo": {
              "schema": "fluence-meal-combos/v1",
              "nome": "Catalogo exemplo Harxy IA",
              "macro_precision": "estimado_taco_tbca",
              "modo_ativo": "combo_de_refeicao",
              "combos": [
                {
                  "combo_id": "ia_exemplo_cafe_ovos_fruta_001",
                  "nome": "Cafe da manha exemplo - ovos e fruta",
                  "meal_keys": [
                    "breakfast"
                  ],
                  "perfil_macro": "proteico",
                  "combo_family": "exemplo_ia",
                  "main_carb_family": "fruta",
                  "main_protein_family": "ovo",
                  "frequency_recommendation": "moderado",
                  "cultural_coherence": "alta",
                  "tags": [
                    "exemplo_ia",
                    "harxy"
                  ],
                  "itens": [
                    {
                      "item_id": "ovos_mexidos",
                      "nome": "Ovos mexidos",
                      "quantidade": 2,
                      "unidade": "unidade",
                      "peso_estimado_g": 100,
                      "grupo": "proteina",
                      "macros_estimados": {
                        "kcal": 143,
                        "proteina_g": 13,
                        "carboidrato_g": 1,
                        "gordura_g": 10
                      }
                    },
                    {
                      "item_id": "banana_prata",
                      "nome": "Banana prata",
                      "quantidade": 1,
                      "unidade": "unidade",
                      "peso_estimado_g": 70,
                      "grupo": "fruta",
                      "macros_estimados": {
                        "kcal": 62,
                        "proteina_g": 0.9,
                        "carboidrato_g": 16,
                        "gordura_g": 0.1
                      }
                    }
                  ],
                  "macros_estimados": {
                    "kcal": 205,
                    "proteina_g": 13.9,
                    "carboidrato_g": 17,
                    "gordura_g": 10.1
                  },
                  "diet_normal": true,
                  "diet_vegetarian": false,
                  "diet_vegan": false,
                  "diet_compatibility": {
                    "permitido_em": [
                      "padrao"
                    ],
                    "ajuste_em": [],
                    "bloqueado_em": [],
                    "cautela_em": []
                  },
                  "observacao_clinica": "Exemplo tecnico para validar o contrato; revisar clinicamente antes de usar em paciente real."
                }
              ]
            }
          }
        },
        "gravar_combo": {
          "method": "POST",
          "path": "/api/dieta/combos/ia/upsert",
          "body": {
            "base_combo": {
              "schema": "fluence-meal-combos/v1",
              "nome": "Catalogo exemplo Harxy IA",
              "macro_precision": "estimado_taco_tbca",
              "modo_ativo": "combo_de_refeicao",
              "combos": [
                {
                  "combo_id": "ia_exemplo_cafe_ovos_fruta_001",
                  "nome": "Cafe da manha exemplo - ovos e fruta",
                  "meal_keys": [
                    "breakfast"
                  ],
                  "perfil_macro": "proteico",
                  "combo_family": "exemplo_ia",
                  "main_carb_family": "fruta",
                  "main_protein_family": "ovo",
                  "frequency_recommendation": "moderado",
                  "cultural_coherence": "alta",
                  "tags": [
                    "exemplo_ia",
                    "harxy"
                  ],
                  "itens": [
                    {
                      "item_id": "ovos_mexidos",
                      "nome": "Ovos mexidos",
                      "quantidade": 2,
                      "unidade": "unidade",
                      "peso_estimado_g": 100,
                      "grupo": "proteina",
                      "macros_estimados": {
                        "kcal": 143,
                        "proteina_g": 13,
                        "carboidrato_g": 1,
                        "gordura_g": 10
                      }
                    },
                    {
                      "item_id": "banana_prata",
                      "nome": "Banana prata",
                      "quantidade": 1,
                      "unidade": "unidade",
                      "peso_estimado_g": 70,
                      "grupo": "fruta",
                      "macros_estimados": {
                        "kcal": 62,
                        "proteina_g": 0.9,
                        "carboidrato_g": 16,
                        "gordura_g": 0.1
                      }
                    }
                  ],
                  "macros_estimados": {
                    "kcal": 205,
                    "proteina_g": 13.9,
                    "carboidrato_g": 17,
                    "gordura_g": 10.1
                  },
                  "diet_normal": true,
                  "diet_vegetarian": false,
                  "diet_vegan": false,
                  "diet_compatibility": {
                    "permitido_em": [
                      "padrao"
                    ],
                    "ajuste_em": [],
                    "bloqueado_em": [],
                    "cautela_em": []
                  },
                  "observacao_clinica": "Exemplo tecnico para validar o contrato; revisar clinicamente antes de usar em paciente real."
                }
              ]
            },
            "confirmar_importacao": true
          }
        },
        "criar_paciente": {
          "method": "POST",
          "path": "/api/dieta/ia/criar-paciente",
          "body": {
            "paciente": {
              "nome": "Paciente exemplo IA",
              "cpf": "12345678909",
              "data_nascimento": "1990-05-20",
              "sexo": "Feminino"
            },
            "confirmar_criacao": false
          }
        },
        "criar_plano_com_pdf": {
          "method": "POST",
          "path": "/api/dieta/ia/criar-plano",
          "body": {
            "dados": {
              "paciente": "Paciente exemplo IA",
              "kcal": 1800,
              "peso": 70,
              "altura": 165,
              "objetivo": "emagrecimento",
              "padrao_alimentar": "Dieta Padrão Fluence",
              "tipo_dieta_filtro": "Normal",
              "refeicoes": 4,
              "proteina_modo": "auto",
              "carboidrato_modo": "auto",
              "restricoes": [],
              "compatibilidade_dietas": [
                "padrao"
              ],
              "cpf": "12345678909"
            },
            "confirmar_criacao": false,
            "gerar_pdf": true
          }
        }
      },
      "resposta_padrao": {
        "ok": true,
        "operation": "chatgpt_proxy",
        "applied": false,
        "persisted": false,
        "requires_confirmation": false,
        "message": "Resposta da rota IA retornada pelo proxy.",
        "target": {
          "method": "POST",
          "path": "/api/dieta/combos/ia/validar",
          "status_code": 200
        },
        "data": {}
      }
    }
  },
  "fluxo_recomendado": [
    "1. Comece sempre por GET /api/dieta/ia.",
    "2. Teste escrita mínima com POST /api/dieta/ia/ping-write. Se o POST direto falhar no seu ambiente, use POST /api/chatgpt/dieta/proxy.",
    "3. Leia GET /api/dieta/ia/contexto-calculo para entender listas, campos, metas, refeições, restrições, objetivos e compatibilidades.",
    "4. Leia GET /api/dieta/combos/ia/contexto para conhecer os combos existentes; use ?limit=, ?q=, ?meal_key=, ?combo_id= e ?include_full=1 quando precisar.",
    "5. Se o paciente ainda não existir, valide/crie por POST /api/dieta/ia/criar-paciente.",
    "6. Simule metas em POST /api/dieta/ia/simular com modo meta antes de pedir plano completo.",
    "7. Para novos combos, envie BaseCombo em POST /api/dieta/combos/ia/validar; depois use /upsert sem confirmação para prévia.",
    "8. Grave combos somente reenviando para /api/dieta/combos/ia/upsert com confirmar_importacao: true.",
    "9. Crie plano alimentar por POST /api/dieta/ia/criar-plano; sem confirmar_criacao ele só calcula prévia.",
    "10. Grave plano alimentar reenviando com confirmar_criacao: true; se precisar do PDF no chat, inclua gerar_pdf: true.",
    "11. Quando a resposta trouxer pdf_chat, consulte status_url até job.status ser succeeded e então use pdf_download_url para baixar o PDF."
  ],
  "pode_ler": {
    "logica_calculo": "/api/dieta/ia/contexto-calculo",
    "pacientes_cadastrados": "/api/dieta/ia/pacientes?q=<nome ou cpf>",
    "combos_existentes": "/api/dieta/combos/ia/contexto",
    "combos_site": "/api/dieta/combos/ia/contexto",
    "combos_export_json": "/api/dieta/combos/ia/contexto?include_full=1",
    "planos_salvos": "/api/dieta/ia/planos?cpf=<cpf opcional>",
    "plano_salvo_por_arquivo": "/api/dieta/ia/planos/detalhe?arquivo=<arquivo>",
    "status_pdf_plano": "/api/dieta/ia/pdf/jobs/<job_id>",
    "artefatos_pdf_plano": "/api/dieta/ia/pdf/jobs/<job_id>/artifact",
    "baixar_pdf_plano": "/api/dieta/ia/pdf/jobs/<job_id>/artifact/pdf/download"
  },
  "pode_gravar": {
    "paciente": {
      "endpoint": "/api/dieta/ia/criar-paciente",
      "method": "POST",
      "response_contract": "diet_ai_create_patient_v1",
      "storage": "PortalPaciente/data/pacientes/pacientes.json",
      "visibility_after_write": "GET /api/dieta/ia/pacientes?q=<nome ou cpf>",
      "default_behavior": "preview_only",
      "apply_flag": "confirmar_criacao: true",
      "required_payload": {
        "paciente": "Objeto com nome, cpf, data_nascimento em YYYY-MM-DD e sexo.",
        "confirmar_criacao": "true somente depois de revisar a prévia."
      }
    },
    "plano_alimentar": {
      "endpoint": "/api/dieta/ia/criar-plano",
      "method": "POST",
      "response_contract": "diet_calculation_ai_create_plan_v1",
      "storage": "PortalPaciente/data/dietas/rascunhos/<timestamp>_<cpf>_<id>.json",
      "visibility_after_write": "detalhe_url em /api/resultados/detalhe?tipo=dieta&arquivo=<arquivo>",
      "pdf_chat": {
        "request_flag": "gerar_pdf: true",
        "delivery": "A resposta confirmada retorna pdf_chat com job_id, status_url, artifact_url e pdf_download_url.",
        "polling": "A IA deve consultar status_url até o job ficar succeeded; antes disso o download pode retornar 409.",
        "auth": "Nas rotas IA públicas, status e download do PDF não exigem token. Use os caminhos /api/dieta/ia/pdf/jobs/* retornados em pdf_chat."
      },
      "default_behavior": "preview_only",
      "apply_flag": "confirmar_criacao: true",
      "required_payload": {
        "dados": "Objeto com cpf, paciente, kcal, peso, objetivo, tipo_dieta_filtro, refeicoes e campos opcionais do motor.",
        "paciente_contexto": "Opcional, mas recomendado para nome, CPF, sexo, data de nascimento e tenant.",
        "confirmar_criacao": "true somente quando a prévia estiver revisada.",
        "gerar_pdf": "true quando o ChatGPT da Raissa precisar receber o PDF gerado no chat."
      }
    },
    "combos": {
      "endpoint": "/api/dieta/combos/ia/upsert",
      "validation_endpoint": "/api/dieta/combos/ia/validar",
      "method": "POST",
      "response_contract": "combo_ai_upsert_v1",
      "strict_contract": "fluence-meal-combos/v1",
      "storage": "Catálogo PostgreSQL oficial do tenant em diet_combo_catalog",
      "strong_key": "combo_id",
      "default_behavior": "preview_only",
      "apply_flag": "confirmar_importacao: true",
      "required_payload": {
        "base_combo": "Objeto BaseCombo completo ou campo conteudo com JSON do contrato fluence-meal-combos/v1.",
        "confirmar_importacao": "true somente depois de validar e revisar a prévia."
      }
    }
  },
  "contratos_de_payload": {
    "simular_meta": {
      "endpoint": "/api/dieta/ia/simular",
      "exemplo_minimo": {
        "modo": "meta",
        "dados": {
          "paciente": "Paciente exemplo IA",
          "kcal": 1800,
          "peso": 70,
          "altura": 165,
          "objetivo": "emagrecimento",
          "padrao_alimentar": "Dieta Padrão Fluence",
          "tipo_dieta_filtro": "Normal",
          "refeicoes": 4,
          "proteina_modo": "auto",
          "carboidrato_modo": "auto",
          "restricoes": [],
          "compatibilidade_dietas": [
            "padrao"
          ]
        }
      },
      "grava": false
    },
    "ping_write": {
      "endpoint": "/api/dieta/ia/ping-write",
      "exemplo_minimo": {
        "origem": "chatgpt",
        "teste": true
      },
      "grava": true,
      "observacao": "Grava log/auditoria mínima e confirma que a rota de escrita está acessível."
    },
    "proxy_chatgpt": {
      "endpoint": "/api/chatgpt/dieta/proxy",
      "exemplo_minimo": {
        "method": "POST",
        "path": "/api/dieta/ia/ping-write",
        "body": {
          "origem": "chatgpt_proxy",
          "teste": true
        }
      },
      "grava": "depende da rota alvo e das flags confirmar_criacao/confirmar_importacao"
    },
    "criar_paciente": {
      "endpoint": "/api/dieta/ia/criar-paciente",
      "exemplo_minimo": {
        "paciente": {
          "nome": "Paciente exemplo IA",
          "cpf": "12345678909",
          "data_nascimento": "1990-05-20",
          "sexo": "Feminino"
        },
        "confirmar_criacao": false
      },
      "grava_quando": "confirmar_criacao: true"
    },
    "criar_plano": {
      "endpoint": "/api/dieta/ia/criar-plano",
      "exemplo_minimo": {
        "dados": {
          "paciente": "Paciente exemplo IA",
          "kcal": 1800,
          "peso": 70,
          "altura": 165,
          "objetivo": "emagrecimento",
          "padrao_alimentar": "Dieta Padrão Fluence",
          "tipo_dieta_filtro": "Normal",
          "refeicoes": 4,
          "proteina_modo": "auto",
          "carboidrato_modo": "auto",
          "restricoes": [],
          "compatibilidade_dietas": [
            "padrao"
          ],
          "cpf": "12345678909"
        },
        "confirmar_criacao": false,
        "gerar_pdf": true
      },
      "grava_quando": "confirmar_criacao: true"
    },
    "validar_combos": {
      "endpoint": "/api/dieta/combos/ia/validar",
      "exemplo_raiz": {
        "schema": "fluence-meal-combos/v1",
        "nome": "Catalogo exemplo Harxy IA",
        "macro_precision": "estimado_taco_tbca",
        "modo_ativo": "combo_de_refeicao",
        "combos": [
          {
            "combo_id": "ia_exemplo_cafe_ovos_fruta_001",
            "nome": "Cafe da manha exemplo - ovos e fruta",
            "meal_keys": [
              "breakfast"
            ],
            "perfil_macro": "proteico",
            "combo_family": "exemplo_ia",
            "main_carb_family": "fruta",
            "main_protein_family": "ovo",
            "frequency_recommendation": "moderado",
            "cultural_coherence": "alta",
            "tags": [
              "exemplo_ia",
              "harxy"
            ],
            "itens": [
              {
                "item_id": "ovos_mexidos",
                "nome": "Ovos mexidos",
                "quantidade": 2,
                "unidade": "unidade",
                "peso_estimado_g": 100,
                "grupo": "proteina",
                "macros_estimados": {
                  "kcal": 143,
                  "proteina_g": 13,
                  "carboidrato_g": 1,
                  "gordura_g": 10
                }
              },
              {
                "item_id": "banana_prata",
                "nome": "Banana prata",
                "quantidade": 1,
                "unidade": "unidade",
                "peso_estimado_g": 70,
                "grupo": "fruta",
                "macros_estimados": {
                  "kcal": 62,
                  "proteina_g": 0.9,
                  "carboidrato_g": 16,
                  "gordura_g": 0.1
                }
              }
            ],
            "macros_estimados": {
              "kcal": 205,
              "proteina_g": 13.9,
              "carboidrato_g": 17,
              "gordura_g": 10.1
            },
            "diet_normal": true,
            "diet_vegetarian": false,
            "diet_vegan": false,
            "diet_compatibility": {
              "permitido_em": [
                "padrao"
              ],
              "ajuste_em": [],
              "bloqueado_em": [],
              "cautela_em": []
            },
            "observacao_clinica": "Exemplo tecnico para validar o contrato; revisar clinicamente antes de usar em paciente real."
          }
        ]
      },
      "grava": false
    },
    "gravar_combos": {
      "endpoint": "/api/dieta/combos/ia/upsert",
      "grava_quando": "confirmar_importacao: true"
    }
  },
  "erros_possiveis": {
    "response_shape": [
      "ok",
      "valid",
      "response_contract",
      "erro",
      "codigo",
      "detalhes",
      "feedback.status",
      "feedback.summary",
      "feedback.next_action",
      "validation_report"
    ],
    "autenticacao": [
      {
        "status": 200,
        "codigo": "public_ai",
        "mensagem": "Rotas IA de paciente, plano alimentar e combo aceitam leitura e escrita sem token nesta fase."
      },
      {
        "status": 401,
        "codigo": "DIET_AI_TOKEN_NOT_CONFIGURED",
        "mensagem": "Token de integração não configurado no servidor."
      },
      {
        "status": 401,
        "codigo": "DIET_AI_TOKEN_INVALID",
        "mensagem": "Token de integração inválido."
      },
      {
        "status": 403,
        "codigo": "AUTHZ_DENIED",
        "mensagem": "Sessão sem permissão para a integração IA."
      }
    ],
    "calculo": [
      {
        "status": 400,
        "codigo": "DIET_AI_DADOS_REQUIRED",
        "mensagem": "Envie um objeto dados com os campos do plano alimentar."
      },
      {
        "status": 400,
        "codigo": "DIET_ENGINE_MACRO_PERCENT_TOTAL_INVALID",
        "mensagem": "Os percentuais de macros precisam somar 100."
      },
      {
        "status": 400,
        "codigo": "DIET_AI_SIMULATION_ERROR",
        "mensagem": "O motor não conseguiu simular a dieta com os dados enviados."
      },
      {
        "status": 400,
        "codigo": "blocked_by_metabolic_rules",
        "mensagem": "feedback.metabolic_blocks explica qual regra metabólica bloqueou a simulação."
      }
    ],
    "paciente": [
      {
        "status": 400,
        "codigo": "DIET_AI_PATIENT_INPUT_INVALID",
        "mensagem": "Payload de paciente inválido; veja detalhes e campos_esperados."
      },
      {
        "status": 409,
        "codigo": "DIET_AI_PATIENT_ALREADY_EXISTS",
        "mensagem": "Já existe paciente com este CPF no tenant; use o paciente existente."
      },
      {
        "status": 200,
        "codigo": "patient_ready_for_confirmation",
        "mensagem": "Paciente validado em prévia; nada foi gravado sem confirmar_criacao: true."
      },
      {
        "status": 201,
        "codigo": "patient_created",
        "mensagem": "Paciente gravado no cadastro do tenant."
      }
    ],
    "plano_alimentar": [
      {
        "status": 400,
        "codigo": "DIET_AI_PATIENT_CPF_INVALID",
        "mensagem": "Informe dados.cpf com um CPF válido para vincular o plano alimentar."
      },
      {
        "status": 400,
        "codigo": "DIET_AI_PATIENT_NAME_REQUIRED",
        "mensagem": "Informe dados.paciente ou paciente_contexto.nome para vincular o plano alimentar."
      },
      {
        "status": 503,
        "codigo": "DIET_COMBO_SOURCE_UNAVAILABLE",
        "mensagem": "Catálogo PostgreSQL oficial de combos indisponível; a resposta pode trazer meta_result parcial."
      },
      {
        "status": 400,
        "codigo": "REPORT_JOB_TENANT_REQUIRED",
        "mensagem": "PDF não foi enfileirado porque faltou tenant para criar o job de relatório."
      },
      {
        "status": 400,
        "codigo": "REPORT_JOB_PATIENT_REQUIRED",
        "mensagem": "PDF não foi enfileirado porque faltou paciente_contexto.cpf."
      },
      {
        "status": 409,
        "codigo": "REPORT_JOB_ARTIFACT_NOT_READY",
        "mensagem": "Job de PDF existe, mas o artefato ainda não está pronto; consulte status_url até succeeded."
      },
      {
        "status": 200,
        "codigo": "plan_ready_for_confirmation",
        "mensagem": "Plano calculado em prévia; nada foi gravado sem confirmar_criacao: true."
      }
    ],
    "combos": [
      {
        "status": 400,
        "codigo": "combo_ai_validation_v1",
        "mensagem": "JSON bloqueado por contrato; veja detalhes, feedback.first_errors e validation_report.errors."
      },
      {
        "status": 400,
        "codigo": "COMBO_AI_TENANT_INVALID",
        "mensagem": "Tenant inválido para integração IA."
      },
      {
        "status": 200,
        "codigo": "preview_ready",
        "mensagem": "JSON válido em prévia; nada foi gravado sem confirmar_importacao: true."
      },
      {
        "status": 200,
        "codigo": "applied",
        "mensagem": "Combos gravados no catálogo PostgreSQL do tenant."
      }
    ],
    "exemplos_de_validacao_combo": [
      "Raiz.schema: deve ser \"fluence-meal-combos/v1\".",
      "Raiz.combos: deve ser lista com 1 ou mais combos.",
      "Combo N.combo_id: valor duplicado na base.",
      "Combo N.meal_keys: valor inválido.",
      "Combo N.itens[1].macros_estimados.kcal: deve ser número JSON real.",
      "Combo N.diet_compatibility: informe exatamente uma compatibilidade no total."
    ]
  },
  "como_interpretar_respostas": {
    "ok_true_valid_true": "A estrutura passou. Confira applied/persisted/requires_confirmation para saber se gravou ou só gerou prévia.",
    "ok_false_valid_false": "Não grave nem prossiga. Leia erro, código, detalhes e feedback.next_action.",
    "partial_true": "O motor conseguiu parte do cálculo, mas faltou recurso externo, normalmente catálogo PostgreSQL de combos.",
    "validation_report": "Quando existir, é o melhor feedback para corrigir JSON de combos."
  }
}