🧠 TFF 知識管理藍圖

Constraints

CREATE CONSTRAINT document_id IF NOT EXISTS
FOR (d:Document) REQUIRE d.id IS UNIQUE;

CREATE CONSTRAINT chunk_id IF NOT EXISTS
FOR (c:Chunk) REQUIRE c.id IS UNIQUE;

CREATE CONSTRAINT assertion_id IF NOT EXISTS
FOR (a:Assertion) REQUIRE a.id IS UNIQUE;

MERGE 使用已驗證的 canonical ID

// 呼叫前由應用 schema 拒絕 null／空字串 ID；
// UNIQUE constraint 防重，但不代表屬性必然存在。
MERGE (d:Document {id: $documentId})
  ON CREATE SET d.createdAt = datetime()
SET d.revisionId = $revisionId,
    d.status = $status;
MERGE (c:Chunk {id: $chunkId})
SET c.text = $text;
MERGE (d)-[r:HAS_CHUNK]->(c)
SET r.relationId = $lineageRelationId,
    r.confidence = 1.0,
    r.evidenceChunkIds = [$chunkId],
    r.reviewStatus = 'approved',
    r.extractionMethod = 'deterministic-parser',
    r.extractionVersion = $parserVersion;

Assertion：主張、端點與證據

MATCH (s:Trend {id: $subjectId}),
      (o:Topic {id: $objectId})
WITH s, o, $evidenceChunkIds AS evidenceChunkIds
WHERE size(evidenceChunkIds) > 0
UNWIND evidenceChunkIds AS evidenceChunkId
MATCH (c:Chunk {id: evidenceChunkId})
WITH s, o, evidenceChunkIds,
     collect(DISTINCT c) AS evidenceChunks
WHERE size(evidenceChunks) = size(evidenceChunkIds)
MERGE (a:Assertion {id: $relationId})
SET a.predicate = $validatedPredicate,
    a.confidence = $confidence,
    a.polarity = $polarity,
    a.authorityFit = $authorityFit,
    a.evidenceChunkIds = $evidenceChunkIds,
    a.reviewStatus = $reviewStatus,
    a.extractionMethod = $extractionMethod,
    a.extractionModel = $extractionModel,
    a.extractionVersion = $extractionVersion,
    a.validFrom = CASE WHEN $validFrom IS NULL
      THEN null ELSE datetime($validFrom) END,
    a.validTo = CASE WHEN $validTo IS NULL
      THEN null ELSE datetime($validTo) END
MERGE (a)-[:SUBJECT]->(s)
MERGE (a)-[:OBJECT]->(o)
FOREACH (c IN evidenceChunks |
  MERGE (a)-[:SUPPORTED_BY]->(c)
);

OpenSearch hits → graph expansion

UNWIND $hits AS hit
MATCH (c:Chunk {id: hit.chunkId})
MATCH (d:Document)-[:HAS_CHUNK]->(c)
OPTIONAL MATCH (a:Assertion)-[:SUPPORTED_BY]->(c)
WHERE a.reviewStatus = 'approved'
  AND (a.validFrom IS NULL OR a.validFrom <= datetime())
  AND (a.validTo IS NULL OR datetime() < a.validTo)
OPTIONAL MATCH (a)-[:SUBJECT|OBJECT]->(e)
RETURN hit.rank, c.id, d.id,
       [item IN collect(DISTINCT CASE WHEN a IS NULL
         THEN null ELSE {
           assertionId: a.id, entityId: e.id,
           polarity: a.polarity,
           conflictStatus: a.conflictStatus,
           confidence: a.confidence
         } END)
        WHERE item IS NOT NULL] AS evidenceGraph;

Explicit mapping · valid JSON body

