furniture-3d-system-Wu/docs/solutions/workflow-issues/collaborator-relation-and-lib-datasource-20260215.md

title, date, module, problem_type, severity, symptoms, root_cause, resolution_type, status, confidence, tags, related_patterns

title	date	module	problem_type	severity	symptoms	root_cause	resolution_type	status	confidence	tags	related_patterns
协作者关系表与 lib 数据源注入收口	2026-02-15	product-collaboration-and-lib-layering	workflow_issue	high	Product 协作者依赖 JSON 字段，查询和交接链路存在全表扫描与类型不稳定 lib 层直接访问数据库，绕过 Service -> Repository 分层	数据访问边界未统一，历史兼容字段与新能力叠加后缺少关系化模型与运行时注入层	code_fix	active	high	product-collaborator repository-layering datasource-injection architecture

现象与影响

• Product.collaborators 采用 JSON 存储协作者，导致筛选和交接只能依赖应用层逻辑，缺少数据库级约束。
• src/lib 多个模块直接读写 Prisma，API/Service 分层难以维持，后续审计与复用成本高。

排查路径

1. 先用 npm run type-check -- --pretty false 固定错误集合，确认问题集中在协作者链路和 3D/装配链路重构中间态。
2. 对 product.repository、handover.repository、product-collaborator.service 做调用链回溯，确认 JSON 与关系表并存阶段缺少统一读取策略。
3. 对 src/lib/assembly-generator.ts、src/lib/hardware-matcher.ts、src/lib/permissions.ts 做依赖扫描，定位直连 Prisma 的边界点。

根因分析

• 协作者数据模型长期停留在 JSON，缺少 FK 和索引，导致权限、交接、查询无法在 Repository 层稳定下沉。
• lib 层承担了运行时数据访问职责，破坏了“lib 纯算法、server 负责 IO”边界，拆分后容易出现类型和注入断层。

最终修复

• 新增 ProductCollaborator 关系表并建立索引/FK，新增迁移 20260215093000_add_product_collaborator_relation，并在迁移中回填历史 JSON 数据。
• Repository/Service 改为优先读写关系表，同时保留 JSON 镜像同步，保障存量接口兼容。
• assembly-generator、hardware-matcher 改为 data source 注入和 server runtime 封装；permissions 通过 repository 读取权限上下文，移除 lib 直连 Prisma。

预防策略

• 新增跨层守护检查：lib 模块默认禁止 @/lib/prisma 依赖，统一走 runtime/service 注入。
• 协作者相关新需求默认只增量扩展关系表，JSON 仅作为兼容镜像，避免再次回到“应用层全扫”。
• 验证命令固定为：
  • npm run prisma:generate
  • npm run type-check -- --pretty false