# metadata-governance 技术设计（Design）

## 1. 设计目标

围绕已上线的元数据配置页面，补齐“配置 -> 录入 -> 检索 -> 治理”的闭环：
- 元数据字段生命周期治理（draft/active/deprecated）
- KB/Intent/Flow/Prompt 录入联动与一致性校验
- Intent 路由后 metadata 过滤注入
- 拆解模板版本治理与回溯

## 2. 架构与职责

### 2.1 元数据配置层（Admin）
- 提供字段定义管理：`field_key/type/options/required/scope/status`
- 提供字段状态治理：
  - `draft`: 可编辑不可生效
  - `active`: 可用于新建与编辑
  - `deprecated`: 不可用于新建，历史可读

### 2.2 录入联动层（Admin Forms）
- 在以下录入页统一挂载 metadata 表单组件：
  - KB 文档
  - Intent Rule
  - Script Flow
  - Prompt Template
- 联动逻辑：对象类型变化时，根据 `scope` 动态渲染字段
- 校验逻辑：required 字段 + 类型校验 + enum 值校验

### 2.3 检索治理层（Runtime）
- 路由流程：Intent 命中 -> 目标知识库集合 -> metadata filters -> 向量召回
- metadata 注入来源：会话上下文、已提取槽位（grade/subject/scene）
- 兜底策略：无召回时 fallback（指定库或固定话术）并输出原因码

### 2.4 模板治理层（Ops）
- 拆解模板持久化与版本管理
- 提供最新生效版本查询能力

## 3. 数据模型建议

### 3.1 MetadataSchema
- id
- field_key
- label
- type
- required
- options
- default_value
- scope
- is_filterable
- is_rank_feature
- status
- version
- created_at/updated_at

### 3.2 MetadataPayload（挂载到业务对象）
- object_type
- object_id
- metadata: key-value
- schema_version

### 3.3 DecompositionTemplate
- id
- name
- template_content
- version
- status
- created_at/updated_at

## 4. 关键流程

### 4.1 配置到生效流程
1. 管理员创建/编辑字段（draft）
2. 审核后切换 active
3. 录入页拉取 active 字段并动态渲染
4. 字段 deprecated 后，新建不可选，历史只读可见

### 4.2 运行时检索流程
1. Intent Rule 命中 response_type=rag
2. 选择目标知识库（支持多库）
3. 注入 metadata 过滤条件
4. 执行向量检索
5. 无召回走 fallback，并记录原因码

## 5. 错误与降级策略

- 配置异常：字段配置缺失/冲突 -> 使用系统默认字段集
- 过滤异常：metadata 过滤构造失败 -> 降级为不加过滤检索（记录 warning）
- 无召回：返回 fallback 并记录 `no_recall_after_metadata_filter`

## 6. 可观测性

- 关键日志字段：
  - `intent_id`
  - `target_kbs`
  - `applied_metadata_filters`
  - `fallback_reason_code`
  - `latency_ms`

## 7. 与 AC 对齐

- 字段状态治理：AC-IDSMETA-13~14
- 跨模块录入联动：AC-IDSMETA-15~17
- 路由与检索治理：AC-IDSMETA-18~20
- 模板治理：AC-IDSMETA-21~22