Referência: schema do vault¶

Diátaxis: reference. Gerado a partir de migrations/ — fonte única da verdade.

Este documento é regenerado por scripts/generate-schema-docs.py. Sempre que adicionar/alterar uma migration:

python scripts/generate-schema-docs.py

Visão geral¶

O vault é um arquivo SQLite cifrado com ChaCha20-Poly1305 via sqlite3mc + Argon2id KDF. Campos individuais marcados com 🔒 são adicionalmente cifrados em repouso por chave field-level (HKDF-SHA256 derivada da master key). Veja docs/explanation/arquitetura.md.

Migrations aplicadas: 11

001_initial_schema.sql
002_patients_professionals.sql
003_audit_log.sql
004_audit_whitelist_expansion.sql
005_attachments.sql
006_rag.sql
007_audit_chain.sql
008_rag_encrypt.sql
009_protocol_rag.sql
010_encounters_encrypt.sql
011_patient_anomcode.sql

Tabelas¶

`audit_log`¶

Definição (DDL)

CREATE TABLE audit_log (
    id                  TEXT PRIMARY KEY,           -- UUID
    timestamp_utc       TEXT NOT NULL,              -- ISO-8601
    action              TEXT NOT NULL,              -- categórico
    actor_cns           TEXT,                       -- CNS do operador (em claro)
    entity_type         TEXT,                       -- 'encounter' / 'patient' / etc
    entity_id           TEXT,                       -- UUID/handle interno
    details_encrypted   BLOB                        -- AEAD opcional
, chain_seq  INTEGER, prev_hash  TEXT, entry_mac  TEXT)

Colunas

#	Nome	Tipo	NotNull	Default	PK	Sensível
0	`id`	`TEXT`	não	—	sim
1	`timestamp_utc`	`TEXT`	sim	—	não
2	`action`	`TEXT`	sim	—	não
3	`actor_cns`	`TEXT`	não	—	não
4	`entity_type`	`TEXT`	não	—	não
5	`entity_id`	`TEXT`	não	—	não
6	`details_encrypted`	`BLOB`	não	—	não	🔒
7	`chain_seq`	`INTEGER`	não	—	não
8	`prev_hash`	`TEXT`	não	—	não
9	`entry_mac`	`TEXT`	não	—	não

Índices

idx_audit_log_chain_seq — (chain_seq)
idx_audit_log_actor — (actor_cns)
idx_audit_log_action — (action)
idx_audit_log_timestamp — (timestamp_utc)

`encounter_attachments`¶

Definição (DDL)

CREATE TABLE encounter_attachments (
    id                  TEXT PRIMARY KEY,                    -- ULID
    encounter_id        TEXT NULL REFERENCES encounters(id) ON DELETE CASCADE,
    patient_id          TEXT NULL REFERENCES patients(id) ON DELETE SET NULL,
    filename_encrypted  BLOB NOT NULL,
    mime_type           TEXT NOT NULL,
    size_bytes          INTEGER NOT NULL CHECK (size_bytes > 0 AND size_bytes <= 10485760),
    storage_strategy    TEXT NOT NULL CHECK (storage_strategy IN ('inline', 'fs_external')),
    blob_encrypted      BLOB NULL,                            -- preenchido se inline
    external_path       TEXT NULL,                            -- ULID-named se fs_external
    sha256              TEXT NOT NULL,                        -- hash do plaintext pre-cifra
    nonce_blob          BLOB NULL,                            -- 12 bytes p/ blob inline
    nonce_external      BLOB NULL,                            -- 12 bytes p/ external file
    source              TEXT NOT NULL CHECK (
        source IN ('manual', 'bluetooth_obex', 'https_qr', 'clipboard', 'ocr_output')
    ),
    received_at         TEXT NOT NULL,                        -- ISO-8601 UTC
    attached_at         TEXT NULL,                            -- quando vinculado a encounter
    created_by_cns      TEXT NULL                             -- actor (operador)
)

Colunas

