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

# 元数据职责分层优化 - 任务清单

## 任务概览

| 阶段 | 任务数 | 状态 |
|------|-------|------|
| Phase 1: 数据模型扩展 | 4 | ✅ 已完成 |
| Phase 2: 后端服务实现 | 6 | ✅ 已完成 |
| Phase 3: 工具协同改造 | 4 | ✅ 已完成 |
| Phase 4: 前端页面改造 | 3 | ✅ 已完成 |
| Phase 5: 测试与验收 | 3 | ⏳ 待开始 |

---

## Phase 1: 数据模型扩展

### Task 1.1: 扩展 MetadataFieldDefinition 模型
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-01, AC-MRS-02, AC-MRS-03
- **描述**: 在现有 `MetadataFieldDefinition` 模型中新增 `field_roles` 字段
- **产出**:
  - 修改 `ai-service/app/models/entities.py` 中的 `MetadataFieldDefinition` 类
  - 新增 `FieldRole` 枚举类
- **验收标准**:
  - `field_roles` 字段类型为 `list[str]`
  - 支持存储多个角色
  - 允许空列表

### Task 1.2: 创建 SlotDefinition 模型
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-07, AC-MRS-08
- **描述**: 创建独立的槽位定义模型
- **产出**:
  - 在 `ai-service/app/models/entities.py` 中新增 `SlotDefinition` 类
  - 新增 `ExtractStrategy` 枚举类
- **验收标准**:
  - 包含所有必需字段：slot_key, type, required, extract_strategy, validation_rule, ask_back_prompt
  - 支持 linked_field_id 关联元数据字段

### Task 1.3: 编写数据库迁移脚本
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-01, AC-MRS-07
- **描述**: 编写 PostgreSQL 迁移脚本
- **产出**:
  - 创建 `ai-service/scripts/migrations/007_add_field_roles_and_slot_definitions.sql`
- **验收标准**:
  - 为 `metadata_field_definitions` 表新增 `field_roles` 列
  - 创建 `slot_definitions` 表
  - 创建必要的索引

### Task 1.4: 更新 Pydantic Schema
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-01, AC-MRS-07
- **描述**: 更新请求/响应 Schema
- **产出**:
  - 创建 `ai-service/app/schemas/metadata.py`
  - 新增 `SlotDefinitionCreate/Update/Response` Schema
- **验收标准**:
  - Schema 与 OpenAPI 契约一致
  - 包含完整的字段校验规则

---

## Phase 2: 后端服务实现

### Task 2.1: 实现 RoleBasedFieldProvider 服务
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-04, AC-MRS-05, AC-MRS-10
- **描述**: 实现按角色查询字段的核心服务
- **产出**:
  - 创建 `ai-service/app/services/mid/role_based_field_provider.py`
- **验收标准**:
  - `get_fields_by_role()` 方法正确查询指定角色的字段
  - 无效角色返回 400 错误
  - 支持缓存机制

### Task 2.2: 扩展 MetadataFieldDefinitionService
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-01, AC-MRS-02, AC-MRS-03, AC-MRS-06
- **描述**: 扩展现有服务支持 field_roles
- **产出**:
  - 修改 `ai-service/app/services/metadata_field_definition_service.py`
- **验收标准**:
  - 创建/更新时支持 field_roles 字段
  - 支持按 role 过滤查询
  - field_roles 校验正确

### Task 2.3: 实现 SlotDefinitionService
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-07, AC-MRS-08
- **描述**: 实现槽位定义管理服务
- **产出**:
  - 创建 `ai-service/app/services/slot_definition_service.py`
- **验收标准**:
  - CRUD 操作正确
  - 支持关联元数据字段
  - slot_key 租户内唯一

### Task 2.4: 扩展 MetadataFieldDefinition API
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-01, AC-MRS-04, AC-MRS-05, AC-MRS-06, AC-MRS-16
- **描述**: 扩展现有 API 端点
- **产出**:
  - 修改 `ai-service/app/api/admin/metadata_field_definition.py`
  - 新增 `/by-role` 端点
