feat: extend MetadataFieldDefinitionService with field_roles support [AC-MRS-01,02,03,06]

ai-service/app/services/metadata_field_definition_service.py

@@ -1,6 +1,7 @@
 """
 Metadata Field Definition Service.
 [AC-IDSMETA-13, AC-IDSMETA-14] 元数据字段定义管理服务，支持字段级状态治理。
+[AC-MRS-01, AC-MRS-02, AC-MRS-03, AC-MRS-06] 支持字段角色分层配置。
 """
 
 import logging
@@ -21,7 +22,9 @@ from app.models.entities import (
     MetadataFieldStatus,
     MetadataFieldType,
     MetadataScope,
+    FieldRole,
 )
+from app.schemas.metadata import VALID_FIELD_ROLES
 
 logger = logging.getLogger(__name__)
 
@@ -42,14 +45,16 @@ class MetadataFieldDefinitionService:
         tenant_id: str,
         status: str | None = None,
         scope: str | None = None,
+        role: str | None = None,
     ) -> list[MetadataFieldDefinition]:
         """
-        [AC-IDSMETA-13] 列出租户所有元数据字段定义
+        [AC-IDSMETA-13] [AC-MRS-06] 列出租户所有元数据字段定义
         
         Args:
             tenant_id: 租户 ID
             status: 按状态过滤（draft/active/deprecated）
             scope: 按适用范围过滤
+            role: [AC-MRS-06] 按字段角色过滤
         
         Returns:
             MetadataFieldDefinition 列表
@@ -66,6 +71,11 @@ class MetadataFieldDefinitionService:
                 cast(MetadataFieldDefinition.scope, JSONB).op('?')(scope)
             )
         
+        if role:
+            stmt = stmt.where(
+                cast(MetadataFieldDefinition.field_roles, JSONB).op('?')(role)
+            )
+        
         stmt = stmt.order_by(col(MetadataFieldDefinition.created_at).desc())
         
         result = await self._session.execute(stmt)
@@ -121,7 +131,7 @@ class MetadataFieldDefinitionService:
         field_create: MetadataFieldDefinitionCreate,
     ) -> MetadataFieldDefinition:
         """
-        [AC-IDSMETA-13] 创建元数据字段定义
+        [AC-IDSMETA-13] [AC-MRS-01,02,03] 创建元数据字段定义
         
         Args:
             tenant_id: 租户 ID
@@ -149,6 +159,8 @@ class MetadataFieldDefinitionService:
             field_create.field_key,
         )
         
+        self._validate_field_roles(field_create.field_roles)
+        
         field = MetadataFieldDefinition(
             tenant_id=tenant_id,
             field_key=field_create.field_key,
@@ -160,6 +172,7 @@ class MetadataFieldDefinitionService:
             scope=field_create.scope,
             is_filterable=field_create.is_filterable,
             is_rank_feature=field_create.is_rank_feature,
+            field_roles=field_create.field_roles or [],
             status=field_create.status,
             version=1,
         )
@@ -168,8 +181,8 @@ class MetadataFieldDefinitionService:
         await self._session.flush()
         
         logger.info(
-            f"[AC-IDSMETA-13] Created field definition: tenant={tenant_id}, "
-            f"field_key={field.field_key}, status={field.status}"
+            f"[AC-IDSMETA-13] [AC-MRS-01] Created field definition: tenant={tenant_id}, "
+            f"field_key={field.field_key}, status={field.status}, field_roles={field.field_roles}"
         )
         
         return field
@@ -437,6 +450,28 @@ class MetadataFieldDefinitionService:
                     f"字段 '{field_key}' 的 options 存在重复值"
                 )
 
+    def _validate_field_roles(
+        self,
+        field_roles: list[str] | None,
+    ) -> None:
+        """
+        [AC-MRS-01,02,03] 验证字段角色配置的有效性
+        
+        Args:
+            field_roles: 字段角色列表
+        
+        Raises:
+            ValueError: 如果包含无效的字段角色
+        """
+        if not field_roles:
+            return
+        
+        for role in field_roles:
+            if role not in VALID_FIELD_ROLES:
+                raise ValueError(
+                    f"无效的字段角色 '{role}'，有效角色为: {VALID_FIELD_ROLES}"
+                )
+
     async def get_field_definitions_map(
         self,
         tenant_id: str,