furniture-3d-system-Wu/docs/solutions/workflow-issues/controller-overload-layering-batch-20260215.md

51 lines
2.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
title: Controller 过载拆分与批处理事务收口
date: 2026-02-15
module: api/products/upload + api/users/[id]/handover + auth/share/panel services
problem_type: workflow_issue
severity: high
symptoms:
- Route 文件承担解析、存储、事务、日志等多重职责
- Service 直连 Prisma,分层边界失效
- 离职交接单事务内长循环,存在锁等待风险
root_cause: Controller 与 Service 职责未按分层规范收口,数据访问逻辑散落在业务层
resolution_type: code_fix
status: active
confidence: high
tags: [route-layering, service-repository, batch-processing, transaction-scope]
related_patterns:
- WF-SVC-REPO-USER-001
- WF-PANEL-ROUTE-SVC-001
---
## 1) 现象与影响
- `/api/products/upload` 既做鉴权又做文件转换、上传、解析与事务写入,Route 过载。
- `/api/users/[id]/handover` 在 Route 内执行多段查询、循环更新、日志落库,难以维护且不利于并发稳定性。
- `auth/share/panel` 的 Service 存在直连 Prisma,导致分层审计无法闭环。
## 2) 排查路径
1. 先定位台账中同类问题(ARCH-009/013/015/017/DB-004)。
2. 用 `type-check` 兜底验证改造后类型边界。
3. 用认证和安全回归测试确认关键链路未回归。
## 3) 根因分析
- Route 层未被限制为“参数+鉴权+统一返回”,业务编排和数据细节长期堆积。
- Service 缺少配套 Repository 原子方法,导致为求开发速度直接写 Prisma。
- 交接链路追求“全成功事务”,把多项循环更新捆成单大事务,放大锁持有时间。
## 4) 最终修复
- 上传链路:新增 `product-upload.service + product-upload.repository`,Route 仅保留入口职责。
- 离职交接:新增 `user-handover.service + handover.repository`,采用分批提交与短事务策略。
- 认证/分享/板件:新增或扩展 `auth/share/panel` Repository 原子方法,Service 仅做权限和编排。
- 产品服务:将软删/恢复/CAD 创建事务下沉到 `product.repository`,减少业务层数据细节泄漏。
## 5) 预防策略
- 新增 API 一律先定义 Service/Repository 边界,再写 Route。
- 对“循环更新 + 事务”场景默认评估分批策略,避免单长事务。
- 复核清单加入“Service 是否仍引用 Prisma”自动检索项。