xsl
aa1287d83d
DeterministicEmbedder（可换 BGE-M3 的接口位）+ kb_chunk 双索引写入 + 硬过滤→向量→关键词→RRF 重排管线 + kb_gap 缺口埋点（T-P2-03/04/06，TD-08）。 实现： - embedding.py：EmbeddingProvider Protocol + DeterministicEmbedder （sha256 种子→归一化 1024 维假向量，同文本同向量/异文本近似正交） + build_embedding_provider 工厂（未知模型名抛 CONFIG_ERROR）。 - repo.py：upsert_chunks（整实体先删后插，逐行带 embedding_model/version， 可重跑判据 T-P2-03）；hybrid_search（§8.3 CTE：硬过滤 published/ entity_types/occasion/avoid_body_shapes → <=> 余弦 topN → ts_rank topN → RRF）；record_gap（咨询锁串行化同 query+filter_ctx 的 hit_count 递增）。 - rerank.py：RRF/权重/新鲜度纯数学（独立于 SQL 以便单测逐项断言）。 - service.py：RetrievalService.search 编排 embed→检索→（空结果）gap 埋点， SearchOutcome.degraded 标记降级。 测试：单测 +30（test_embedding 确定性/维度/归一化/工厂拒绝、test_rerank 公式逐项断言、test_retrieval_service 编排打桩）；集成 +5 （test_hybrid_retrieval：禁忌实体同文最近向量仍零出现、draft 零出现、 关键词路径、换模型整组替换、kb_gap hit_count=2、partial 索引 EXPLAIN 验证）。 全绿：ruff / mypy(retrieval+shared+domain) / lint-imports / 268 单测 / 21 集成。 偏差说明： 1) 新增 rerank.py（任务文档只点名 embedding/repo/service，但重排数学必须 不连库可单测，独立模块是最低成本实现，仍属 packages/retrieval/**）。 2) upsert_chunks 的 upsert 粒度是实体（先删后插）：kb_chunk 无业务自然键， 行级 ON CONFLICT 不可行；换模型名=新版本整组替换，不留旧版本残向量。 3) 禁忌过滤用 COALESCE(attrs->avoid_body_shapes, '[]')兜底：jsonb NULL 的 ? 运算结果是 NULL，直接 NOT 会把未声明禁忌的好实体一并排除。 4) 关键词路过滤用 tsv @@ tsquery 而非 ts_rank>0：ts_rank 对不匹配文本返回 ~1e-20 正 epsilon，阈值过滤会把无关 chunk 全放进关键词路。 5) RRF 分量按 1/(k+1) 归一到 (0,1]，使 0.45/0.2/0.25/0.1 权重量纲可比 （原始倒数 0.45×1/61 与规则项 0.25×1 完全不可比）。
packages/ — 业务域与能力包
架构 §3.2：单体不等于混乱。这里的每个子目录都是一个边界，越界会被 CI 拦下。
目录含义
| 包 | 类型 | 内容 |
|---|---|---|
domain/ |
纯逻辑层 | 领域模型与业务规则。无 IO、无框架、可纯单测 |
shared/ |
基础设施 | 配置、日志、错误码、统一响应、DB、Redis、可观测 |
llm/ |
AI 能力 | LLM 网关（已实现） |
retrieval/ rules/ memory/ |
AI 能力 | 混合检索 / 规则引擎 / 记忆系统（占位） |
compliance/ |
业务域 | 统一合规出口（占位，CR-05/CR-06） |
identity/ billing/ task/ agent/ |
业务域 | 已有实现 |
profile/ report/ tryon/ kb/ notify/ wardrobe/ |
业务域 | 占位 |
每个业务域包的标准结构：
packages/<域>/
├─ __init__.py
├─ README.md 这个域负责什么、不负责什么
├─ service.py 对外唯一入口。其他域只能调这里
└─ repo.py SQL。只有本域可以 import
硬性规则（由 make importlint 机器校验）
- 禁止跨域直接查表。要用别的域的数据，调它的
service，不要 import 它的repo，更不要在自己的 SQL 里 JOIN 别人的表。表名的域前缀（id_/bl_/tk_/ …）就是为将来拆库预留的边界。 packages/domain/必须保持纯净。不许 importfastapi、sqlalchemy、httpx、redis、celery，也不许 importpackages/shared。放不进去说明 它不是领域逻辑，是应用逻辑，应该待在service.py。compliance不得依赖任何业务域。它必须能被任何模块安全调用。identity不得依赖任何其他业务域。登录链路不能被业务拖累。- AI 能力包（
llm/retrieval/rules）不得依赖业务域，也不得 importapps。它们要能在 V2 原样拆成独立服务。
加一个新业务域时
- 建目录，写
README.md说明职责与不负责的事。 - 在
pyproject.toml的[tool.importlinter]契约里把它加进相应的layers/forbidden_modules列表 —— 新域默认没有约束，忘了加就等于没有边界。 - 领域规则先写进
packages/domain/<域>/并配单测，再写service.py。 - 表加域前缀，走 Alembic，迁移必须向后兼容（NFR-MAINT-06）。