- **验收标准**:
  - 所有端点符合 OpenAPI 契约
  - 包含 AC 注释

### Task 2.5: 实现 SlotDefinition API
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-07, AC-MRS-08, AC-MRS-16
- **描述**: 实现槽位定义管理 API
- **产出**:
  - 创建 `ai-service/app/api/admin/slot_definition.py`
- **验收标准**:
  - CRUD 端点符合 OpenAPI 契约
  - 包含 AC 注释

### Task 2.6: 实现运行时槽位 API
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-09, AC-MRS-10
- **描述**: 实现运行时槽位查询 API
- **产出**:
  - 创建 `ai-service/app/api/mid/slots.py`
- **验收标准**:
  - `/mid/slots/by-role` 端点正确返回槽位定义
  - `/mid/slots/{slot_key}` 端点正确返回运行时值

---

## Phase 3: 工具协同改造

### Task 3.1: 改造 kb_search_dynamic 工具
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-11
- **描述**: 改造 KB 动态检索工具，只消费 resource_filter 角色
- **产出**:
  - 修改 `ai-service/app/services/mid/kb_search_dynamic_tool.py`
  - 修改 `ai-service/app/services/mid/metadata_filter_builder.py`
- **验收标准**:
  - 只使用 field_roles 包含 resource_filter 的字段
  - 不影响现有功能

### Task 3.2: 改造 memory_recall 工具
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-12
- **描述**: 改造记忆召回工具，只消费 slot 角色
- **产出**:
  - 修改 `ai-service/app/services/mid/memory_recall_tool.py`
- **验收标准**:
  - 只使用 field_roles 包含 slot 的字段
  - 槽位合并逻辑正确

### Task 3.3: 改造 intent_hint 和 high_risk_check 工具
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-13
- **描述**: 改造意图提示和高风险检测工具，只消费 routing_signal 角色
- **产出**:
  - 修改 `ai-service/app/services/mid/intent_hint_tool.py`
  - 修改 `ai-service/app/services/mid/high_risk_check_tool.py`
- **验收标准**:
  - 只使用 field_roles 包含 routing_signal 的字段
  - 路由判断逻辑正确

### Task 3.4: 改造 template_engine
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-14
- **描述**: 改造模板引擎，只消费 prompt_var 角色
- **产出**:
  - 修改 `ai-service/app/services/flow/template_engine.py`
- **验收标准**:
  - 只使用 field_roles 包含 prompt_var 的字段
  - 模板渲染正确

---

## Phase 4: 前端页面改造

### Task 4.1: 元数据字段配置页面增加 field_roles
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-15
- **描述**: 在元数据字段编辑表单中增加角色选择组件
- **产出**:
  - 创建 `ai-service-admin/src/components/metadata/FieldRolesSelector.vue`
  - 修改 `ai-service-admin/src/views/admin/metadata-schema/index.vue`
- **验收标准**:
  - 支持多选角色
  - 显示角色说明
  - 保存时正确提交

### Task 4.2: 增加按角色过滤视图
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-06
- **描述**: 在元数据字段列表页面增加角色过滤功能
- **产出**:
  - 修改 `ai-service-admin/src/views/admin/metadata-schema/index.vue`
- **验收标准**:
  - 下拉框选择角色
  - 过滤结果正确

### Task 4.3: 槽位定义管理页面
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-07, AC-MRS-08, AC-MRS-16
- **描述**: 创建槽位定义管理页面
- **产出**:
  - 创建 `ai-service-admin/src/views/admin/slot-definition/index.vue`
  - 创建 `ai-service-admin/src/api/slot-definition.ts`
  - 创建 `ai-service-admin/src/types/slot-definition.ts`
  - 更新 `ai-service-admin/src/router/index.ts`
  - 更新 `ai-service-admin/src/App.vue` 导航菜单
- **验收标准**:
  - 支持 CRUD 操作
  - 支持关联元数据字段

---

## Phase 5: 测试与验收

