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

feature_id	title	status	version	active_version	version_history	owners	last_updated	source
MRS	元数据职责分层优化	draft	0.1.0	0.1.0	version ac_range description 0.1.0 AC-MRS-01~16 元数据字段职责分层、槽位模型独立化、工具协同改造与管理端配置能力	product backend frontend	2026-03-05	type ref conversation 元数据职责过载问题优化需求

元数据职责分层优化（MRS）

1. 背景与目标

1.1 背景

当前系统中元数据字段承担了多种隐式职责，导致以下问题：

1. 职责混淆：同一字段（如 grade）同时用于资源过滤、运行时槽位、提示词变量和路由信号，但系统无法区分其具体用途
2. 工具耦合：kb_search_dynamic、memory_recall、intent_hint、high_risk_check 等工具全量消费元数据字段，无法按需筛选
3. 槽位语义模糊：槽位与元数据字段概念混淆，缺少独立的槽位定义模型
4. 配置不可视：管理端无法按职责视角查看和配置字段

1.2 目标

• 为元数据字段引入显式的 field_roles 职责分层
• 建立独立的槽位定义模型，与元数据字段解耦但可复用
• 改造工具链按职责角色消费字段，实现精准消费
• 提供管理端按角色配置和查看的能力

1.3 非目标（Out of Scope）

• 不处理历史数据迁移，允许删除重建配置
• 不新增元数据字段类型（保持 string/number/boolean/enum/array_enum）
• 不替换向量引擎或 LLM 供应商
• 不覆盖渠道端具体实现

2. 模块边界（Scope）

• 覆盖：元数据字段职责分层、槽位定义模型、工具协同改造、管理端配置能力
• 不覆盖：历史数据迁移、向量引擎替换、模型切换、渠道端实现

3. 依赖盘点（Dependencies）

• metadata-governance 模块：元数据字段定义基础能力
• intent-driven-mid-platform 模块：中台运行时工具链
• ai-service-admin 前端：管理端配置界面

4. 用户故事（User Stories）

• [US-MRS-01] 作为系统架构师，我希望元数据字段有明确的职责角色标记，以便工具能按需消费。
• [US-MRS-02] 作为后端开发者，我希望通过接口按角色查询字段定义，以便精准获取所需字段。
• [US-MRS-03] 作为运营配置人员，我希望在管理端按角色过滤查看字段，以便快速定位配置。
• [US-MRS-04] 作为对话系统开发者，我希望槽位有独立的定义模型，以便管理运行时槽位语义。
• [US-MRS-05] 作为工具开发者，我希望 kb_search_dynamic 只消费资源过滤角色字段，以便避免无关字段干扰。
• [US-MRS-06] 作为工具开发者，我希望 memory_recall 只消费槽位角色字段，以便精准管理对话槽位。
• [US-MRS-07] 作为工具开发者，我希望 intent_hint/high_risk_check 只消费路由信号角色字段，以便精准路由决策。
• [US-MRS-08] 作为提示词工程师，我希望 prompt 渲染只消费提示词变量角色字段，以便控制注入范围。

5. 验收标准（Acceptance Criteria, EARS）

5.1 字段职责分层

• [AC-MRS-01] WHEN 管理员创建或编辑元数据字段 THEN 系统 SHALL 支持 field_roles 多选配置，可选值为 resource_filter、slot、prompt_var、routing_signal。
• [AC-MRS-02] WHEN 保存字段定义时 field_roles 为空 THEN 系统 SHALL 允许保存（默认无职责）。
• [AC-MRS-03] WHEN 字段定义包含多个 field_roles THEN 系统 SHALL 正确存储并返回所有角色。

5.2 分层视图能力

• [AC-MRS-04] WHEN 调用 GET /admin/metadata-schemas/by-role?role=resource_filter THEN 系统 SHALL 返回所有 field_roles 包含 resource_filter 的活跃字段定义。
• [AC-MRS-05] WHEN 调用按角色查询接口且角色参数无效 THEN 系统 SHALL 返回 400 错误并提示有效角色列表。
• [AC-MRS-06] WHEN 管理端请求字段列表 THEN 系统 SHALL 支持按 field_roles 过滤展示。

5.3 槽位模型

