主题
工程安全管理 · 建渣管理 · 详细设计文档
文档版本：0.10 ｜ 最近核对日期：2026-09-15
进展说明：详细设计已实现；边界修复已实现，代表性端到端主链路已验证，流程详情专项已复验、导出专项待确认；审查补录渣场引用生效校验、流程 JSON 路径与两级驳回路由，新增消纳场启用/停用通道及引用兼容规则。
1. 后端结构
包路径 com.bokun.business.czw，分层与 sqe 一致：
| 层 | 类 | 说明 |
|---|---|---|
| controller | CzwDisposalSiteController、CzwSlagLedgerController | 协议边界；@SaCheckPermission 与 SYS_MENU.PERMS 逐字一致 |
| service | ICzwDisposalSiteService/ICzwSlagLedgerService + impl | 业务规则、事务边界、流程接入 |
| service | CzwBusinessRules | 状态可写性、证书时效、满容、期间、剩余占比、湿渣阶段校验（纯函数，单测覆盖） |
| domain | CzwDisposalSite、CzwSlagLedger、CzwSlagLedgerPlan + bo/vo | MyBatis-Plus 实体，@TableLogic 逻辑删除 |
| mapper | 三个 BaseMapperPlus 接口 | 无 XML，注解式 |
| helper | CzwWorkflowHelper | 草稿启动流程/退回重办；nextHandlerId 逗号拼接多人或签 |
| workflow | CzwFlowConstant、CzwProcessEventListener | czw 前缀事件回写 approvalStatus |
2. 接口清单
| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
| GET | /business/czw/disposalSite/list | czw:disposalSite:list | 分页，含派生字段与 currentTaskId |
| GET | /business/czw/disposalSite/options | czw:disposalSite:list | 已生效且未停用渣场下拉（停用渣场不进新计划，已引用台账不受影响） |
| GET/POST/PUT/DELETE | /business/czw/disposalSite[/{ids}] | query/add/edit/remove | 详情/新增/编辑/删除（仅草稿） |
| POST | /business/czw/disposalSite/submit | czw:disposalSite:submit | 提交进流程 |
| PUT | /business/czw/disposalSite/current-update | czw:disposalSite:update | 本期更新剩余容量，仅生效单据 |
| PUT | /business/czw/disposalSite/status | czw:disposalSite:edit | 启用/停用切换，仅生效单据 |
| GET | /business/czw/disposalSite/process-info/{id} | czw:disposalSite:query | 流程信息 |
| POST | /business/czw/disposalSite/export | czw:disposalSite:export | 导出 |
| GET | /business/czw/slagLedger/list | czw:slagLedger:list | 分页，含当期处置计划与派生字段 |
| GET | /business/czw/slagLedger/stats | czw:slagLedger:list | 统计卡 |
| GET | /business/czw/slagLedger/{id}/plans?period= | czw:slagLedger:query | 指定期次处置计划 |
| GET/POST/PUT/DELETE | /business/czw/slagLedger[/{ids}] | query/add/edit/remove | 详情/新增/编辑/删除（仅草稿，级联删计划） |
| POST | /business/czw/slagLedger/submit | czw:slagLedger:submit | 提交（含湿渣阶段强校验） |
| PUT | /business/czw/slagLedger/current-update | czw:slagLedger:update | 本期更新：覆盖当期快照+问题情况 |
| GET | /business/czw/slagLedger/process-info/{id} | czw:slagLedger:query | 流程信息 |
| POST | /business/czw/slagLedger/export | czw:slagLedger:export | 导出 |
说明：导出接口保留为后端协议入口；当前前端页面沿用平台下载能力直接请求导出地址，未在 API 客户端另设同名封装函数。
3. 关键业务规则实现
- 提交校验（
validateSubmit）：标段、施工/运输单位、渣土类别、预计完成时间、设计/剩余总量必填；剩余总量必须满足0 ≤ remainTotal ≤ designTotal；处置计划非空且阶段/渣场必填；湿渣（wet/shield）调用CzwBusinessRules.validateWetStageOrder按 orderNum 排序后校验预处理先于最终消纳。草稿保存不执行计划阶段/渣场强校验，但消纳场草稿仍校验物理必填的渣场名称，避免数据库非空约束转化为 500。 - 渣场引用生效校验（
fillSiteSnapshot，新增/编辑/提交/本期更新保存计划共用）：处置计划引用的消纳场必须存在且approvalStatus=finish；新引用还必须不是siteStatus=disabled，与前端"下拉仅已生效且未停用渣场"口径一致，避免绕过前端直连接口把计划挂到草稿、未生效或已停用渣场。服务层以该台账历史计划已有的siteId作为兼容范围，允许已引用的停用渣场继续写入名称/ID 快照，保证编辑和本期更新不破坏历史业务事实。 - 草稿期次与正式快照：新增草稿计划使用当前自然月；草稿编辑沿用该台账已有最近期次并只替换该期计划；正式提交先清理该台账旧计划行，再以提交当月写入通过校验的正式快照，避免跨月编辑残留幽灵期次。
- 编辑/提交保留快照：审批状态、更新状态、期次、填报人快照不由前端覆盖。
- 本期更新（台账）：仅
finish可更新；bo 只携带执行类字段，校验用完整契约继承既有业务字段；更新remainTotal/satisfyStatus/problemDesc/suggestion/otherDesc+updateStatus=updated+currentPeriod=当月；replacePlans先删当期快照行再插入，填报人记为更新人。 - 消纳场启用/停用（
changeStatus）：仅approvalStatus=finish可手工切换siteStatus（enabled/disabled），草稿/退回态经编辑表单改状态；停用渣场由options()下拉过滤（siteStatus≠disabled或为空），不再进入新处置计划，服务端同步拒绝新引用；状态接口只更新SITE_STATUS，并以记录 ID、approvalStatus=finish及读取到的旧状态作为条件，避免并发操作覆盖其他字段或逆向覆盖较新的状态；已引用台账保留快照不受影响。 - 删除：仅草稿；消纳场删除前校验未被任何处置计划引用；删除同时
workflowService.deleteInstance清理流程实例。 - 派生展示在 service 填充：
certStatus、displayStatus（消纳场）、remainRatio、produceCertStatus、transportCertStatus、displayUpdateStatus。
4. 流程定义
- JSON：
digital-construction-modules/digital-construction-workflow/src/main/resources/flow/czw/czw_disposal_site.json、czw_slag_ledger.json；节点start → submit → supervision_audit(${nextHandlerId}, pop,back) → owner_audit(${nextHandlerId}, back) → end；监理驳回退回submit（申请人）、业主驳回退回supervision_audit（同 sqe 两级驳回路由）；坐标与边锚点遵循 流程图编排规范。 - 导入/发布：管理端
POST /workflow/definition/importDef（category=2110000000000000901）+PUT /workflow/definition/publish/{id}；已发布版本不改写，后续变更复制 V(n+1)。 - 业主审核人注入：监理办理时弹窗选人 →
assigneeMap{owner_audit}→CompletePrepareComponent.setPopAssigneeMap写pass:owner_audit变量。
5. 前端结构
| 路径 | 说明 |
|---|---|
src/api/business/czw/{index,types}.ts | API 与类型；ID 保持 string | number |
src/views/business/czw/flowSteps.ts | 流程展示节点、记录动作（仅草稿可删、生效可本期更新）+ spec |
src/views/business/czw/disposalSite/{index,flowForm}.vue | 消纳场台账页与工作台 |
src/views/business/czw/slagLedger/{index,flowForm}.vue | 渣土台账页（统计卡/展开行/四页签弹窗/本期更新弹窗）与工作台（期次切换） |
| 复用 | sqe useFlowWorkspace（flowKey 类型放宽为 string）、loading.ts、flow-workspace.scss；平台 NextHandlerPicker、FlowChartEntry、FileUpload、FlowActionPanel/FlowTimeline/FlowProgressDrawer |
菜单路由：/czw/waste/disposalSite[/flowForm]、/czw/waste/slagLedger[/flowForm]，办理菜单隐藏（VISIBLE=1）且与流程 JSON formPath 对应。
渣土台账的新增基础信息和列表筛选均不引入独立项目选择；线路直接读取工程结构树，标段递归收集所选线路下的 BID 节点，兼容线路下存在 PACKAGE 等中间层级的工程树结构。线路选项默认隐藏运营线路并提供「显示运营」开关（默认关闭，查询区与新增表单共用同一份选项，2026-09-18 起），仅切换显示层、不做运营拒绝。
6. 权限矩阵
三段式 czw:{disposalSite|slagLedger}:{list|query|add|edit|remove|export|submit|update}；后端 @SaCheckPermission、SYS_MENU.PERMS、前端 v-hasPermi 三处逐字一致（菜单回读见 数据库设计）。审批动作走流程任务权限，不另设业务权限。消纳场启用/停用切换（PUT /status）复用 czw:disposalSite:edit，不新增权限码与菜单按钮，故无数据库菜单变更。
台账页面还有两个跨模块读取依赖：工程树线路接口需要 business:projectNode:query、business:projectNode:list 或 business:siteMaster:list 任一权限；已生效渣场下拉需要 czw:disposalSite:list。这些依赖需纳入角色授权与页面验收；依赖失败时前端分别隔离线路筛选/新增能力、渣场下拉能力，不阻断已有列表和统计的读取。
工程数据范围由 EngineeringDataAccessHelper 对渣土台账的列表及对象入口执行专属组合校验：授权必须命中同线路、同标段、同工点的当前有效组合，或该线路的整线授权；候选标段或工点无效时拒绝访问。消纳场档案不受工程数据授权过滤。模块级浏览器端到端证据见测试报告，共享授权模型见工程基础详细设计 §4.2。