feat(kb): entity store with lifecycle, graph traversal and color palette

12 类实体统一表 + 状态机 + version 递增 + kb_relation 递归 CTE 1~3 跳可解释路径（防环）+ kb_color 色板（T-P2-01/05，TD-09/18）。实现： - packages/kb/schemas.py：12 类 EntityType 与状态 Literal 校验、 EntityCreate/Update/Out、RelationCreate、GraphNode/Hop/Path/QueryResult、 ColorOut；雪花 ID 全部字符串出参（JS 精度）。 - packages/kb/repo.py：实体 CRUD/按名查重/过滤分页搜索；traverse 递归 CTE（path 数组 + NOT @> 防环，锚点与递归段 varchar[] 显转型）；色板读写。 - packages/kb/service.py：状态机矩阵（draft→reviewing→published→archived + draft/reviewing→archived 撤稿，非法跃迁 40900，矩阵单测 16 组全覆盖）、内容修改仅 draft/reviewing 且 version+1、published 只读；关系写入（自环/三元组重复 400、端点缺失 404）；色板 role/hex(#RRGGBB) 校验。 - apps/api/routers/kb.py：GET/POST /kb/items、GET/PATCH /kb/items/{id}、 GET /kb/items/{id}/graph?max_hops=1..3（超界 422）；KbService 装配就近放路由文件（apps/api/deps.py 本轮禁改）。测试：单测 77 例（跃迁矩阵、12 类 Literal、非法类型拒绝、hex/role/hops 校验）；集成 5 例（真实 PG：生命周期/改 published 被拒/版本递增、关系约束、2 跳可解释路径+防环、列表过滤分页、色板读写）。全套门禁绿： ruff check/format、mypy（指定包列表）、lint-imports、单测 315 通过、集成 21 通过。偏差说明： 1. 新增 tests/unit/__init__.py 与 tests/integration/__init__.py（仅注释的包标记）：任务文档要求单测/集成同名 test_kb_entity.py，pytest prepend 导入模式按 basename 注册模块会撞名，加包标记唯一化。 2. 关系与色板未挂 HTTP 路由：文档 §3.4 路由清单仅列 items+graph，录入入口属运营后台 T-P2-09，本批在 service 层落地并集成直连验证。 3. published→draft 按文档字面矩阵（其余跃迁非法）拦为 40900：改已发布内容的既定路径是撤稿归档后重录新草稿（错误 hint 已说明），未私开回退通道。
2026-08-14 20:09:12 +08:00
parent d5f366fa4c
commit d9249400af
10 changed files with 1499 additions and 10 deletions
@@ -0,0 +1,392 @@
+"""kb 域 service：实体生命周期、关系写入、图谱遍历、自建色板（FR-KB-01/02/05）.
+
+状态机与格式校验拆成模块级纯函数（不碰 DB，单测直接覆盖矩阵）；
+``KbService`` 只负责组装、落库与跨表编排。所有写操作只 ``flush`` 不
+``commit``——事务边界交给 ``session_dep`` 的统一提交/回滚，与 task /
+billing 域一致。
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from decimal import Decimal
+
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from packages.domain.ids import next_id
+from packages.kb import repo
+from packages.kb.schemas import (
+    MAX_GRAPH_HOPS,
+    ColorOut,
+    EntityCreate,
+    EntityUpdate,
+    GraphHop,
+    GraphNode,
+    GraphPath,
+    GraphQueryResult,
+    RelationCreate,
+)
+from packages.shared.errors import AppError, ErrorCode, NotFoundError
+from packages.shared.logging import get_logger
+from packages.shared.models import KbColor, KbEntity, KbRelation
+
+logger = get_logger(__name__)
+
+#: 合法跃迁矩阵（知识库文档「发布回滚」语义）：
+#:   draft → reviewing → published → archived 主线；
+#:   draft/reviewing → archived 撤稿支线；
+#:   archived 终态。其余（含 published→draft、reviewing→draft、自跃迁）
+#:   一律非法——想改已发布内容，就撤稿归档后以新草稿重录，让新版本重走评审。
+LEGAL_TRANSITIONS: frozenset[tuple[str, str]] = frozenset(
+    {
+        ("draft", "reviewing"),
+        ("reviewing", "published"),
+        ("published", "archived"),
+        ("draft", "archived"),
+        ("reviewing", "archived"),
+    }
+)
+
+#: 内容可编辑的状态。published 内容只读（版本语义的基石），archived 终态。
+CONTENT_EDITABLE_STATUSES: frozenset[str] = frozenset({"draft", "reviewing"})
+
+_HEX_COLOR_PATTERN = re.compile(r"^#[0-9A-Fa-f]{6}$")
+_COLOR_ROLES: frozenset[str] = frozenset({"base", "accent", "avoid"})
+
+
+# --- 纯校验函数（单测直接覆盖，不触碰 DB） ----------------------------------
+
+
+def can_transition(current: str, target: str) -> bool:
+    return (current, target) in LEGAL_TRANSITIONS
+
+
+def assert_transition(current: str, target: str) -> None:
+    """非法跃迁 → ``STATE_CONFLICT``（409）。矩阵见 :data:`LEGAL_TRANSITIONS`。"""
+    if not can_transition(current, target):
+        raise AppError(
+            ErrorCode.STATE_CONFLICT,
+            message="实体状态不允许该跃迁",
+            data={"current": current, "target": target},
+        )
+
+
+def ensure_content_editable(status: str) -> None:
+    """published/archived 的内容不可直接修改（version 递增的前提）。"""
+    if status not in CONTENT_EDITABLE_STATUSES:
+        raise AppError(
+            ErrorCode.STATE_CONFLICT,
+            message=f"{status} 状态的实体内容不可修改",
+            hint="已发布内容要改：先撤稿归档，再以新草稿重录，新版本重走评审",
+            data={"status": status},
+        )
+
+
+def ensure_valid_hex(hex_code: str) -> None:
+    """色板 hex 必须 ``#RRGGBB``（大小写不敏感，入库前不归一化，展示原样保留）。"""
+    if _HEX_COLOR_PATTERN.fullmatch(hex_code) is None:
+        raise AppError(
+            ErrorCode.BAD_REQUEST,
+            message="色板 hex 格式非法，应为 #RRGGBB",
+            data={"hex": hex_code},
+        )
+
+
+def ensure_valid_color_role(role: str) -> None:
+    if role not in _COLOR_ROLES:
+        raise AppError(
+            ErrorCode.BAD_REQUEST,
+            message="色板 role 非法，应为 base/accent/avoid",
+            data={"role": role},
+        )
+
+
+def ensure_valid_hops(max_hops: int) -> None:
+    """遍历深度 1~3（TD-09 有界遍历；上限同时也是防环的保险丝）。"""
+    if not 1 <= max_hops <= MAX_GRAPH_HOPS:
+        raise AppError(
+            ErrorCode.BAD_REQUEST,
+            message=f"max_hops 超出允许范围 1~{MAX_GRAPH_HOPS}",
+            data={"max_hops": max_hops},
+        )
+
+
+# --- service -----------------------------------------------------------------
+
+
+class KbService:
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    # -- 实体 -----------------------------------------------------------------
+
+    async def create_entity(
+        self, *, payload: EntityCreate, updated_by: str | None = None
+    ) -> KbEntity:
+        """新建实体：固定 draft / version=1 起步。同名同类目拒绝（400）。"""
+        existing = await repo.find_entity_by_name(
+            self._session, entity_type=payload.entity_type, name=payload.name
+        )
+        if existing is not None:
+            raise AppError(
+                ErrorCode.BAD_REQUEST,
+                message="同名同类目的实体已存在",
+                data={"entity_type": payload.entity_type, "name": payload.name},
+            )
+        entity = repo.add_entity(
+            self._session,
+            KbEntity(
+                entity_id=next_id(),
+                entity_type=payload.entity_type,
+                name=payload.name,
+                attrs=payload.attrs,
+                status="draft",
+                version=1,
+                source=payload.source,
+                license=payload.license,
+                updated_by=updated_by,
+            ),
+        )
+        try:
+            await self._session.flush()
+        except IntegrityError as exc:
+            # 并发同名是唯一预期内的约束冲突（UNIQUE(entity_type,name) 兜底）
+            raise AppError(
+                ErrorCode.BAD_REQUEST,
+                message="同名同类目的实体已存在",
+                data={"entity_type": payload.entity_type, "name": payload.name},
+            ) from exc
+        logger.info(
+            "kb_entity_created",
+            entity_id=entity.entity_id,
+            entity_type=entity.entity_type,
+            name=entity.name,
+        )
+        return entity
+
+    async def get_entity(self, *, entity_id: int) -> KbEntity:
+        entity = await repo.get_entity(self._session, entity_id)
+        if entity is None:
+            raise NotFoundError("实体不存在")
+        return entity
+
+    async def search_entities(
+        self,
+        *,
+        entity_type: str | None = None,
+        status: str | None = None,
+        name_ilike: str | None = None,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> tuple[list[KbEntity], int]:
+        return await repo.search_entities(
+            self._session,
+            entity_type=entity_type,
+            status=status,
+            name_ilike=name_ilike,
+            limit=limit,
+            offset=offset,
+        )
+
+    async def update_entity(
+        self, *, entity_id: int, payload: EntityUpdate, updated_by: str | None = None
+    ) -> KbEntity:
+        """内容修改与状态跃迁共用一个 PATCH 入口，规则：
+
+        - 内容字段仅 draft/reviewing 可改，每次内容修改 version+1；
+        - 状态变化必须走合法跃迁矩阵；与当前相同的 status 是幂等 no-op；
+        - 先全部校验、后统一变更——半个请求不会落库。
+        """
+        entity = await repo.get_entity_for_update(self._session, entity_id)
+        if entity is None:
+            raise NotFoundError("实体不存在")
+
+        content = payload.content_fields()
+        if content:
+            ensure_content_editable(entity.status)
+        if payload.status is not None and payload.status != entity.status:
+            assert_transition(entity.status, payload.status)
+
+        if content:
+            for field, value in content.items():
+                setattr(entity, field, value)
+            entity.version += 1
+        if payload.status is not None:
+            entity.status = payload.status
+        if content or payload.status is not None:
+            entity.updated_by = updated_by or entity.updated_by
+            entity.updated_at = datetime.now(UTC)
+            try:
+                await self._session.flush()
+            except IntegrityError as exc:
+                # 改名撞上另一条同类目实体
+                raise AppError(
+                    ErrorCode.BAD_REQUEST,
+                    message="同名同类目的实体已存在",
+                    data={"entity_id": str(entity_id)},
+                ) from exc
+            logger.info(
+                "kb_entity_updated",
+                entity_id=entity_id,
+                version=entity.version,
+                status=entity.status,
+                content_changed=bool(content),
+            )
+        return entity
+
+    # -- 关系 -----------------------------------------------------------------
+
+    async def add_relation(self, *, payload: RelationCreate) -> KbRelation:
+        """写入三元组。自环与重复（UNIQUE 三元组）拒绝（400），端点缺失 404。"""
+        if payload.from_entity_id == payload.to_entity_id:
+            raise AppError(
+                ErrorCode.BAD_REQUEST,
+                message="不允许自环关系",
+                data={"entity_id": str(payload.from_entity_id)},
+            )
+        for end_id in (payload.from_entity_id, payload.to_entity_id):
+            if await repo.get_entity(self._session, end_id) is None:
+                raise NotFoundError("关联实体不存在")
+        duplicate = await repo.find_relation(
+            self._session,
+            from_id=payload.from_entity_id,
+            rel_type=payload.rel_type,
+            to_id=payload.to_entity_id,
+        )
+        if duplicate is not None:
+            raise AppError(
+                ErrorCode.BAD_REQUEST,
+                message="该 from/rel_type/to 三元组已存在",
+                data={
+                    "from_entity_id": str(payload.from_entity_id),
+                    "rel_type": payload.rel_type,
+                    "to_entity_id": str(payload.to_entity_id),
+                },
+            )
+        relation = repo.add_relation(
+            self._session,
+            KbRelation(
+                relation_id=next_id(),
+                from_id=payload.from_entity_id,
+                rel_type=payload.rel_type,
+                to_id=payload.to_entity_id,
+                weight=payload.weight,
+                confidence=payload.confidence,
+                evidence=payload.evidence,
+            ),
+        )
+        await self._session.flush()
+        logger.info(
+            "kb_relation_added",
+            from_id=payload.from_entity_id,
+            rel_type=payload.rel_type,
+            to_id=payload.to_entity_id,
+        )
+        return relation
+
+    # -- 图谱 -----------------------------------------------------------------
+
+    async def traverse_graph(
+        self, *, entity_id: int, max_hops: int = MAX_GRAPH_HOPS
+    ) -> GraphQueryResult:
+        """1~3 跳可解释路径（T-P2-05）。
+
+        CTE 只回 id 与 rel_type 序列；节点摘要（类型/名称/状态）由第二次
+        查询补齐——遍历有界，涉及的实体集合很小，两次往返远比在递归 SQL
+        里 JOIN 实体表好维护。
+        """
+        ensure_valid_hops(max_hops)
+        await self.get_entity(entity_id=entity_id)  # 起点 404 语义保持一致
+
+        raw_paths = await repo.traverse(self._session, from_id=entity_id, max_hops=max_hops)
+        node_ids: set[int] = set()
+        for raw in raw_paths:
+            node_ids.update(raw.node_ids)
+        nodes_map = await repo.get_entities_by_ids(self._session, node_ids)
+
+        paths: list[GraphPath] = []
+        for raw in raw_paths:
+            nodes = [_node_summary(nodes_map, node_id) for node_id in raw.node_ids]
+            hops = [
+                GraphHop(
+                    from_entity_id=str(hop_from),
+                    rel_type=rel_type,
+                    to_entity_id=str(hop_to),
+                )
+                # node_ids 比 rel_types 多一个元素（n 个节点 n-1 跳），首尾
+                # 错位 zip 即得「第 i 跳 = nodes[i] --rels[i]--> nodes[i+1]」
+                for hop_from, rel_type, hop_to in zip(
+                    raw.node_ids[:-1], raw.rel_types, raw.node_ids[1:], strict=True
+                )
+            ]
+            paths.append(GraphPath(nodes=nodes, hops=hops))
+        return GraphQueryResult(from_entity_id=str(entity_id), max_hops=max_hops, paths=paths)
+
+    # -- 色板（TD-18 自建色板） ------------------------------------------------
+
+    async def add_color(
+        self,
+        *,
+        season_code: str,
+        role: str,
+        lab_l: float,
+        lab_a: float,
+        lab_b: float,
+        hex_code: str,
+        name_cn: str,
+    ) -> ColorOut:
+        """录入色板条目。role/hex 校验在 service 层（运营后台 T-P2-09 直接复用）。"""
+        ensure_valid_color_role(role)
+        ensure_valid_hex(hex_code)
+        color = repo.add_color(
+            self._session,
+            KbColor(
+                color_id=next_id(),
+                season_code=season_code,
+                role=role,
+                lab_l=Decimal(str(lab_l)),
+                lab_a=Decimal(str(lab_a)),
+                lab_b=Decimal(str(lab_b)),
+                hex=hex_code,
+                name_cn=name_cn,
+            ),
+        )
+        await self._session.flush()
+        logger.info("kb_color_added", season_code=season_code, role=role, hex=hex_code)
+        return _color_out(color)
+
+    async def list_colors(self, *, season_code: str | None = None) -> list[ColorOut]:
+        rows = await repo.list_colors(self._session, season_code=season_code)
+        return [_color_out(row) for row in rows]
+
+
+def _node_summary(nodes_map: dict[int, KbEntity], node_id: int) -> GraphNode:
+    """路径节点摘要。关系端点在写入时校验过存在，理论必中；万一实体行
+    被运维手工删除，退化为占位摘要而不是让整个图查询 500。"""
+    entity = nodes_map.get(node_id)
+    if entity is None:
+        logger.warning("kb_graph_node_missing", entity_id=node_id)
+        return GraphNode(
+            entity_id=str(node_id), entity_type="unknown", name="unknown", status="unknown"
+        )
+    return GraphNode(
+        entity_id=str(entity.entity_id),
+        entity_type=entity.entity_type,
+        name=entity.name,
+        status=entity.status,
+    )
+
+
+def _color_out(color: KbColor) -> ColorOut:
+    return ColorOut(
+        color_id=str(color.color_id),
+        season_code=color.season_code,
+        role=color.role,
+        lab_l=float(color.lab_l),
+        lab_a=float(color.lab_a),
+        lab_b=float(color.lab_b),
+        hex=color.hex,
+        name_cn=color.name_cn,
+    )