# 元数据职责分层模块边界（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`
- 迭代策略：允许删除重建配置，不考虑历史数据迁移