#	Nome	Tipo	NotNull	Default	PK	Sensível
0	`id`	`TEXT`	não	—	sim
1	`encounter_id`	`TEXT`	não	—	não
2	`patient_id`	`TEXT`	não	—	não
3	`filename_encrypted`	`BLOB`	sim	—	não	🔒
4	`mime_type`	`TEXT`	sim	—	não
5	`size_bytes`	`INTEGER`	sim	—	não
6	`storage_strategy`	`TEXT`	sim	—	não
7	`blob_encrypted`	`BLOB`	não	—	não	🔒
8	`external_path`	`TEXT`	não	—	não
9	`sha256`	`TEXT`	sim	—	não
10	`nonce_blob`	`BLOB`	não	—	não
11	`nonce_external`	`BLOB`	não	—	não
12	`source`	`TEXT`	sim	—	não
13	`received_at`	`TEXT`	sim	—	não
14	`attached_at`	`TEXT`	não	—	não
15	`created_by_cns`	`TEXT`	não	—	não

Índices

idx_attachments_received — (received_at)
idx_attachments_patient — (patient_id)
idx_attachments_encounter — (encounter_id)

Foreign keys

patient_id → patients(id) (ON UPDATE NO ACTION, ON DELETE SET NULL)
encounter_id → encounters(id) (ON UPDATE NO ACTION, ON DELETE CASCADE)

`encounters`¶

Definição (DDL)

CREATE TABLE encounters (
    id                       TEXT PRIMARY KEY,
    created_at               TEXT NOT NULL,
    updated_at               TEXT NOT NULL,
    professional_cns         TEXT NOT NULL,
    professional_cpf_encrypted BLOB,
    professional_role        TEXT NOT NULL,
    patient_id_local         TEXT NOT NULL,
    encounter_date           TEXT NOT NULL,
    encounter_type           TEXT NOT NULL,
    soap_subjective          TEXT,
    soap_objective           TEXT,
    soap_assessment          TEXT,
    soap_plan                TEXT,
    ciap2_codes              TEXT,
    cid10_codes              TEXT,
    procedures               TEXT,
    medications              TEXT,
    metadata                 TEXT NOT NULL,
    audit_log                TEXT NOT NULL DEFAULT '[]',
    hash_sha256              TEXT NOT NULL
, patient_id TEXT REFERENCES patients(id), professional_id TEXT REFERENCES professionals(id), soap_subjective_enc BLOB, soap_objective_enc  BLOB, soap_assessment_enc BLOB, soap_plan_enc       BLOB, ciap2_codes_enc     BLOB, cid10_codes_enc     BLOB, medications_enc     BLOB)

Colunas

#	Nome	Tipo	NotNull	Default	PK	Sensível
0	`id`	`TEXT`	não	—	sim
1	`created_at`	`TEXT`	sim	—	não
2	`updated_at`	`TEXT`	sim	—	não
3	`professional_cns`	`TEXT`	sim	—	não
4	`professional_cpf_encrypted`	`BLOB`	não	—	não	🔒
5	`professional_role`	`TEXT`	sim	—	não
6	`patient_id_local`	`TEXT`	sim	—	não
7	`encounter_date`	`TEXT`	sim	—	não
8	`encounter_type`	`TEXT`	sim	—	não
9	`soap_subjective`	`TEXT`	não	—	não
10	`soap_objective`	`TEXT`	não	—	não
11	`soap_assessment`	`TEXT`	não	—	não
12	`soap_plan`	`TEXT`	não	—	não
13	`ciap2_codes`	`TEXT`	não	—	não
14	`cid10_codes`	`TEXT`	não	—	não
15	`procedures`	`TEXT`	não	—	não
16	`medications`	`TEXT`	não	—	não
17	`metadata`	`TEXT`	sim	—	não
18	`audit_log`	`TEXT`	sim	`'[]'`	não
19	`hash_sha256`	`TEXT`	sim	—	não
20	`patient_id`	`TEXT`	não	—	não
21	`professional_id`	`TEXT`	não	—	não
22	`soap_subjective_enc`	`BLOB`	não	—	não
23	`soap_objective_enc`	`BLOB`	não	—	não
24	`soap_assessment_enc`	`BLOB`	não	—	não
25	`soap_plan_enc`	`BLOB`	não	—	não
26	`ciap2_codes_enc`	`BLOB`	não	—	não
27	`cid10_codes_enc`	`BLOB`	não	—	não
28	`medications_enc`	`BLOB`	não	—	não

Índices

idx_encounters_professional_fk — (professional_id)
idx_encounters_patient_fk — (patient_id)
idx_encounters_professional — (professional_cns)
idx_encounters_patient — (patient_id_local)
idx_encounters_date — (encounter_date)

