"""知识域接口（M3）：草稿、审议、发布、归档，以及"从事项沉淀"。 一条知识的一生： 工单验收通过（或你手动点"沉淀成知识"） -> draft 草稿：系统整理好了，等你核对 -> in_review 提交审议：让同事看一遍（可选） -> published 发布：进团队检索、能被问答引用 -> archived 归档：不删，退出检索（历史结论不该消失） 为什么要 `draft` 这一步：自动整理的东西一定有"看着像那么回事、其实漏了前提"的情况， 让人扫一眼的成本远低于让整个团队按错的结论办事。发布权收紧到 owner/admin 也是同理—— 发布等于团队背书。 """ from __future__ import annotations import uuid from datetime import datetime, timezone from typing import Annotated, Any from fastapi import APIRouter, Query from pydantic import BaseModel, Field from sqlalchemy import Select, and_, func, or_, select, update from sqlalchemy.ext.asyncio import AsyncSession from ..audit import record as audit_record from ..deps import MemberDep, SessionDep from ..domain.knowledge import can_publish_role, sidebar_fields, target_status from ..errors import AppError, ErrorCode from ..models_knowledge import ( DOC_TYPES, KNOWLEDGE_STATUSES, MAX_CATEGORY_DEPTH, KnowledgeCategory, KnowledgeDoc, ) from ..models_task import Activity, Item, ItemTag, Tag from ..schemas import clamp_limit, decode_cursor, encode_cursor, ok from ..serializers import item_out, tags_of from ..services.knowledge import create_draft_from_source, find_doc_by_source from ..services.knowledge_index import reindex_document, search_knowledge from .attachments import count_for_items, list_for_item router = APIRouter(prefix="/workspaces/{ws_id}", tags=["知识库"]) # ── 入参 ──────────────────────────────────────────────────────────────── class KnowledgeIn(BaseModel): title: str = Field(min_length=1, max_length=200) body_md: str = "" summary: str = Field(default="", max_length=2000) doc_type: str = "note" source_item_id: uuid.UUID | None = None tag_names: list[str] = Field(default_factory=list) category_id: uuid.UUID | None = None class KnowledgePatch(BaseModel): title: str | None = Field(default=None, min_length=1, max_length=200) body_md: str | None = None summary: str | None = None doc_type: str | None = None tag_names: list[str] | None = None category_id: uuid.UUID | None = None # 单独一个开关：`category_id=None` 既可能表示"没改"，也可能表示"清空分类"， # 靠 pydantic 的未传/传 null 区分太隐晦，不如显式给一个。 clear_category: bool = False version: int class CategoryIn(BaseModel): name: str = Field(min_length=1, max_length=40) parent_id: uuid.UUID | None = None sort_order: int = 0 class CategoryPatch(BaseModel): name: str | None = Field(default=None, min_length=1, max_length=40) parent_id: uuid.UUID | None = None move: bool = False sort_order: int | None = None version: int class StatusActionIn(BaseModel): action: str version: int note: str = "" # ── 内部工具 ──────────────────────────────────────────────────────────── async def _load_doc( session: AsyncSession, ws_id: uuid.UUID, item_id: uuid.UUID ) -> tuple[Item, KnowledgeDoc]: item = await session.get(Item, item_id) doc = await session.get(KnowledgeDoc, item_id) if item is None or doc is None or item.workspace_id != ws_id or item.kind != "knowledge": raise AppError(ErrorCode.KNOWLEDGE_NOT_FOUND, "这份知识不存在") return item, doc async def _log( session: AsyncSession, item: Item, actor_id: uuid.UUID, action: str, payload: dict | None = None ) -> None: session.add( Activity( workspace_id=item.workspace_id, item_id=item.id, actor_id=actor_id, action=action, payload=payload or {}, ) ) async def _source_out( session: AsyncSession, ws_id: uuid.UUID, source_item_id: uuid.UUID | None ) -> dict[str, Any] | None: if source_item_id is None: return None source = await session.get(Item, source_item_id) if source is None or source.workspace_id != ws_id: return None return { "id": str(source.id), "kind": source.kind, "title": source.title, "status": source.status, } def _doc_out(doc: KnowledgeDoc) -> dict[str, Any]: return { "doc_type": doc.doc_type, "summary": doc.summary, "status_hint": doc.status_hint, "source_kind": doc.source_kind, "source_item_id": str(doc.source_item_id) if doc.source_item_id else None, "category_id": str(doc.category_id) if doc.category_id else None, "generated_by": doc.generated_by, "published_at": doc.published_at, "archived_at": doc.archived_at, "chunk_count": doc.chunk_count, "author_id": str(doc.author_id), } # ── 分类 ──────────────────────────────────────────────────────────────── async def _categories( session: AsyncSession, ws_id: uuid.UUID ) -> dict[uuid.UUID, KnowledgeCategory]: """一次把分类全捞出来。分类是工作区级的小字典（几十条），比按需查祖先便宜。""" rows = ( await session.execute( select(KnowledgeCategory).where(KnowledgeCategory.workspace_id == ws_id) ) ).scalars() return {row.id: row for row in rows} def _category_payload( cat: KnowledgeCategory, by_id: dict[uuid.UUID, KnowledgeCategory] ) -> dict[str, Any]: """分类带上完整路径：`研发 / 部署 / 回滚`。客户端不用自己去拼。""" names: list[str] = [] node: KnowledgeCategory | None = cat while node is not None and len(names) < MAX_CATEGORY_DEPTH: names.append(node.name) node = by_id.get(node.parent_id) if node.parent_id else None names.reverse() return { "id": str(cat.id), "parent_id": str(cat.parent_id) if cat.parent_id else None, "name": cat.name, "depth": cat.depth, "sort_order": cat.sort_order, "version": cat.version, "path": names, "full_path": " / ".join(names), } def _subtree_ids(root_id: uuid.UUID, by_id: dict[uuid.UUID, KnowledgeCategory]) -> list[uuid.UUID]: children: dict[uuid.UUID, list[uuid.UUID]] = {} for cat in by_id.values(): if cat.parent_id: children.setdefault(cat.parent_id, []).append(cat.id) out = [root_id] stack = [root_id] while stack: for child in children.get(stack.pop(), []): out.append(child) stack.append(child) return out async def _resolve_category( session: AsyncSession, ws_id: uuid.UUID, category_id: uuid.UUID | None ) -> KnowledgeCategory | None: if category_id is None: return None cat = await session.get(KnowledgeCategory, category_id) if cat is None or cat.workspace_id != ws_id: raise AppError(ErrorCode.KNOWLEDGE_CATEGORY_NOT_FOUND, "这个分类不存在") return cat async def _category_name_taken( session: AsyncSession, ws_id: uuid.UUID, parent_id: uuid.UUID | None, name: str, exclude: uuid.UUID | None = None, ) -> bool: stmt = select(KnowledgeCategory.id).where( KnowledgeCategory.workspace_id == ws_id, func.lower(KnowledgeCategory.name) == name.strip().lower(), ) stmt = ( stmt.where(KnowledgeCategory.parent_id.is_(None)) if parent_id is None else stmt.where(KnowledgeCategory.parent_id == parent_id) ) if exclude is not None: stmt = stmt.where(KnowledgeCategory.id != exclude) return (await session.execute(stmt)).first() is not None async def _knowledge_out( session: AsyncSession, ws_id: uuid.UUID, item: Item, doc: KnowledgeDoc ) -> dict[str, Any]: tags = (await tags_of(session, ws_id, [item.id])).get(item.id, []) data = item_out(item, tags) data["knowledge"] = _doc_out(doc) by_id = await _categories(session, ws_id) cat = by_id.get(doc.category_id) if doc.category_id else None data["category"] = _category_payload(cat, by_id) if cat else None data["source"] = await _source_out(session, ws_id, doc.source_item_id) data["attachments"] = await list_for_item(session, ws_id, item.id) data["attachment_count"] = len(data["attachments"]) return data async def _set_tags_for( session: AsyncSession, ws_id: uuid.UUID, item: Item, names: list[str] ) -> None: from .items import _set_tags await _set_tags(session, ws_id, item, names) # ── 列表 / 详情 ───────────────────────────────────────────────────────── @router.get("/knowledge", summary="知识列表") async def list_knowledge( ctx: MemberDep, session: SessionDep, status: Annotated[list[str] | None, Query()] = None, doc_type: Annotated[str | None, Query()] = None, source_item_id: Annotated[uuid.UUID | None, Query()] = None, category_id: Annotated[uuid.UUID | None, Query(description="含子分类")] = None, uncategorized: Annotated[bool, Query(description="只看未分类")] = False, tag: Annotated[str | None, Query(max_length=32)] = None, q: Annotated[str | None, Query(max_length=100)] = None, limit: Annotated[int, Query(ge=1, le=100, description="每页条数")] = 30, cursor: Annotated[str | None, Query(description="上一页返回的 next_cursor")] = None, ) -> dict: ws_id = ctx.ws_id stmt: Select = ( select(Item, KnowledgeDoc) .join(KnowledgeDoc, KnowledgeDoc.item_id == Item.id) .where(Item.workspace_id == ws_id, Item.kind == "knowledge", Item.deleted_at.is_(None)) ) wanted = [s for s in (status or []) if s in KNOWLEDGE_STATUSES] if wanted: stmt = stmt.where(KnowledgeDoc.status_hint.in_(wanted)) if doc_type: stmt = stmt.where(KnowledgeDoc.doc_type == doc_type) if source_item_id: stmt = stmt.where(KnowledgeDoc.source_item_id == source_item_id) by_id: dict[uuid.UUID, KnowledgeCategory] = {} if uncategorized: stmt = stmt.where(KnowledgeDoc.category_id.is_(None)) elif category_id is not None: by_id = await _categories(session, ws_id) cat = by_id.get(category_id) if cat is None: raise AppError(ErrorCode.KNOWLEDGE_CATEGORY_NOT_FOUND, "这个分类不存在") stmt = stmt.where(KnowledgeDoc.category_id.in_(_subtree_ids(category_id, by_id))) if tag: stmt = ( stmt.join(ItemTag, ItemTag.item_id == Item.id) .join(Tag, Tag.id == ItemTag.tag_id) .where(Tag.workspace_id == ws_id, func.lower(Tag.name) == tag.strip().lower()) ) if q: like = f"%{q.strip()}%" stmt = stmt.where( or_(Item.title.ilike(like), Item.body_md.ilike(like), KnowledgeDoc.summary.ilike(like)) ) if cursor: cur = decode_cursor(cursor) stmt = stmt.where( or_( Item.updated_at < cur.created_at, and_(Item.updated_at == cur.created_at, Item.id < cur.item_id), ) ) limit = clamp_limit(limit) rows = ( await session.execute( stmt.order_by(Item.updated_at.desc(), Item.id.desc()).limit(limit + 1) ) ).all() has_more = len(rows) > limit rows = rows[:limit] tag_map = await tags_of(session, ws_id, [it.id for it, _ in rows]) if not by_id: by_id = await _categories(session, ws_id) items = [] counts = await count_for_items(session, ws_id, [it.id for it, _ in rows]) for item, doc in rows: data = item_out(item, tag_map.get(item.id, [])) data["knowledge"] = _doc_out(doc) cat = by_id.get(doc.category_id) if doc.category_id else None data["category"] = _category_payload(cat, by_id) if cat else None data["source"] = await _source_out(session, ws_id, doc.source_item_id) data["attachment_count"] = counts.get(str(item.id), 0) items.append(data) next_cursor = ( encode_cursor(rows[-1][0].updated_at, rows[-1][0].id) if has_more and rows else None ) return ok({"items": items, "next_cursor": next_cursor, "has_more": has_more}) # ── 分类的增删改查 ────────────────────────────────────────────────────── # 路由顺序：`/knowledge/categories` 必须排在 `/knowledge/{item_id}` 之前， # 否则 "categories" 会被当成 uuid 解析，直接 422。 @router.get("/knowledge/categories", summary="知识分类") async def list_categories(ctx: MemberDep, session: SessionDep) -> dict: by_id = await _categories(session, ctx.ws_id) counts = dict( ( await session.execute( select(KnowledgeDoc.category_id, func.count()) .join(Item, Item.id == KnowledgeDoc.item_id) .where( KnowledgeDoc.workspace_id == ctx.ws_id, KnowledgeDoc.category_id.is_not(None), KnowledgeDoc.status_hint != "archived", Item.deleted_at.is_(None), ) .group_by(KnowledgeDoc.category_id) ) ).all() ) items = [] for cat in sorted(by_id.values(), key=lambda c: (c.depth, c.sort_order, c.name)): data = _category_payload(cat, by_id) data["doc_count"] = counts.get(cat.id, 0) items.append(data) return ok({"items": items, "max_depth": MAX_CATEGORY_DEPTH}) @router.post("/knowledge/categories", summary="新建分类") async def create_category(body: CategoryIn, ctx: MemberDep, session: SessionDep) -> dict: ws_id = ctx.ws_id depth = 1 if body.parent_id is not None: parent = await _resolve_category(session, ws_id, body.parent_id) depth = parent.depth + 1 if depth > MAX_CATEGORY_DEPTH: raise AppError( ErrorCode.KNOWLEDGE_CATEGORY_DEPTH, f"分类最多 {MAX_CATEGORY_DEPTH} 级，「{parent.name}」下面不能再建了", details={"parent_depth": parent.depth}, ) name = body.name.strip() if await _category_name_taken(session, ws_id, body.parent_id, name): raise AppError(ErrorCode.KNOWLEDGE_CATEGORY_CONFLICT, "同一层已经有同名的分类") cat = KnowledgeCategory( workspace_id=ws_id, parent_id=body.parent_id, name=name, depth=depth, sort_order=body.sort_order, ) session.add(cat) await session.flush() await audit_record( session, workspace_id=ws_id, actor_user_id=ctx.user.id, action="knowledge.category.create", target_type="knowledge_category", target_id=str(cat.id), ) by_id = await _categories(session, ws_id) return ok(_category_payload(cat, by_id)) @router.patch("/knowledge/categories/{category_id}", summary="改名或移动分类") async def patch_category( category_id: uuid.UUID, body: CategoryPatch, ctx: MemberDep, session: SessionDep ) -> dict: ws_id = ctx.ws_id cat = await session.get(KnowledgeCategory, category_id) if cat is None or cat.workspace_id != ws_id: raise AppError(ErrorCode.KNOWLEDGE_CATEGORY_NOT_FOUND, "这个分类不存在") by_id = await _categories(session, ws_id) now = datetime.now(timezone.utc) new_parent_id = cat.parent_id new_depth = cat.depth shift = 0 subtree: list[uuid.UUID] = [] if body.move: new_parent_id = body.parent_id if new_parent_id is not None and new_parent_id not in by_id: raise AppError(ErrorCode.KNOWLEDGE_CATEGORY_NOT_FOUND, "这个分类不存在") if new_parent_id == category_id: raise AppError(ErrorCode.KNOWLEDGE_CATEGORY_DEPTH, "不能把分类挂到自己下面") subtree = _subtree_ids(category_id, by_id) if new_parent_id is not None and new_parent_id in subtree: raise AppError(ErrorCode.KNOWLEDGE_CATEGORY_DEPTH, "不能把分类移到它自己的子分类下") new_depth = by_id[new_parent_id].depth + 1 if new_parent_id else 1 deepest = max(by_id[cid].depth for cid in subtree) shift = new_depth - cat.depth if deepest + shift > MAX_CATEGORY_DEPTH: raise AppError( ErrorCode.KNOWLEDGE_CATEGORY_DEPTH, f"移动后子树最深到第 {deepest + shift} 级，超过 {MAX_CATEGORY_DEPTH} 级", details={"deepest_after_move": deepest + shift}, ) name = body.name.strip() if body.name is not None else cat.name if name != cat.name and await _category_name_taken( session, ws_id, new_parent_id, name, exclude=category_id ): raise AppError(ErrorCode.KNOWLEDGE_CATEGORY_CONFLICT, "同一层已经有同名的分类") values: dict[str, Any] = {"name": name, "updated_at": now} if body.move: values.update(parent_id=new_parent_id, depth=new_depth) if body.sort_order is not None: values["sort_order"] = body.sort_order result = await session.execute( update(KnowledgeCategory) .where( KnowledgeCategory.id == category_id, KnowledgeCategory.workspace_id == ws_id, KnowledgeCategory.version == body.version, ) .values(version=KnowledgeCategory.version + 1, **values) ) if result.rowcount == 0: await session.refresh(cat) raise AppError( ErrorCode.VERSION_CONFLICT, "这个分类刚被改过", details={"current_version": cat.version}, ) # 子树跟着整体升降；只改被移动的那棵子树以外的行会留下 depth 不一致 if body.move and shift: for cid in subtree: if cid == category_id: continue await session.execute( update(KnowledgeCategory) .where(KnowledgeCategory.id == cid, KnowledgeCategory.workspace_id == ws_id) .values( depth=KnowledgeCategory.depth + shift, updated_at=now, version=KnowledgeCategory.version + 1, ) ) await session.flush() fresh = await _categories(session, ws_id) return ok(_category_payload(fresh[category_id], fresh)) @router.delete("/knowledge/categories/{category_id}", summary="删除分类") async def delete_category( category_id: uuid.UUID, ctx: MemberDep, session: SessionDep, force: Annotated[bool, Query(description="真删：里面的知识变成未分类")] = False, ) -> dict: ws_id = ctx.ws_id cat = await session.get(KnowledgeCategory, category_id) if cat is None or cat.workspace_id != ws_id: raise AppError(ErrorCode.KNOWLEDGE_CATEGORY_NOT_FOUND, "这个分类不存在") children = ( await session.execute( select(func.count()) .select_from(KnowledgeCategory) .where( KnowledgeCategory.workspace_id == ws_id, KnowledgeCategory.parent_id == category_id, ) ) ).scalar_one() if children: raise AppError( ErrorCode.KNOWLEDGE_CATEGORY_CONFLICT, f"「{cat.name}」下面还有 {children} 个子分类，先把它们移走或删掉", details={"children": children}, ) docs = ( await session.execute( select(func.count()) .select_from(KnowledgeDoc) .where(KnowledgeDoc.workspace_id == ws_id, KnowledgeDoc.category_id == category_id) ) ).scalar_one() if docs and not force: raise AppError( ErrorCode.KNOWLEDGE_CATEGORY_CONFLICT, f"「{cat.name}」里还有 {docs} 条知识，先移走，或者带 force 删成未分类", details={"doc_count": docs}, ) await session.delete(cat) await audit_record( session, workspace_id=ws_id, actor_user_id=ctx.user.id, action="knowledge.category.delete", target_type="knowledge_category", target_id=str(category_id), payload={"orphaned_docs": docs}, ) return ok({"deleted": str(category_id), "uncategorized_docs": docs}) # 注意路由顺序：`/knowledge/search` 必须排在 `/knowledge/{item_id}` 之前， # 否则 "search" 会被当成 uuid 解析，返回 422。 @router.get("/knowledge/search", summary="检索已发布知识") async def search( ctx: MemberDep, session: SessionDep, q: Annotated[str, Query(min_length=1, max_length=200, description="检索词")], limit: Annotated[int, Query(ge=1, le=30)] = 10, mode: Annotated[str, Query(pattern="^(hybrid|vector|keyword)$")] = "hybrid", ) -> dict: hits = await search_knowledge(session, ctx.ws_id, q, limit=limit, mode=mode) return ok({"query": q, "mode": mode, "items": hits, "has_more": False}) @router.get("/knowledge/{item_id}", summary="知识详情") async def get_knowledge(item_id: uuid.UUID, ctx: MemberDep, session: SessionDep) -> dict: item, doc = await _load_doc(session, ctx.ws_id, item_id) data = await _knowledge_out(session, ctx.ws_id, item, doc) events = ( await session.execute( select(Activity) .where(Activity.workspace_id == ctx.ws_id, Activity.item_id == item.id) .order_by(Activity.created_at.desc()) .limit(50) ) ).scalars() data["activities"] = [ { "action": e.action, "payload": e.payload, "actor_id": str(e.actor_id) if e.actor_id else None, "created_at": e.created_at, } for e in events ] return ok(data) # ── 创建 / 修改 ───────────────────────────────────────────────────────── @router.post("/knowledge", summary="新建知识（手记或引用来源）") async def create_knowledge(body: KnowledgeIn, ctx: MemberDep, session: SessionDep) -> dict: ws_id = ctx.ws_id if body.doc_type not in DOC_TYPES: raise AppError(ErrorCode.VALIDATION_ERROR, f"未知的知识类型：{body.doc_type}") source: Item | None = None if body.source_item_id is not None: source = await session.get(Item, body.source_item_id) if source is None or source.workspace_id != ws_id or source.kind not in ("task", "ticket"): raise AppError( ErrorCode.KNOWLEDGE_SOURCE_REQUIRED, "来源必须是与本知识同一工作区的任务或工单", ) category = await _resolve_category(session, ws_id, body.category_id) item = Item( workspace_id=ws_id, kind="knowledge", title=body.title.strip(), body_md=body.body_md, status="draft", creator_id=ctx.user.id, ) session.add(item) await session.flush() doc = KnowledgeDoc( item_id=item.id, workspace_id=ws_id, author_id=ctx.user.id, source_item_id=source.id if source else None, source_kind="manual" if source is None else source.kind, doc_type=body.doc_type, status_hint="draft", summary=body.summary, category_id=category.id if category else None, generated_by="human", ) session.add(doc) await session.flush() await _log(session, item, ctx.user.id, "knowledge_created", {"generated_by": "human"}) await _set_tags_for(session, ws_id, item, body.tag_names) await audit_record( session, workspace_id=ws_id, actor_user_id=ctx.user.id, action="knowledge.create", target_type="item", target_id=str(item.id), ) return ok(await _knowledge_out(session, ws_id, item, doc)) @router.patch("/knowledge/{item_id}", summary="修改知识内容") async def patch_knowledge( item_id: uuid.UUID, body: KnowledgePatch, ctx: MemberDep, session: SessionDep ) -> dict: ws_id = ctx.ws_id item, doc = await _load_doc(session, ws_id, item_id) if item.status == "published": raise AppError( ErrorCode.KNOWLEDGE_STATUS_INVALID, "已发布的知识不能直接改内容，先撤回成草稿", details={"from": item.status, "allowed_actions": ["archive"]}, ) if body.doc_type is not None and body.doc_type not in DOC_TYPES: raise AppError(ErrorCode.VALIDATION_ERROR, f"未知的知识类型：{body.doc_type}") values: dict[str, Any] = {} if body.title is not None: values["title"] = body.title.strip() if body.body_md is not None: values["body_md"] = body.body_md if body.summary is not None: values["summary"] = body.summary if body.doc_type is not None: values["doc_type"] = body.doc_type # 分类/标签也改的是这条知识的"样子"，所以同样要推进 version： # 否则只改了标签的知识，下一次保存还会拿着旧 version 撞 4009。 meta_changed = body.clear_category or body.category_id is not None or body.tag_names is not None if values or meta_changed: values["updated_at"] = datetime.now(timezone.utc) result = await session.execute( update(Item) .where( Item.id == item.id, Item.workspace_id == ws_id, Item.version == body.version, Item.deleted_at.is_(None), ) .values(version=Item.version + 1, **values) ) if result.rowcount == 0: await session.refresh(item) raise AppError( ErrorCode.VERSION_CONFLICT, "这条内容刚被别人改过", details={"current_version": item.version}, ) await session.refresh(item) if body.doc_type is not None: doc.doc_type = body.doc_type if body.summary is not None: doc.summary = body.summary if body.clear_category: doc.category_id = None elif body.category_id is not None: category = await _resolve_category(session, ws_id, body.category_id) doc.category_id = category.id if category else None if body.tag_names is not None: await _set_tags_for(session, ws_id, item, body.tag_names) await session.flush() return ok(await _knowledge_out(session, ws_id, item, doc)) # ── 状态动作 ──────────────────────────────────────────────────────────── @router.post("/knowledge/{item_id}/status", summary="提交审议 / 发布 / 归档 / 恢复") async def change_status( item_id: uuid.UUID, body: StatusActionIn, ctx: MemberDep, session: SessionDep ) -> dict: ws_id = ctx.ws_id item, doc = await _load_doc(session, ws_id, item_id) to_status = target_status(body.action, item.status) # 发布等于团队背书；归档/恢复作者自己就能做 if body.action == "publish" and not can_publish_role(ctx.role): raise AppError( ErrorCode.KNOWLEDGE_FORBIDDEN, "只有管理员可以发布知识", details={"role": ctx.role}, ) now = datetime.now(timezone.utc) result = await session.execute( update(Item) .where( Item.id == item.id, Item.workspace_id == ws_id, Item.version == body.version, Item.deleted_at.is_(None), ) .values(version=Item.version + 1, status=to_status, updated_at=now) ) if result.rowcount == 0: await session.refresh(item) raise AppError( ErrorCode.VERSION_CONFLICT, "这条内容刚被别人改过", details={"current_version": item.version}, ) await session.refresh(item) # 发布时间/归档时间记在 knowledge_doc 上（item 只有 status） doc.status_hint = to_status stamps = sidebar_fields(to_status, now) if "published_at" in stamps: doc.published_at = stamps["published_at"] doc.archived_at = None if "archived_at" in stamps: doc.archived_at = stamps["archived_at"] await _log( session, item, ctx.user.id, "knowledge_status_changed", {"action": body.action, "to": to_status, "note": body.note}, ) await audit_record( session, workspace_id=ws_id, actor_user_id=ctx.user.id, action=f"knowledge.{body.action}", target_type="item", target_id=str(item.id), payload={"to": to_status}, ) await session.flush() if body.action == "publish": # 发布后立刻建索引：检索只认 published，不在这里建就要等定时任务， # 而"刚发布却搜不到"是最容易被当成 bug 的体验。 await reindex_document(session, ws_id, item.id) return ok(await _knowledge_out(session, ws_id, item, doc)) @router.post("/knowledge/{item_id}/reindex", summary="重建这份知识的检索切片") async def reindex(item_id: uuid.UUID, ctx: MemberDep, session: SessionDep) -> dict: # 改完正文不重建，检索命中的还是旧句子——留一个能手动触发的入口 _item, doc = await _load_doc(session, ctx.ws_id, item_id) count = await reindex_document(session, ctx.ws_id, item_id) await session.flush() return ok( { "item_id": item_id, "chunk_count": count, "searchable": doc.status_hint == "published", } ) # ── 从任务/工单沉淀 ───────────────────────────────────────────────────── @router.post("/items/{item_id}/knowledge", summary="把这件事沉淀成知识草稿") async def promote_to_knowledge( item_id: uuid.UUID, ctx: MemberDep, session: SessionDep, doc_type: Annotated[str, Query()] = "postmortem", ) -> dict: ws_id = ctx.ws_id source = await session.get(Item, item_id) if source is None or source.workspace_id != ws_id or source.kind not in ("task", "ticket"): raise AppError(ErrorCode.ITEM_NOT_FOUND, "任务不存在") if doc_type not in DOC_TYPES: raise AppError(ErrorCode.VALIDATION_ERROR, f"未知的知识类型：{doc_type}") existing = await find_doc_by_source(session, ws_id, source.id) if existing is not None: raise AppError( ErrorCode.KNOWLEDGE_ALREADY_EXISTS, "这件事已经沉淀过了", details={"knowledge_id": str(existing.item_id)}, ) resolution = "" if source.kind == "ticket": from ..models_ticket import TicketExt ext = await session.get(TicketExt, source.id) if ext is not None and ext.resolution_md: resolution = ext.resolution_md doc_item, doc = await create_draft_from_source( session, ws_id=ws_id, source=source, author_id=ctx.user.id, generated_by="rule" if source.kind == "ticket" else "human", resolution_md=resolution, doc_type=doc_type, ) await _log( session, doc_item, ctx.user.id, "knowledge_created", {"source_item_id": str(source.id)} ) await audit_record( session, workspace_id=ws_id, actor_user_id=ctx.user.id, action="knowledge.promote", target_type="item", target_id=str(doc_item.id), payload={"source_item_id": str(source.id)}, ) # 与"新建知识"返回同一种形状：知识本体 + source，前端不用记两套 return ok(await _knowledge_out(session, ws_id, doc_item, doc))