### Task 5.1: 单元测试
- [x] **状态**: ✅ 已完成
- **AC**: AC-MRS-01~16
- **描述**: 编写单元测试
- **产出**:
  - `ai-service/tests/test_role_based_field_provider.py`
  - `ai-service/tests/test_slot_definition_service.py`
  - `ai-service/tests/test_field_roles.py`
- **验收标准**:
  - 覆盖核心逻辑
  - 测试通过

### Task 5.2: 集成测试
- [ ] **状态**: ⏳ 待开始
- **AC**: AC-MRS-01~16
- **描述**: 编写 API 集成测试
- **产出**:
  - `ai-service/tests/api/test_metadata_field_roles.py`
  - `ai-service/tests/api/test_slot_definition.py`
- **验收标准**:
  - 覆盖所有 API 端点
  - 测试通过

### Task 5.3: 契约测试
- [ ] **状态**: ⏳ 待开始
- **AC**: AC-MRS-01~16
- **描述**: 验证 API 符合 OpenAPI 契约
- **产出**:
  - 运行契约测试
  - 修复不一致
- **验收标准**:
  - Provider 契约达到 L2 级别
  - 所有响应符合 Schema

---

## 任务依赖关系

```
Phase 1 (数据模型)
    │
    ├── Task 1.1 (扩展 MetadataFieldDefinition)
    ├── Task 1.2 (创建 SlotDefinition)
    ├── Task 1.3 (迁移脚本) ← 依赖 1.1, 1.2
    └── Task 1.4 (更新 Schema) ← 依赖 1.1, 1.2
            │
            ▼
Phase 2 (后端服务)
    │
    ├── Task 2.1 (RoleBasedFieldProvider) ← 依赖 1.4
    ├── Task 2.2 (扩展 MetadataFieldService) ← 依赖 1.4
    ├── Task 2.3 (SlotDefinitionService) ← 依赖 1.4
    ├── Task 2.4 (扩展 MetadataField API) ← 依赖 2.2
    ├── Task 2.5 (SlotDefinition API) ← 依赖 2.3
    └── Task 2.6 (运行时槽位 API) ← 依赖 2.1, 2.3
            │
            ▼
Phase 3 (工具改造)
    │
    ├── Task 3.1 (kb_search_dynamic) ← 依赖 2.1
    ├── Task 3.2 (memory_recall) ← 依赖 2.1
    ├── Task 3.3 (intent_hint/high_risk_check) ← 依赖 2.1
    └── Task 3.4 (template_engine) ← 依赖 2.1
            │
            ▼
Phase 4 (前端改造)
    │
    ├── Task 4.1 (field_roles 组件) ← 依赖 2.4
    ├── Task 4.2 (角色过滤视图) ← 依赖 2.4
    └── Task 4.3 (槽位定义页面) ← 依赖 2.5
            │
            ▼
Phase 5 (测试验收)
    │
    ├── Task 5.1 (单元测试) ← 依赖 Phase 2
    ├── Task 5.2 (集成测试) ← 依赖 Phase 2, 3, 4
    └── Task 5.3 (契约测试) ← 依赖 5.2
```

---

## 执行顺序建议

1. **Phase 1** → **Phase 2** → **Phase 3** → **Phase 4** → **Phase 5**
2. Phase 3 和 Phase 4 可并行执行
3. 每个 Task 完成后需更新状态并提交

---

## 变更记录

| 日期 | 变更内容 | 变更人 |
|------|---------|-------|
| 2026-03-05 | 初始创建 | AI Agent |
| 2026-03-05 | 完成 Phase 3 工具协同改造 (Task 3.1-3.4) [AC-MRS-11~14] | AI Agent |
| 2026-03-05 | 完成 Phase 4 前端页面改造 (Task 4.1-4.3) [AC-MRS-06,07,08,15,16] | AI Agent |
| 2026-03-05 | 完成 Phase 2 后端服务实现 (Task 2.3-2.6) [AC-MRS-07~10,16] | AI Agent |
| 2026-03-05 | 完成 Task 5.1 单元测试 [AC-MRS-01~16] | AI Agent |