Foreign keys

professional_id → professionals(id) (ON UPDATE NO ACTION, ON DELETE NO ACTION)
patient_id → patients(id) (ON UPDATE NO ACTION, ON DELETE NO ACTION)

`mappings`¶

Definição (DDL)

CREATE TABLE mappings (
    id             TEXT PRIMARY KEY,
    name           TEXT NOT NULL,
    target_system  TEXT NOT NULL,
    target_version TEXT NOT NULL,
    version        TEXT NOT NULL,
    fields_json    TEXT NOT NULL,
    created_at     TEXT NOT NULL,
    updated_at     TEXT NOT NULL
)

Colunas

#	Nome	Tipo	NotNull	Default	PK
0	`id`	`TEXT`	não	—	sim
1	`name`	`TEXT`	sim	—	não
2	`target_system`	`TEXT`	sim	—	não
3	`target_version`	`TEXT`	sim	—	não
4	`version`	`TEXT`	sim	—	não
5	`fields_json`	`TEXT`	sim	—	não
6	`created_at`	`TEXT`	sim	—	não
7	`updated_at`	`TEXT`	sim	—	não

`patients`¶

Definição (DDL)

CREATE TABLE patients (
    id                       TEXT PRIMARY KEY,
    display_handle           TEXT NOT NULL UNIQUE,
    full_name_encrypted      BLOB,
    birth_date_encrypted     BLOB,
    mother_name_encrypted    BLOB,
    record_number_encrypted  BLOB,
    cns_encrypted            BLOB,
    notes_encrypted          BLOB,
    created_at               TEXT NOT NULL,
    updated_at               TEXT NOT NULL
, anomcode TEXT)

Colunas

#	Nome	Tipo	NotNull	Default	PK	Sensível
0	`id`	`TEXT`	não	—	sim
1	`display_handle`	`TEXT`	sim	—	não
2	`full_name_encrypted`	`BLOB`	não	—	não	🔒
3	`birth_date_encrypted`	`BLOB`	não	—	não	🔒
4	`mother_name_encrypted`	`BLOB`	não	—	não	🔒
5	`record_number_encrypted`	`BLOB`	não	—	não	🔒
6	`cns_encrypted`	`BLOB`	não	—	não	🔒
7	`notes_encrypted`	`BLOB`	não	—	não	🔒
8	`created_at`	`TEXT`	sim	—	não
9	`updated_at`	`TEXT`	sim	—	não
10	`anomcode`	`TEXT`	não	—	não

Índices

idx_patients_anomcode — (anomcode)
idx_patients_handle — (display_handle)

`professionals`¶

Definição (DDL)

CREATE TABLE professionals (
    id                       TEXT PRIMARY KEY,
    cns                      TEXT NOT NULL UNIQUE,
    cpf_encrypted            BLOB,
    full_name_encrypted      BLOB,
    professional_role        TEXT NOT NULL,
    professional_registry    TEXT,
    cnes_unit                TEXT,
    is_default               INTEGER NOT NULL DEFAULT 0,
    created_at               TEXT NOT NULL,
    updated_at               TEXT NOT NULL
)

Colunas

#	Nome	Tipo	NotNull	Default	PK	Sensível
0	`id`	`TEXT`	não	—	sim
1	`cns`	`TEXT`	sim	—	não
2	`cpf_encrypted`	`BLOB`	não	—	não	🔒
3	`full_name_encrypted`	`BLOB`	não	—	não	🔒
4	`professional_role`	`TEXT`	sim	—	não
5	`professional_registry`	`TEXT`	não	—	não
6	`cnes_unit`	`TEXT`	não	—	não
7	`is_default`	`INTEGER`	sim	`0`	não
8	`created_at`	`TEXT`	sim	—	não
9	`updated_at`	`TEXT`	sim	—	não

Índices

idx_professionals_default — (is_default)
idx_professionals_cns — (cns)

`protocol_chunks`¶

Definição (DDL)