• [AC-MRS-07] WHEN 管理员创建槽位定义 THEN 系统 SHALL 支持 slot_key、type、required、extract_strategy、validation_rule、ask_back_prompt 属性配置。
• [AC-MRS-08] WHEN 槽位定义的 slot_key 与已有元数据字段 field_key 相同 THEN 系统 SHALL 允许创建并建立关联关系。
• [AC-MRS-09] WHEN 运行时读取槽位值 THEN 系统 SHALL 返回 source（来源）、confidence（置信度）、updated_at（更新时间）属性。
• [AC-MRS-10] WHEN 调用 GET /mid/slots/by-role?role=slot THEN 系统 SHALL 返回所有 field_roles 包含 slot 的字段定义及关联的槽位定义。

5.4 工具协同改造

• [AC-MRS-11] WHEN kb_search_dynamic 构建过滤器 THEN 系统 SHALL 仅使用 field_roles 包含 resource_filter 的字段。
• [AC-MRS-12] WHEN memory_recall 召回槽位 THEN 系统 SHALL 仅使用 field_roles 包含 slot 的字段。
• [AC-MRS-13] WHEN intent_hint 或 high_risk_check 进行路由判断 THEN 系统 SHALL 仅使用 field_roles 包含 routing_signal 的字段。
• [AC-MRS-14] WHEN 模板引擎渲染 prompt THEN 系统 SHALL 仅使用 field_roles 包含 prompt_var 的字段。

5.5 管理端可配置能力

• [AC-MRS-15] WHEN 管理员在元数据字段编辑界面 THEN 系统 SHALL 显示 field_roles 多选配置组件。
• [AC-MRS-16] WHEN 管理员删除字段或槽位定义 THEN 系统 SHALL 允许删除且无需考虑历史数据兼容性。

6. 追踪映射（Traceability）

AC ID	Endpoint	方法	operationId	备注
AC-MRS-01	/admin/metadata-schemas	POST	createMetadataSchema	field_roles 配置
AC-MRS-01	/admin/metadata-schemas/{id}	PUT	updateMetadataSchema	field_roles 配置
AC-MRS-02	/admin/metadata-schemas	POST	createMetadataSchema	空角色允许
AC-MRS-03	/admin/metadata-schemas	POST	createMetadataSchema	多角色存储
AC-MRS-04	/admin/metadata-schemas/by-role	GET	getMetadataSchemasByRole	按角色查询
AC-MRS-05	/admin/metadata-schemas/by-role	GET	getMetadataSchemasByRole	无效角色校验
AC-MRS-06	/admin/metadata-schemas	GET	listMetadataSchemas	按角色过滤
AC-MRS-07	/admin/slot-definitions	POST	createSlotDefinition	槽位定义创建
AC-MRS-08	/admin/slot-definitions	POST	createSlotDefinition	关联元数据字段
AC-MRS-09	/mid/slots/{slot_key}	GET	getSlotValue	运行时槽位值
AC-MRS-10	/mid/slots/by-role	GET	getSlotsByRole	按角色获取槽位
AC-MRS-11	内部调用	-	kb_search_dynamic	resource_filter 消费
AC-MRS-12	内部调用	-	memory_recall	slot 消费
AC-MRS-13	内部调用	-	intent_hint/high_risk_check	routing_signal 消费
AC-MRS-14	内部调用	-	template_engine	prompt_var 消费
AC-MRS-15	前端页面	-	-	field_roles 配置组件
AC-MRS-16	/admin/metadata-schemas/{id}	DELETE	deleteMetadataSchema	删除无需兼容
AC-MRS-16	/admin/slot-definitions/{id}	DELETE	deleteSlotDefinition	删除无需兼容

7. 字段角色定义

角色标识	中文名称	用途说明	消费工具
resource_filter	资源过滤	用于 KB 文档检索时的元数据过滤	kb_search_dynamic
slot	运行时槽位	对话流程中的结构化槽位，用于信息收集	memory_recall
prompt_var	提示词变量	注入到 LLM Prompt 中的变量	template_engine
routing_signal	路由信号	用于意图路由和风险判断的信号	intent_hint, high_risk_check

8. 槽位定义属性

属性	类型	必填	说明
slot_key	string	是	槽位键名，可与 field_key 关联
type	enum	是	槽位类型：string/number/boolean/enum/array_enum
required	boolean	是	是否必填槽位
extract_strategy	enum	否	提取策略：rule/llm/user_input
validation_rule	string	否	校验规则（正则或 JSON Schema）
ask_back_prompt	string	否	追问提示语模板
default_value	any	否	默认值
linked_field_id	uuid	否	关联的元数据字段 ID

9. 运行时槽位值属性

属性	类型	说明
key	string	槽位键名
value	any	槽位值
source	enum	来源：user_confirmed/rule_extracted/llm_inferred/default
confidence	float	置信度 0.0~1.0
updated_at	datetime	最后更新时间