Solução de problemas

Algo no AWR não está se comportando como você espera. Este guia trabalha dos sintomas às correções: primeiro verificações de saúde, depois problemas de banco de dados, depois mudanças interrompidas nos seus arquivos-fonte. Cada seção dá o comando exato a executar e como ler a saída. Para os comandos do dia a dia, veja Fluxo de trabalho diário e a Referência da CLI.

Passo um: rode uma verificação de saúde

O AWR traz um comando de diagnóstico embutido chamado Doctor, em dois níveis:

awr --json doctor --database-only
awr --json doctor

• --database-only verifica o próprio banco SQLite: integridade, chaves estrangeiras, versão do schema, identidades de migrações e objetos de schema de propriedade do AWR.
• O doctor completo inspeciona adicionalmente os seus arquivos-fonte selecionados e os vínculos entre os registros do runtime e os arquivos no disco.

O Doctor abre o banco de dados em modo somente leitura. Ele não migra o schema, não reindexa fontes, não aplica mutações pendentes, não expira claims nem exclui arquivos órfãos — então é sempre seguro executá-lo, mesmo em um projeto danificado.

Lendo os achados do Doctor

O Doctor reporta problemas como achados explícitos em vez de adivinhar:

• schema_issues — tabelas, colunas, índices ou triggers de propriedade do AWR ausentes ou alterados, verificados contra as migrações embutidas. Objetos extras podem coexistir; o Doctor não vai reparar definições nem imprimir o SQL delas.
• foreign_key_check_error — uma referência malformada impediu o SQLite de sequer rodar a sua verificação de chaves estrangeiras. Se você vir este campo, o banco de dados não está saudável, e um relatório de zero violações significa "não conseguimos contá-las", não "está tudo bem".
• Sessões ativas — apenas informativo; um registro antigo não prova que o processo está morto.
• Dependências ausentes, arestas soltas, fontes indisponíveis, salvamentos interrompidos e artefatos danificados ou não registrados são cada um reportados como achados. Páginas ilegíveis ou um banco de dados estranho (não AWR) produzem erros explícitos, não um status enganoso.

Sintoma: "O AWR rejeitou o meu arquivo-fonte"

Quando um arquivo-fonte YAML tem um erro de sintaxe ou um campo de tipo errado, o AWR falha com o código de erro InvalidInput e detalhes estruturados:

{
  "location": {
    "locator": "file:///project/work.yaml",
    "pointer": "/work_items/0/title",
    "line": 3,
    "column": 10
  },
  "rule": "ledger.string",
  "repair": "Use a quoted string or a YAML block scalar (|) for multiline text."
}

Como ler: pointer nomeia o campo problemático usando o vocabulário do seu próprio arquivo-fonte (incluindo nomes de campos em chinês configurados); line e column começam em um. Erros de sintaxe puros podem ter apenas coordenadas do parser, e algumas consultas (como aliases YAML) mantêm o pointer com coordenadas nulas — isso não rejeita um arquivo que, fora isso, é válido. rule nomeia a expectativa que falhou; repair descreve a estrutura esperada. Ele nunca edita o arquivo nem ecoa de volta o valor rejeitado.

Um caso comum: você escreveu title: [Draft, Review], que o YAML interpreta como uma lista, mas o campo exige uma string. Se a vírgula era para ser literal:

title: "Draft, Review"

Para descrições multilinha, use um bloco escalar do YAML (|); texto chinês válido e caminhos com espaços são totalmente suportados.

Sintoma: "As minhas mudanças não aparecem nas consultas"

Você editou um arquivo-fonte, mas o AWR ainda mostra fatos antigos. Rode uma reindexação:

awr source reindex

Depois verifique as duas partes do relatório: sucesso da operação e completude da projeção. Uma varredura pode ter sucesso enquanto a projeção permanece incompleta, porque a varredura observa as fontes sem importar os seus fatos alterados. O mesmo relatório vem como JSON com --json e via MCP awr_source_reindex. Compare saídas a partir de snapshots iniciais equivalentes; a própria reindexação atualiza o estado da fonte.

Se a evidência de um item de trabalho parecer estranha, work show (ou o MCP awr_work_get) reporta evidence_groups ao lado da lista plana evidence. Cada grupo tem um locator exato; uma referência de fonte e um relatório verificado no mesmo caminho permanecem distintos, e o agrupamento nunca transfere verificação entre registros.

Sintoma: "O banco de dados está corrompido ou foi perdido"

