xsl/meida

Files

T

- Sprint 执行计划 v1.1：§1.1 补第一批交付实据；T9 SPIKE 结论回写 Sprint 1 表
  （T-P0-16 通过 2.8ms；T-P0-12 有条件；T-P0-10 原型 6/6 + 真实照片重验前置）；
  Sprint 2 表标注 T-P2-01~06 交付；新增 §9 两批交付记录
- 开发任务拆解 v1.5：交付回写 + 新风险登记（RTMPose 域差异、BiRefNet 异步化）
- 新增 开发任务包/：三批多 agent 并行的协作规程与 14 份任务契约
- 新增 前置开通清单-云资源与资质.md
- 清理已用毕的评审报告（文档评审 2026-08-13、项目整体评审 2026-08-14），
  README 中相应引用改为留痕表述

2026-08-14 21:07:20 +08:00

5.0 KiB

Raw Blame History

T6 · 知识库·实体与图谱

对应任务：T-P2-01（12 类实体可存取）、T-P2-05（1~3 跳可解释路径）｜需求：FR-KB-*、架构 §6.2 kb 域、TD-09 ｜分支：task/t6-kb-entity ｜ worktree：/home/xsl/meida_backend-t6 先读《README.md（协作规程）》，遵守全部纪律。

1. 目标

知识库的实体底座：12 类实体统一表的 CRUD 与状态机、kb_relation 邻接表 + 递归 CTE 的 1~3 跳图谱查询（可解释路径）、kb_color 自建色板存取。这是知识库可运营（M2 出口）的第一块。

2. 已就绪的契约（协调提交已提供，禁改 models/migrations）

表（迁移 `0005` 已建，ORM 已加：`KbEntity`/`KbRelation`/`KbColor`，先读 `packages/shared/models.py` 核对列名）

kb_entity：entity_id PK 雪花、entity_type varchar(32)、name varchar(128)、attrs JSONB、status draft/reviewing/published/archived、version int、source、license、updated_by、created_at/updated_at；UNIQUE(entity_type,name)、Index(entity_type,status)
kb_relation：relation_id PK、from_id/to_id bigint、rel_type varchar(64)、weight Numeric(4,3)、confidence Numeric(4,3)、evidence varchar(255)；UNIQUE(from_id,rel_type,to_id)、Index(to_id)
kb_color：color_id PK、season_code varchar(16)、role base/accent/avoid、lab_l/lab_a/lab_b Numeric(6,2)、hex varchar(7)、name_cn varchar(64)；Index(season_code)

12 类 entity_type（知识库文档 §3.1，写进 schemas 的 Literal 校验）

item / color / style / body_shape / face_hair / occasion / material / accessory / makeup / rule / outfit / trend

状态机（写进 service，非法跃迁抛 `AppError(STATE_CONFLICT)`）

draft → reviewing → published → archived；archived 终态；draft/reviewing → archived 允许（撤稿）；其余跃迁非法。每次内容修改 version+1 且不允许直接改 published 实体——published 实体要改必须先回 draft（新版本走评审，这是知识库文档"发布回滚"的语义）。

路由骨架

apps/api/routers/kb.py 空路由（prefix /kb）已注册 main.py——你填充。

3. 实现要点

允许改动：packages/kb/**（service.py / repo.py / schemas.py / README.md）、apps/api/routers/kb.py、测试文件。packages/kb 现只有 README + 空 __init__；packages/rules、packages/retrieval 归 T7/T8，禁碰。

schemas.py（Pydantic）：EntityCreate（entity_type/name/attrs）、EntityUpdate（仅 draft/reviewing 可用）、EntityOut（含 status/version/时间戳）、RelationCreate、GraphPath（路径节点序列 + 每跳 rel_type）、ColorOut。跨域响应模型放本包，apps/api/schemas.py 禁改。
repo.py：CRUD + search_entities(entity_type, status, name_ilike, limit, offset) + traverse(from_id, max_hops) —— 递归 CTE 用 sqlalchemy.text() 写原生 SQL（返回 hop 序列），1~3 跳，防环（CTE 里用 path 数组 + NOT path @> ARRAY[to_id] 判重）。参考架构 TD-09 的理由：浅层有界遍历，不需要图数据库。
service.py：状态机校验、版本递增、relation 写入（自环/重复抛 AppError(BAD_REQUEST)）、色板 CRUD（role/hex 格式校验，#RRGGBB）。实体创建时 entity_id=next_id()（packages.domain.ids）。
路由：GET /kb/items（分页 + entity_type/status 过滤）、GET /kb/items/{id}、POST /kb/items、PATCH /kb/items/{id}、GET /kb/items/{id}/graph?max_hops=3（1~3 跳，超界 422/400）。写接口暂不挂鉴权以外的前置（后台运营角色属 T-P2-09，先 CurrentUserId）。

4. 测试要求

单测 tests/unit/test_kb_entity.py：状态机全跃迁矩阵（合法/非法）、12 类 Literal 校验、非法 entity_type 拒绝、色板 hex 校验。（纯逻辑部分；repo/service 层用集成覆盖。）
集成 tests/integration/test_kb_entity.py（新文件）：建实体→reviewing→published；改 published 被拒；draft 改→version+1；建 relation→graph 2 跳返回可解释路径（含每跳 rel_type）；自环拒绝；GET /v1/kb/items 过滤分页。

5. 禁改清单

通用禁改之外：packages/rules/**、packages/retrieval/**、packages/identity/**、apps/api/routers/{auth,auth_sms}.py、全部已有测试文件。

6. 验收标准（T-P2-01/05）

12 类实体可存取，attrs JSONB 差异化承载；
状态机非法跃迁 100% 被拦（有测试矩阵证明）；
图谱 1~3 跳返回可解释路径且防环；
全部检查绿（mypy 范围：apps packages/shared packages/identity packages/billing packages/task packages/agent packages/compliance packages/analytics packages/storage packages/kb）。

7. 提交信息

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）。

偏差说明：<如有写在这里，无则写"无">

5.0 KiB Raw Blame History Unescape Escape