{
  "settings": { "index.knn": true },
  "mappings": {
    "dynamic": "strict",
    "properties": {
      "chunk_id": { "type": "keyword" },
      "card_id": { "type": "keyword" },
      "revision_id": { "type": "keyword" },
      "card_type": { "type": "keyword" },
      "source_id": { "type": "keyword" },
      "document_id": { "type": "keyword" },
      "language": { "type": "keyword" },
      "title": {
        "type": "text", "analyzer": "cjk",
        "fields": { "raw": { "type": "keyword", "ignore_above": 512 } }
      },
      "content": { "type": "text", "analyzer": "cjk" },
      "section_path": { "type": "text", "analyzer": "cjk" },
      "topic_ids": { "type": "keyword" },
      "neo4j_node_ids": { "type": "keyword" },
      "keywords": { "type": "keyword" },
      "category": { "type": "keyword" },
      "tags": { "type": "keyword" },
      "synonyms": { "type": "keyword" },
      "status": { "type": "keyword" },
      "is_current": { "type": "boolean" },
      "pii_level": { "type": "keyword" },
      "pii_status": { "type": "keyword" },
      "confidentiality": { "type": "keyword" },
      "acl_groups": { "type": "keyword" },
      "page_number": { "type": "integer" },
      "slide_number": { "type": "integer" },
      "quote_span": {
        "properties": {
          "start": { "type": "integer" },
          "end": { "type": "integer" }
        }
      },
      "valid_from": { "type": "date" },
      "valid_to": { "type": "date" },
      "published_at": { "type": "date" },
      "observed_at": { "type": "date" },
      "content_hash": { "type": "keyword" },
      "embedding_model_id": { "type": "keyword" },
      "embedding_version": { "type": "keyword" },
      "embedding_dimensions": { "type": "integer" },
      "chunk_strategy_version": { "type": "keyword" },
      "token_count": { "type": "integer" },
      "index_version": { "type": "keyword" },
      "indexed_at": { "type": "date" },
      "embedding": {
        "type": "knn_vector", "dimension": 768,
        "method": {
          "name": "hnsw", "engine": "lucene",
          "space_type": "cosinesimil",
          "parameters": { "ef_construction": 100, "m": 16 }
        }
      }
    }
  }
}

Serializer 契約：canonical camelCase 轉成 index snake_case，例如 cardVersion→revision_id、text→content、embeddingModel→embedding_model_id；pii_status 是由核可流程產生的安全投影欄位。送入 dynamic: strict 前先以同版 JSON Schema 驗證，不傳未映射欄位。

Search pipeline · valid JSON body

{
  "phase_results_processors": [
    {
      "normalization-processor": {
        "normalization": { "technique": "min_max" },
        "combination": {
          "technique": "arithmetic_mean",
          "parameters": { "weights": [0.4, 0.6] }
        }
      }
    }
  ]
}

Top-level hybrid query · valid JSON body

{
  "size": 20,
  "_source": { "excludes": ["embedding"] },
  "query": {
    "hybrid": {
      "filter": {
        "bool": { "filter": [
          { "term": { "status": "approved" } },
          { "term": { "is_current": true } },
          { "term": { "pii_status": "cleared" } },
          { "bool": { "should": [
            { "bool": { "must_not": { "exists": { "field": "valid_from" } } } },
            { "range": { "valid_from": { "lte": "now" } } }
          ], "minimum_should_match": 1 } },
          { "bool": { "should": [
            { "bool": { "must_not": { "exists": { "field": "valid_to" } } } },
            { "range": { "valid_to": { "gt": "now" } } }
          ], "minimum_should_match": 1 } },
          { "terms": { "acl_groups": ["ACL_GROUP_FROM_TRUSTED_ADAPTER"] } }
        ] }
      },
      "queries": [
        { "multi_match": {
          "query": "永續金融公司治理課程",
          "fields": ["title^3", "section_path^2", "content"]
        } },
        { "neural": { "embedding": {
          "query_text": "永續金融公司治理課程",
          "model_id": "DEPLOYED_MODEL_ID", "k": 100
        } } }
      ]
    }
  }
}

Atomic alias switch · valid JSON body

{
  "actions": [
    { "remove": {
      "index": "tff-kb-chunks-v1",
      "alias": "tff-kb-chunks-read"
    } },
    { "add": {
      "index": "tff-kb-chunks-v2",
      "alias": "tff-kb-chunks-read"
    } }
  ]
}