CREATE TABLE protocol_chunks (
    id              TEXT PRIMARY KEY,                     -- ULID
    source_file     TEXT NOT NULL,                        -- basename do PDF (ex: "pcdt-hiv-2024.pdf")
    title           TEXT NOT NULL,                        -- título derivado do nome do arquivo
    page_number     INTEGER NOT NULL DEFAULT 0,           -- página de origem (0 = desconhecida)
    position        INTEGER NOT NULL CHECK (position >= 0), -- ordinal dentro do documento
    text            TEXT NOT NULL,                        -- conteúdo em claro (dado público)
    char_count      INTEGER NOT NULL CHECK (char_count > 0),
    token_estimate  INTEGER NOT NULL CHECK (token_estimate > 0),
    created_at      TEXT NOT NULL                         -- ISO-8601 UTC
)

Colunas

#	Nome	Tipo	NotNull	Default	PK
0	`id`	`TEXT`	não	—	sim
1	`source_file`	`TEXT`	sim	—	não
2	`title`	`TEXT`	sim	—	não
3	`page_number`	`INTEGER`	sim	`0`	não
4	`position`	`INTEGER`	sim	—	não
5	`text`	`TEXT`	sim	—	não
6	`char_count`	`INTEGER`	sim	—	não
7	`token_estimate`	`INTEGER`	sim	—	não
8	`created_at`	`TEXT`	sim	—	não

Índices

idx_protocol_chunks_position — (source_file, position)
idx_protocol_chunks_source — (source_file)

`protocol_embeddings`¶

Definição (DDL)

CREATE TABLE protocol_embeddings (
    chunk_id        TEXT PRIMARY KEY REFERENCES protocol_chunks(id) ON DELETE CASCADE,
    model_id        TEXT NOT NULL,                        -- ex: "multilingual-e5-small-onnx"
    dimension       INTEGER NOT NULL CHECK (dimension > 0 AND dimension <= 4096),
    embedding_blob  BLOB NOT NULL,                        -- numpy float32 tobytes()
    indexed_at      TEXT NOT NULL                         -- ISO-8601 UTC
)

Colunas

#	Nome	Tipo	NotNull	Default	PK
0	`chunk_id`	`TEXT`	não	—	sim
1	`model_id`	`TEXT`	sim	—	não
2	`dimension`	`INTEGER`	sim	—	não
3	`embedding_blob`	`BLOB`	sim	—	não
4	`indexed_at`	`TEXT`	sim	—	não

Índices

idx_protocol_embeddings_model — (model_id)

Foreign keys

chunk_id → protocol_chunks(id) (ON UPDATE NO ACTION, ON DELETE CASCADE)

`rag_chunks`¶

Definição (DDL)

CREATE TABLE rag_chunks (
    id              TEXT PRIMARY KEY,                          -- ULID
    encounter_id    TEXT NOT NULL REFERENCES encounters(id) ON DELETE CASCADE,
    position        INTEGER NOT NULL CHECK (position >= 0),
    text_encrypted  BLOB NOT NULL,                             -- ChaCha20-Poly1305; AAD = id
    char_count      INTEGER NOT NULL CHECK (char_count > 0),
    token_estimate  INTEGER NOT NULL CHECK (token_estimate > 0),
    created_at      TEXT NOT NULL                              -- ISO-8601 UTC
)

Colunas

#	Nome	Tipo	NotNull	Default	PK	Sensível
0	`id`	`TEXT`	não	—	sim
1	`encounter_id`	`TEXT`	sim	—	não
2	`position`	`INTEGER`	sim	—	não
3	`text_encrypted`	`BLOB`	sim	—	não	🔒
4	`char_count`	`INTEGER`	sim	—	não
5	`token_estimate`	`INTEGER`	sim	—	não
6	`created_at`	`TEXT`	sim	—	não

Índices

idx_rag_chunks_position — (encounter_id, position)
idx_rag_chunks_encounter — (encounter_id)

Foreign keys

encounter_id → encounters(id) (ON UPDATE NO ACTION, ON DELETE CASCADE)

`rag_embeddings`¶

Definição (DDL)

CREATE TABLE rag_embeddings (
    chunk_id              TEXT PRIMARY KEY REFERENCES rag_chunks(id) ON DELETE CASCADE,
    model_id              TEXT NOT NULL,
    dimension             INTEGER NOT NULL CHECK (dimension > 0 AND dimension <= 4096),
    embedding_encrypted   BLOB NOT NULL,                       -- ChaCha20-Poly1305; AAD = chunk_id
    indexed_at            TEXT NOT NULL                        -- ISO-8601 UTC
)

