xsl
d9249400af
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 已说明），未私开
回退通道。
36 lines
1.7 KiB
Markdown
36 lines
1.7 KiB
Markdown
# `packages/kb/` — 美学知识库
|
||
|
||
**职责**（架构 §4.1）：知识实体/关系/规则/素材的读写与发布。
|
||
**不负责**：检索算法（调 `packages/retrieval`）。
|
||
|
||
## 本批已落地（T6，T-P2-01/05）
|
||
|
||
- `schemas.py`：12 类 `EntityType` Literal、`EntityStatus`、CRUD 与图谱
|
||
响应模型（雪花 ID 一律字符串出参，防 JS 精度丢失）
|
||
- `repo.py`：`kb_entity`/`kb_relation`/`kb_color` 数据访问；
|
||
`traverse` 为递归 CTE 1~3 跳有界遍历（防环：`path` 数组 + `NOT @>`）
|
||
- `service.py`：状态机（draft→reviewing→published→archived，撤稿支线
|
||
draft/reviewing→archived，非法跃迁 40900）、内容修改 version+1 且
|
||
published 只读（要改必须撤稿归档后重录新草稿）、关系写入（自环/重复/
|
||
端点缺失校验）、色板 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`
|
||
|
||
## 待实现（后续批次）
|
||
|
||
- `kb_rule` 决策表 CRUD（T7 规则引擎）
|
||
- `kb_chunk` 向量+全文混合检索（T8）
|
||
- `kb_asset` 白底图流水线、`kb_gap` 知识缺口埋点（T-P2-06+）
|
||
- 关系/色板的运营 HTTP 入口（后台角色 T-P2-09 就绪后挂路由）
|
||
|
||
## 为什么它是数据不是代码
|
||
|
||
架构 §1.1：**知识库是持续演进的资产，更新频率远高于代码**。规则、色板、单品
|
||
必须是数据，配顾问能独立使用的运营入口（FR-ADM-02），改内容不发版。
|
||
任何时候想把规则写成 `if` 分支，都是错的。
|
||
|
||
## 知识库版本号
|
||
|
||
所有检索缓存键都带全局 `kb_version`，发布时 +1，**旧缓存自然失效**
|
||
（架构 §10）。不要试图精确追踪哪些缓存受影响。
|