Os seus arquivos-fonte são autoridade para os fatos do projeto, mas o banco de dados SQLite (.awr/state.db) também guarda estado que esses arquivos não contêm: sessões, claims, checkpoints, eventos de runtime, registros de artefatos e tentativas de mutação. A reindexação atualiza as projeções a partir das fontes, mas não consegue reconstruir esse histórico de runtime — e inicializar um banco novo a partir das mesmas fontes também não consegue.

Fazendo backup corretamente

Para um snapshot recuperável, mantenha todos estes itens juntos e pause os escritores do projeto enquanto os reúne (a API de backup do SQLite fornece uma imagem coerente do banco, mas não faz snapshot dos arquivos ao redor):

• Um backup coerente de .awr/state.db feito com a API de backup do SQLite ou ferramenta equivalente — copiar o arquivo enquanto há escritores ativos pode perder registros confirmados que ainda estão no write-ahead log.
• Os arquivos-fonte correspondentes, a revisão do Git, o .awr/project.toml, a configuração de raiz autorizada e quaisquer fontes externas explicitamente autorizadas.
• Os arquivos de artefatos gerenciados, os artefatos locais registrados fora do diretório gerenciado e os journals e snapshots de recuperação de .awr/mutations referenciados por operações pendentes.

Restaurando

1. Pare o projeto.
2. Restaure na raiz canônica registrada; preserve o estado deslocado em vez de excluí-lo.
3. Rode awr --json doctor --database-only e depois o awr --json doctor completo.

Uma restauração pode recuperar o registro de um artefato enquanto o seu arquivo ainda está ausente — restaure o arquivo ou deixe o achado sem resolver. awr source reindex não é nem uma restauração de runtime nem uma ferramenta de realocação de banco de dados.

O Doctor pode realizar reparos nomeados, mas somente com a revisão atual do projeto, um objeto selecionado e um motivo; os reparos preservam as fontes e o estado de runtime não relacionado. Se a integridade do banco de dados estiver comprometida, os reparos de runtime sugeridos ficam desabilitados — sem reconstrução automática.

Sintoma: "Uma mutação foi interrompida no meio da escrita"

O AWR aplica propostas aprovadas aos seus arquivos-fonte com proteções de durabilidade: snapshots imutáveis de antes/depois são salvos antes de a tentativa ser registrada, e o sucesso exige os bytes de fonte pretendidos, uma projeção reconstruída e o evento final de aplicação. Se um processo morre no meio da escrita, a tentativa permanece aberta e recuperável.

Se você receber MutationIncomplete com write_outcome: pending_recovery, inspecione primeiro:

awr --json doctor
awr --json proposal show PROPOSAL_ID

Leia o project_revision atual na saída e depois retome a proposta:

awr --json proposal recover PROPOSAL_ID \
  --actor reviewer \
  --reason "Resume the interrupted report review" \
  --expected-revision CURRENT_REVISION

O que a recuperação faz depende de quão longe a tentativa chegou:

Uma nova tentativa bem-sucedida reporta recovered, nomeia a tentativa original e vincula o seu resolved_event_id ao evento final.

Duas coisas a não fazer:

• Não edite os snapshots para forçar um resultado. Se a fonte atual não corresponde a nenhum dos snapshots, resolva o conflito na fonte e prepare uma nova proposta.
• Não presuma que uma nova tentativa escreveu o arquivo. source_write_performed descreve apenas a invocação atual — é por isso que a recuperação revalida primeiro.

Concorrência: os escritores do AWR se coordenam por uma trava de SO por fonte e verificações transacionais de expected_revision. Fontes separadas progridem de forma independente, mas uma revisão de projeto intermediária pode exigir uma nova tentativa explícita de recuperação. Editores externos não entram na trava; verificações de impressão digital detectam as mudanças deles.

Quando parar e pedir ajuda

Pare e escale em vez de improvisar quando:

• O Doctor reportar integridade de banco de dados comprometida (foreign_key_check_error, páginas ilegíveis) — os reparos de runtime ficam desabilitados, sem reconstrução automática.
• Uma recuperação de mutação reportar um conflito de fonte/snapshot — o caminho suportado é uma nova proposta, não editar snapshots ou journals à mão.
• O seu cenário envolver queda de energia da máquina, escritores distribuídos ou outros sistemas operacionais — as garantias de recuperação cobrem interrupção de processo local; além disso não está estabelecido.

Antes de pedir ajuda ou abrir uma issue, capture o estado enquanto ele está fresco:

awr --json doctor --database-only
awr --json doctor
awr --json proposal show PROPOSAL_ID   # if a mutation is involved

Mantenha o banco de dados deslocado, os journals de .awr/mutations e os arquivos-fonte relevantes intocados — eles tornam um relatório acionável e são o seu plano B se a correção der errado.