ai-robot-core/spec/metadata-role-separation/scope.md

元数据职责分层模块边界（Scope）

1. 模块边界说明

1.1 覆盖范围

本模块聚焦于元数据字段的职责分层与运行时消费解耦，具体包括：

1. 字段职责分层

   • 为元数据字段引入 field_roles 多选属性
   • 支持四种职责角色：resource_filter、slot、prompt_var、routing_signal
   • 单个字段可同时承担多种职责

2. 分层视图能力

   • 后端提供按 role 查询字段的能力
   • 工具与模块按 role 消费，不再全量混用

3. 槽位模型增强

   • 引入独立的槽位定义模型（可复用元数据字段但有独立运行时语义）
   • 支持 slot_key/type/required/extract_strategy/validation_rule/ask_back_prompt
   • 运行时值包含 source/confidence/updated_at

4. 工具协同改造

   • kb_search_dynamic 只消费 resource_filter 角色
   • memory_recall 只消费 slot 角色
   • intent_hint/high_risk_check 只消费 routing_signal 角色
   • prompt 渲染只消费 prompt_var 角色

5. 管理端可配置能力

   • 元数据字段编辑界面增加 field_roles 配置
   • 提供"按 role 过滤查看"能力
   • 允许删除重建配置（无需迁移兼容）

1.2 不覆盖范围

• 历史数据迁移：本迭代不负责历史数据的自动迁移，允许删除重建配置
• 向量引擎替换：不涉及 Qdrant 或其他向量引擎的替换
• LLM 模型切换：不涉及模型供应商或模型选型的变更
• 渠道端实现：不覆盖渠道侧 SegmentDispatcher/InterruptManager 等具体实现
• 元数据字段类型扩展：不新增字段类型（string/number/boolean/enum/array_enum 保持不变）

---

2. 依赖盘点

2.1 内部依赖

依赖模块	用途说明	接口
metadata-governance	元数据字段定义基础能力	/admin/metadata-schemas
intent-driven-mid-platform	中台运行时工具链	kb_search_dynamic, memory_recall, intent_hint, high_risk_check
ai-service-admin	管理端前端页面	元数据配置界面

2.2 外部依赖

依赖服务	用途说明
PostgreSQL	元数据字段定义、槽位定义存储
Redis	运行时缓存

---

3. 依赖接口清单

3.1 本模块依赖的外部接口（Consumer）

接口	来源模块	用途
GET /admin/metadata-schemas	metadata-governance	获取元数据字段列表
POST /admin/metadata-schemas	metadata-governance	创建元数据字段
PUT /admin/metadata-schemas/{id}	metadata-governance	更新元数据字段
DELETE /admin/metadata-schemas/{id}	metadata-governance	删除元数据字段

3.2 本模块对外提供的接口（Provider）

接口	用途
GET /admin/metadata-schemas/by-role	按 role 查询字段定义
GET /admin/slot-definitions	获取槽位定义列表
POST /admin/slot-definitions	创建槽位定义
PUT /admin/slot-definitions/{id}	更新槽位定义
DELETE /admin/slot-definitions/{id}	删除槽位定义
GET /mid/slots/by-role	运行时按 role 获取槽位定义

---

4. 数据模型边界

4.1 新增模型

模型名	说明
SlotDefinition	槽位定义表（独立于 MetadataFieldDefinition）

4.2 扩展模型

模型名	扩展字段
MetadataFieldDefinition	新增 field_roles: list[str] 字段

---

5. 工具消费关系

┌─────────────────────────────────────────────────────────────────┐
│                    元数据字段职责分层                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  MetadataFieldDefinition                                        │
│  └── field_roles: [resource_filter, slot, prompt_var,          │
│                    routing_signal]                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│resource_filter│   │     slot      │   │  prompt_var   │
└───────┬───────┘   └───────┬───────┘   └───────┬───────┘
        │                   │                   │
        ▼                   ▼                   ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│kb_search_     │   │memory_recall  │   │template_engine│
│dynamic        │   │               │   │               │
└───────────────┘   └───────────────┘   └───────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  routing_signal                                                 │
└───────┬─────────────────────────────────────────────────────────┘
        │
        ├───────────────┐
        ▼               ▼
┌───────────────┐ ┌───────────────┐
│intent_hint    │ │high_risk_check│
└───────────────┘ └───────────────┘

---

6. 版本与迭代

• 当前版本：v0.1.0
• AC 范围：AC-MRS-01 ~ AC-MRS-16
• 迭代策略：允许删除重建配置，不考虑历史数据迁移