Colunas

#	Nome	Tipo	NotNull	Default	PK	Sensível
0	`chunk_id`	`TEXT`	não	—	sim
1	`model_id`	`TEXT`	sim	—	não
2	`dimension`	`INTEGER`	sim	—	não
3	`embedding_encrypted`	`BLOB`	sim	—	não	🔒
4	`indexed_at`	`TEXT`	sim	—	não

Índices

idx_rag_embeddings_model — (model_id)

Foreign keys

chunk_id → rag_chunks(id) (ON UPDATE NO ACTION, ON DELETE CASCADE)

`rag_meta`¶

Definição (DDL)

CREATE TABLE rag_meta (
    id                  INTEGER PRIMARY KEY CHECK (id = 1),
    active_model_id     TEXT NOT NULL,                   -- modelo atualmente em uso
    embedding_dimension INTEGER NOT NULL CHECK (embedding_dimension > 0),
    chunk_target_tokens INTEGER NOT NULL DEFAULT 256,    -- alvo do chunker
    chunk_overlap_tokens INTEGER NOT NULL DEFAULT 32,    -- overlap do chunker
    last_indexed_at     TEXT NULL,                       -- último encounter indexado
    last_full_reindex_at TEXT NULL                       -- última recriação completa
)

Colunas

#	Nome	Tipo	NotNull	Default	PK
0	`id`	`INTEGER`	não	—	sim
1	`active_model_id`	`TEXT`	sim	—	não
2	`embedding_dimension`	`INTEGER`	sim	—	não
3	`chunk_target_tokens`	`INTEGER`	sim	`256`	não
4	`chunk_overlap_tokens`	`INTEGER`	sim	`32`	não
5	`last_indexed_at`	`TEXT`	não	—	não
6	`last_full_reindex_at`	`TEXT`	não	—	não

`schema_version`¶

Definição (DDL)

CREATE TABLE schema_version (
    version     INTEGER PRIMARY KEY,
    applied_at  TEXT NOT NULL,
    description TEXT NOT NULL
)

Colunas

#	Nome	Tipo	NotNull	Default	PK
0	`version`	`INTEGER`	não	—	sim
1	`applied_at`	`TEXT`	sim	—	não
2	`description`	`TEXT`	sim	—	não

`templates`¶

Definição (DDL)

CREATE TABLE templates (
    id          TEXT PRIMARY KEY,
    name        TEXT NOT NULL,
    description TEXT,
    specialty   TEXT,
    version     TEXT NOT NULL,
    schema_json TEXT,
    fields_json TEXT,
    defaults_json TEXT,
    created_at  TEXT NOT NULL,
    updated_at  TEXT NOT NULL
)

Colunas

#	Nome	Tipo	NotNull	Default	PK
0	`id`	`TEXT`	não	—	sim
1	`name`	`TEXT`	sim	—	não
2	`description`	`TEXT`	não	—	não
3	`specialty`	`TEXT`	não	—	não
4	`version`	`TEXT`	sim	—	não
5	`schema_json`	`TEXT`	não	—	não
6	`fields_json`	`TEXT`	não	—	não
7	`defaults_json`	`TEXT`	não	—	não
8	`created_at`	`TEXT`	sim	—	não
9	`updated_at`	`TEXT`	sim	—	não

`vault_meta`¶

Definição (DDL)

CREATE TABLE vault_meta (
    key   TEXT PRIMARY KEY,
    value TEXT NOT NULL
)

Colunas

#	Nome	Tipo	NotNull	Default	PK	Sensível
0	`key`	`TEXT`	não	—	sim
1	`value`	`TEXT`	sim	—	não

Referência: schema do vault¶

Visão geral¶

Tabelas¶

audit_log¶

encounter_attachments¶

encounters¶

mappings¶

patients¶

professionals¶

protocol_chunks¶

protocol_embeddings¶

rag_chunks¶

rag_embeddings¶

rag_meta¶

schema_version¶

templates¶

vault_meta¶

`audit_log`¶

`encounter_attachments`¶

`encounters`¶

`mappings`¶

`patients`¶

`professionals`¶

`protocol_chunks`¶

`protocol_embeddings`¶

`rag_chunks`¶

`rag_embeddings`¶

`rag_meta`¶

`schema_version`¶

`templates`¶

`vault_meta`¶