主题
勘察管理 · 详细设计
文档版本：1.20 ｜ 最近核对日期：2026-11-04
| 项目 | 内容 |
|---|---|
| 设计范围 | 勘察管理五项业务；以下新增 API、类、表均为目标设计，不表示已存在 |
业务规则唯一正文见需求分析，结构见数据库设计，验收见测试与验收。平台约束引用前端规范、后端规范、公共约定、界面规范。
1. 设计决策与范围边界
五项业务共用任务头，taskType 固定为 outline / fieldPlan / progress / special / result。外业计划与进度各有扩展表；成果类使用分类附件。类型不是任意字符串，不允许调用方通过改类型访问其他资源。共享任务表不代表五类业务共用一条流程或一套动态表单引擎。
一期按一张任务对应一个工程范围、一个项目的紧凑模型设计。项目与线路是不同主数据，不能把线路 ID 当 projectId；若需跨项目或跨工点联合报审，先核实关联粒度再调整关系表，不能按旧方案自动增加多项目关系。合同编号从已选择项目/标段的适用合同信息取值；现有契约不能唯一定位时保留合同编号录入并做业务核对，不从项目名称截取。
用户明确选择工程授权过滤。任务有工点时属于标段工点专属资源；仅落标段且无工点时按平台标段级资源处理，不能把有工点记录降级为标段权限。旧父模块中部门数据范围、并行审查和十七页面统一主实体等提案不适用于本次勘察实现。
本次数量按勾选孔数派生；统计集合、草稿预览和完成率按需求已确认规则执行。计划调整走原审批链，通过前原已通过计划继续有效；计划台账一行一份计划版本任务，完成台账一行一次进度上报。详细计算与接口见4.1—4.3节。
2. 页面、路由与布局
页面菜单层级：勘察设计管理 → 勘察管理 → 勘察大纲 / 外业计划 / 进度上报 / 专项勘察 / 勘察成果。外业计划与进度上报按业务顺序紧随大纲排列，保持下表精确路由；流程分类另保留“勘察外业”分组，见概要设计。
| 资源 | 台账路由（设计） | 菜单组件（设计） | 流程编码（设计） |
|---|---|---|---|
| outline | /surveyDesign/survey/outline | business/surveyDesign/outline/index | survey_outline |
| fieldPlan | /surveyDesign/survey/fieldPlan | business/surveyDesign/fieldPlan/index | survey_field_plan |
| progress | /surveyDesign/survey/progress | business/surveyDesign/progress/index | survey_progress |
| special | /surveyDesign/survey/special | business/surveyDesign/special/index | survey_special |
| result | /surveyDesign/survey/result | business/surveyDesign/result/index | survey_result |
办理路径为各台账路由追加 /flowForm；组件为对应目录 flowForm。在 src/router/flowFormRoutes.ts 静态注册，并同步核对 flowFormPaths.ts，流程 JSON 表单路径、菜单路径必须一致。隐藏菜单按“勘察大纲办理”等真实流程名命名，与台账同父级且紧随其后。详情复用相同工作台的只读模式，不另建审批中心。
新增/编辑在台账弹窗完成：报审类采用标准双列表单，计划与进度采用宽型编辑表格弹窗。查询卡位于最上，列表工具栏左标题右操作；状态与操作连续固定右侧。采用共享工作区滚动模式，不使用硬编码视口高度。所有动作按权限和任务状态呈现，不能照抄原型“草稿行没有编辑”就禁止编辑。
2026-11-03 布局调整：计划/进度弹窗宽度 min(1280px, calc(100vw - 48px))，报审类 min(960px, calc(100vw - 40px))；基本信息采用两列栅格，线路、勘察标段、工点、项目名称、勘察阶段、合同编号各占一列，任务名称和业务说明整行；计划信息按“计划开始/完成时间、紧急程度/钻机数量、计划说明整行”排布；进度信息按“外业计划整行、线路/勘察标段/工点/勘察阶段/计划起止只读、实际起止、完成说明整行”排布。弹窗整体最大高度为视口减 111px，标题和底部操作固定，仅正文滚动；底部按钮顺序为取消、保存草稿、提交审批。台账查询区使用线路、勘察标段两个独立下拉，表格 fit=false 保证列宽超出时横向滚动且固定列不覆盖中间列。
表单按“基本信息—业务内容—附件”分区，选择审核人属于提交动作；草稿不强制选择。打开弹窗不能创建流程实例。流程图与历史在工作台统一展示，禁止复刻原型多层弹窗叠加。任务名称不硬编码示例“15号线”“张三”。
2.1 公共组件的真实契约
- 单选审核人复用
src/components/UserSelect/index.vue：:multiple="false"，:data="已选ID"，:user-ids="服务端候选ID数组"，@confirm-call-back返回UserVO[]，单选取第一项userId；通过 ref 的open()/close()控制。空候选时禁用选择入口并阻止提交；不得给组件传空userIds后仍打开全员列表。用户选择后仍由服务端核验候选。 UserSelectField当前只支持多选 ID 数组，没有multiple、disabled或候选范围属性，不能靠传不存在的 prop 实现单选或权限裁剪。可借鉴造价单选封装的用法，但不跨业务依赖其私有组件。- 工程候选不再使用“线路/标段”一个级联控件，拆为三个独立选择：线路用
getEngineeringLineOptions，勘察标段用getEngineeringSelectTree('bid')扁平化，工点用getEngineeringSelectTree('site', bidId)，暂未选标段时用getEngineeringSelectTree('line-site')按线路读取物理工点。线路和标段是空间核与合同核两个独立字段，不互为父子路径；线路变化时只清空不属于该线路的标段和原工点。 - 线路候选统一经
hideOperatingNodes排除运营线路及其下辖节点；标段候选限定“勘察标段”“勘察设计标段”，并显示标段类型；服务端保存时执行同样的类型校验。 - 已保存的线路/标段/工点不在当前候选（授权变化、线路运营被隐藏、标段停用）时，选择器补“已保存值”兜底项显示原名称，不能显示空白；保存仍以服务端回写的 ID/名称为准。项目另用项目主数据接口，按标段
BIZ_BID_PROJECT_REL过滤。工程树已按授权裁剪，不能改用全量线路选项规避本模块授权。 - 附件复用
FileUpload：模型提交 CSV OSS ID，在服务端拆成分类关联。编辑时deleteOssOnRemove=false，移除只改变本次表单引用，取消编辑不得使旧附件失效。详情disabled=true仍允许预览/下载。 - 默认文件类型不含图片；逐孔影像须在业务调用显式配置图片类型。是否支持视频、压缩包、CAD 需结合文件服务能力确认，不能宣称默认支持。布孔图按经确认类型配置，不修改全局上传默认值。
- 文件预览复用站内抽屉：业务附件左侧 65%，审批时间线附件右侧 65%。
3. 类型、字段与校验责任
3.1 请求与响应对象
共同 SurveyTaskForm：id?、projectId?、lineId、bidId?、siteId?、contractNo?、surveyStage?、taskName?、content?、attachmentGroups[]。标段暂未建立时允许为空；无标段提交时 projectId 必填。attachmentGroups 为 {category, ossIds: (string|number)[]}。后台读取数据库/主数据生成名称快照与发起人；不采信请求中的status、taskType、createBy、instanceId、累计值、派生钻孔数及影像数；currentCompletedCount同样是只读派生字段，服务端从本单有效选孔明细计数，不接受客户端数量作为统计依据。
计划增量：planStartDate?、planEndDate?、urgency?、machineCount?、description?、boreholes[]。钻孔为 {id?, holeCode, designX?, designY?, expectedDepth?}；详情额外返回只读sourceBoreholeId用于版本对比，PUT不允许改其关系。坐标与孔深的请求/响应统一用十进制字符串（前端string，后端BigDecimal），避免实现者在各接口任选数字或字符串；物理精度见数据库设计。日期统一 yyyy-MM-dd，无时区偏移；创建/提交时间按平台日期时间契约。
进度增量：planTaskId、actualStartDate?、actualEndDate?、description?、holes[]。逐孔为 {boreholeId, actualDepth?, actualStartDate?, actualEndDate?, imageOssIds[]}。钻孔编号、坐标、预计深度由服务端读取计划生成快照，不由前端任意改写。进度保存不能修改计划钻孔。
SurveyTaskVO 含共同字段、业务扩展、分类附件、status、instanceId?、currentTaskId?、canEdit、canSubmit、canHandle；能力字段仅辅助显示，写操作仍服务端校验。响应增加rootPlanTaskId、currentCompletedCount、cumulativeCompletedCount、planBoreholeCount、completionRate。本次数量取有效选孔明细行数，同单重复boreholeId拒绝；孔深、日期、影像不参与计数判据。累计由后端派生，完成率为百分数十进制字符串（如"33.33"，前端加%），分母0返回null并显示“—”；使用BigDecimal乘100后除以分母，scale=2、HALF_UP，大于100不截断。Service列表返回 PageResult<VO>，HTTP Controller统一包装为 R<PageResult<VO>>，详情HTTP为 R<VO>；前端按项目请求包装读取 res.data，不另加第二层 data。
3.2 草稿与提交
| 校验 | 草稿保存 | 提交/办理 |
|---|---|---|
| 登录、动作权限、资源类型、工程范围 | 必须 | 必须 |
| 已填 ID 的真实性与归属、已填日期先后、数值合法性 | 必须 | 必须 |
| 任务标题、勘察阶段及足够业务内容 | 可分步完善；长度仍校验 | 要求完整，具体资料完整性按需求规则 |
| 审核人 | 不要求 | 只允许下一节点有效候选 |
| 原型无星号的其他附件、工点 | 不凭截图推断必填 | 不随意扩大必填范围 |
| 累计公式、调整生效 | 本次值变化即预览累计；调整草稿不改变有效版本 | 累计不等待审核通过；调整仅最终通过后切换有效版本 |
日期结束不得早于开始；孔深与钻机台数非负，预计孔深已填时也须非负；坐标可为有符号十进制值，不误设必须正数。钻孔编号在同计划内去空白后唯一，不能静默吞掉重复行。阶段与紧急程度来自字典：需先核实/建立本模块稳定值，截图中的“初步勘察”“一般”是例子，不能认定枚举全集。
编辑详情返回该单完整钻孔/进度明细及稳定ID，弹窗表格使用本地分页，切页不得丢未保存数据。PUT的boreholes/holes/attachmentGroups明确为完整集合；前端只有当前服务器页时不得提交覆盖保存，应先加载完整编辑集合。服务端按ID比对新增/更新/移除，缺省集合与明确空数组区分：缺省视为无效完整表单并拒绝，空数组表示明确清空且仍受引用保护。进度逐孔以本单boreholeId定位已有progressHoleId并保留它，不能删除重建导致影像关系悬空。
保存主表、扩展、钻孔/进度明细、附件关系在同一事务中完成；前端成功后才关闭弹窗。任何一项失败保留输入并提示；不吞异常、分段成功或后台默默丢附件。更新必须仅允许对应类型的任务，不允许把 progress ID 交给 outline 接口。
4. API 与权限矩阵（目标契约）
统一资源根 /business/surveyDesign/{resource}，resource 仅上述五值。建议五个薄 Controller 固定类型，复用业务 Service，禁止直接把任意 URL 字符串当数据库类型条件。权限统一 surveyDesign:{resource}:{action}。
| 方法/相对路径 | 请求/返回 | 权限动作 | 关键边界 |
|---|---|---|---|
| GET /list | PageQuery + lineId/bidId/siteId/surveyStage/taskName/status；R<PageResult<VO>> | list | 条件合并工程范围；空权限空列表 |
| GET / | R<SurveyTaskVO> | query | 详情、附件与子记录同范围 |
| POST 根路径 | 对应Form；R<ID> | add | 只建草稿，返回原始主键 |
| PUT 根路径 | 带id的Form；R<Void> | edit | 仅可编辑状态，服务端清除越权字段 |
| DELETE / | ID列表；R<Void> | remove | 全部逐项核对类型、范围、状态；一项不符整批失败 |
| POST /export | 与列表相同条件；xlsx流 | export | 同列表范围；不受当前页限制 |
| POST /{id}/submit | nextHandlerIds；R<Void> | submit | 草稿发起或退回重提；不可另建重复实例 |
| GET /{id}/next-handlers | 当前登录人当前节点之后的候选信息 | query | 先查任务范围；按当前任务节点解析真实目标节点，校验资源权限、节点组织/岗位资格及目标人员本人工程授权；流程结束返回空 |
新增尚无 ID 时，先保存草稿，再取下一节点候选并提交；不要为了选人临时启动实例。后续节点可由工作流候选能力驱动，勿造全局所有人下拉框。
办理复用平台 WorkflowService 与现行任务操作端点，不新增 approve/reject/update/delete 等未登记权限码。业务办理入口至少要求资源 query 与平台适用任务权限，服务端同时核验该用户当前 taskId 及工程范围；审批意见、附件和下一步人按平台 DTO 传递。若需模块专用业务校验接口，先与流程实际调用链对齐，不能前端先改业务状态再调引擎。
通用办理入口的服务端校验落点
现行 /workflow/task/completeTask 复用入口不会自动识别新模块工程范围，不能只在勘察详情接口或页面校验。已核对平台存在同步前置事件 WorkflowTaskCompletingEvent：CompleteExecuteComponent 在 taskService.skip 前通过 WorkflowTaskCompletionEventPublisher.publishBeforeCompletion 发布；FlwTaskServiceImpl.backProcess 在退回前发布 REJECT；现有转办/人员变更等支持入口也发布 ASSIGN 等动作。质量模块 QualityProcessEventListener.validateQualityTaskAction 是真实接入先例。
本模块增加 SurveyProcessEventListener（设计类名），使用同步 @EventListener 处理该前置事件，限定五个已登记 flowCode，通过事件 businessId 读取未删除任务，核对 flowCode与taskType、当前任务/实例关联、对应资源 query权限、工程范围及适用当前任务资格；申请节点提交还要求 submit权限。COMPLETE 中选择的下一办理人与 ASSIGN 中接收人分别执行节点候选和工程资格校验。异常必须同步抛出终止引擎操作，不使用异步监听或 AFTER_COMMIT 检查。状态回写的 ProcessEvent 是另一职责，不能用事后回写代替前置鉴权。
优先复用此扩展点，不新建一套审批包装层，不使workflow工程反向依赖business模块。只处理勘察流程，不改变其他业务语义；实施时核对实际开放的标准动作及其前置事件覆盖。通用入口回归至少直接调用完成和退回：当工程授权被撤销或资源权限缺失，须在引擎推进前拒绝。平台自动审批路径也调用此前置事件，沿用平台条件，不因监听器误阻断合法同人后续办理。
4.1 计划和进度专用 API
| 资源/路径 | 功能 | 权限 | 约定 |
|---|---|---|---|
| fieldPlan GET /boreholes/import-template | 下载钻孔模板 | surveyDesign:fieldPlan:import | 完整权限码 |
| fieldPlan POST /boreholes/import-preview | multipart file；行校验结果 | surveyDesign:fieldPlan:import | 解析校验不落库；不创建OSS业务附件 |
| fieldPlan POST /{id}/boreholes/export | 导出计划钻孔 | surveyDesign:fieldPlan:export | 必须先校验任务范围 |
| progress GET /plan-options | 可引用计划 | surveyDesign:progress:query | 只返回授权范围内当前有效且已通过的计划版本，调整待批时仍返回原版本 |
| progress GET /plan/{planTaskId}/boreholes | 带分页计划钻孔 | surveyDesign:progress:query | 逐孔选择；不泄露其他计划数据 |
导入模板固定列：地探孔编号、设计坐标X(m)、设计坐标Y(m)、预计孔深(m)。行号为数据行在工作簿中的实际位置。返回 {valid, rows, errors:[{rowNumber,column,message}]}；模板错误、重复编号、非数值等整批不应用，用户修正后重试。预览成功由页面合并到本地明细，最终保存事务统一落库。默认追加，不无提示覆盖已存在孔；同编号冲突报错。明细导出与模板列一致，列表导出另按台账列，两者不得混淆。
计划台账复用fieldPlan的list/export，一行一份版本任务；完成台账复用progress的list/export，一行一次上报，保留所有可见状态、引用计划版本、本次/累计/计划孔数、完成率、日期、影像数及发起/审批信息。计划行的“计划完成台账”入口跳转进度台账并携带rootPlanTaskId筛选，同根各版本上报均可查看；计划台账入口使用既有计划页。两个入口复用原查询、分页、导出和工程鉴权，不新增独立菜单或根计划汇总接口。progress列表/导出支持rootPlanTaskId及可选planTaskId筛选；服务端核验引用可见、两个条件不冲突，不能用筛选条件覆盖工程范围。
4.2 累计与计划调整的新增契约
progress POST /cumulative-preview（surveyDesign:progress:query）：传planTaskId、currentTaskId?、selectedBoreholeIds[]，返回previousTotal、currentCompletedCount、cumulativeCompletedCount、planBoreholeCount、completionRate。先校验计划可见、每个孔属于引用版本且有效、同单无重复；当前任务若存在须为可编辑的草稿或退回progress，编辑预览另校验edit及可编辑资格，不能任意指定排除对象。未换计划时沿用本单在原根中的前缀累计；显式换计划时校验新版本为当前有效，按新根现有有效贡献累计，保存后正式切换引用，避免把旧根或本单旧值带入新计划。新建引用当前有效版；既有单未换计划时允许历史版。只加当前选孔数量一次，不接收手填数量。保存、列表、详情和导出复用下文派生规则，不在审批回调执行“累计+本次”。fieldPlan POST /{id}/adjustment（surveyDesign:fieldPlan:add）：校验源为当前有效已通过计划，产生新的fieldPlan草稿、计划扩展、钻孔及附件引用；由服务端生成同一rootPlanTaskId、previousPlanTaskId，不接受客户端指定。新任务、新钻孔版本行使用新ID，原版本不更新；不会物理复制或删除OSS文件。- 调整草稿的编辑、删除、提交复用fieldPlan既有接口及对应edit/remove/submit权限；调整提交沿用
survey_field_plan同一节点链，新调整单拥有独立业务ID和实例，退回后仍在该调整实例续办。与原业务单退回重提不是同一行为。 fieldPlan GET /{id}/versions（surveyDesign:fieldPlan:query）：按根返回调整序号、审批状态、是否当前有效、来源版本、调整人/创建时间及审批关联，先校验该计划范围。计划详情返回rootPlanTaskId、previousPlanTaskId、effectivePlanTaskId、isEffective、adjustmentCount。- 原计划及通过版本保持finish与历史只读。只有调整流程最终完成且确认通过时，在同一业务事务回写新版本finish并更新根记录的
effectivePlanTaskId；草稿、审批中、退回、终止都不切换。旧进度仍引用原计划版本和原钻孔行，不自动迁移；后续新进度引用当前有效版本。已建立进度草稿也不静默改绑新版本。 - 同一业务计划跨版本用rootPlanTaskId归组，不能因调整ID变化把累计清零。调整次数由同根已通过且已生效过的非初始版本计数，普通编辑和同单退回重提不增加。
4.3 累计顺序、版本写入和展示约束
**累计顺序采用实施设计口径：**同一rootPlanTaskId内按主任务create_time ASC, task_id ASC作为稳定上报顺序；这是实现排序决策，不新增用户填写的业务日期。已保存记录R只聚合顺序严格早于R且属于已确定统计集合的记录，再按下述状态及编辑预览规则加入R本次贡献；排序/分页/查询筛选仅影响展示，不能改变累计基数。新建尚无ID时预览位于现有记录之后，保存后使用服务端实际顺序重算。历史有效贡献要求主任务与进度扩展未删除、submit_time非空且status属于waiting/back/finish；其本次数量为有效progress_hole行数。草稿及cancel/invalid/termination等排除，不能因有submit_time就计入所有状态。
例：A/B/C均已提交且处于有效统计状态，本次分别为1、2、3，则列表/详情/导出分别为1、3、6；B退回申请节点后预览编辑为4，应为1+4=5，不含C；保存后各行按现值重算为1、5、8。此为实时累计展示，不把查询结果伪称审批时冻结快照。未选择孔时本次数量为0；累计使用Long求和并遵循大整数序列化，不能让多次Integer相加溢出。
**本单贡献与草稿预览：**列表、只读详情和导出的累计只包括顺序不晚于本单的有效已提交记录。未提交草稿、撤销、作废、终止记录的本次选孔数可展示，但本单不贡献累计；草稿仅在具有编辑资格的本单编辑预览中临时加上当前选孔数，不改变其他上报累计。退回修改的编辑预览替换本单旧选孔数；保存后本行及后续记录按新值重算。提交成功进入waiting后立即成为有效贡献；提交失败回滚仍为草稿。排除状态仅约束统计，不新增撤销、作废或删除操作权限。
**选孔及完成率：**holes就是本次勾选要报的完整明细集合，不另设可编辑本次数量或isSelected列；移除勾选即从本单集合移除，保存按稳定ID维护关系。每单同一boreholeId只能一行，重复请求明细拒绝，跨不同上报允许同孔再次上报且分别计数。completionRate的分母始终取本单planTaskId指向版本的有效计划孔数，不随根当前有效版本切换。历史行按当前有效贡献重算，属于实时口径，不是审批时冻结统计快照。
**版本系统字段写入：**普通POST只生成初始计划（root=self、previous=null、effective=null、effectiveTime=null）；调整入口从服务端读取当前有效源版生成root/previous。普通PUT不得修改根ID、来源ID、生效指针、生效时间。调整拷贝须清除实例、审批状态、发起信息、审计与生效字段，按新草稿重新生成；不可MapStruct全量复制源实体。调整版的项目、线路、标段、工点、勘察阶段继承根计划并只读，服务端拒绝改归属后仍挂旧根。
仅根行存effectivePlanTaskId；从任意版本读取详情/候选时先解析根行，不能直接把调整行的空指针当“没有有效计划”。版本通过后同时写本版本effectiveTime与根有效指针，旧版本effectiveTime保留。进度planTaskId不变时允许保存/续办仍引用历史版的既有记录；新建或显式换计划时必须选择当前有效版，并清理不属于新版本的本地孔明细后由用户重新选择。不能用“所有保存都必须当前有效版”卡住原版本下已建立的进度。
**台账呈现设计：**外业计划基础台账按版本任务分页，每行保留自身审批状态，增加只读“当前有效”标记；已通过的历史版不再显示计划调整入口。版本历史通过现有调整次数/详情穿透到versions，无需新增独立业务菜单。有效计划选择器按根只返回一个当前有效版本，调整未通过时继续返回旧版，不把“最新创建”当“最新生效”。该台账就是已确认的计划任务台账，完成台账是4.1节的进度上报台账。
4.4 多次调整历史与前后对比
用户已明确要求每次调整保留计划前后数据。初始版revisionNo=0；每次创建调整草稿由服务端为同根生成递增revisionNo（包含已软删除版本的既有序号，不重新编号，不复用旧号）。序号表示第几次调整记录，adjustmentCount表示已生效调整次数，两者不能混用。草稿编辑、退回重提仍是同一调整记录、同一序号，不额外生成版本。
增加fieldPlan GET /{id}/comparison，权限surveyDesign:fieldPlan:query；id必须是可访问的调整版本，返回before（previousPlanTaskId的完整只读数据）、after（当前调整版本完整数据）、changedFields、boreholeChanges、attachmentChanges及两侧任务/版本/审批标识。初始版没有来源，明确返回before=null，不伪造调整记录。后端反查前后记录同根且归属一致，不能允许客户端传两个任意ID做跨范围比较。
历史入口放在计划详情/调整次数穿透内。历史列表展示初始版及各次调整的序号、来源版本、审批状态、生效时间和是否当前有效，每行提供“查看”和“审批记录”明确入口；“查看”打开该版本的完整资料区，顶部按真实状态标注已通过/草稿/退回/当前有效，并以页签提供“差异摘要、调整前完整资料、调整后完整资料、审批记录”。差异摘要保留日期、钻机数、紧急程度、说明、钻孔数量、逐孔编号/坐标/预计孔深以及分类附件的增加/移除；前/后完整资料复用只读详情，展示未变化字段、全部钻孔和全部附件；审批记录复用现有流程时间线。初始版before=null，前侧页签明确显示“初始版本没有调整前资料”，不伪造前侧版本；草稿/退回按真实状态展示。长表分页只影响显示，不影响完整对比。不新增业务菜单，不覆盖已通过历史，不另建审批表。
调整复制钻孔时为新行生成boreholeId，并将源行ID写入sourceBoreholeId；新增孔该字段为空。比较时按sourceBoreholeId关联来源版本的原行，缺少对应后行表示删除；同一来源孔不能映射两行，来源孔必须属于本次previousPlanTaskId。这样孔编号被修改也能识别为修改，不误判为删除后新增。该字段只用于版本溯源，不作为累计数量去重键。
已通过版及附件关系不可改写；后续调整仅复制引用并修改自己的关系。前侧始终读取来源已通过版，后侧草稿/退回时显示当前待定内容并标注状态，通过后成为只读历史。比较使用版本中保存的值/快照，不用最新工程名称、最新附件分类或当前有效计划覆盖历史。编辑本次、删除可删除草稿均不能影响前侧记录和OSS原文件。
验收链：V0已通过→调整1(V1)待批时仍执行V0→V1通过后执行V1→从V1发起调整2(V2)，前后分别为V1/V2；V2未通过仍执行V1，V2通过后执行V2；始终能查看V0/V1、V1/V2两次完整差异及各自审批记录。
5. 工程授权与操作边界
EngineeringDataAccessHelper 实际存在 assertPairVisible/applyPairScope、assertBidVisible/applyBidScope、assertLineVisible/applyLineScope。不要新增已移除的 @DataPermission/@DataColumn。
本设计以 lineId 为空间归属基础，bidId 为合同归属且暂未建立标段时允许为空，工点可空。校验和查询按四类互斥分支：
- 标段+工点：校验有效
(lineId,bidId,siteId)组合，并用BIZ_BID_SITE_SCOPE（指定工点型）或同线（全线统包型）确认工点在标段管辖范围内； - 无标段+工点：按工点共享范围判定（整线授权或任一当前有效组合包含该工点）；
- 标段级（有标段、无工点）：整线授权或该标段有效组合投影；
- 无标段+无工点：仅整线授权。
不得将四类 helper 顺序 AND 施加到全部记录，也不能用标段分支放行有工点记录。项目存在时必须属于标段 BIZ_BID_PROJECT_REL 的项目集合；标段唯一关联一个项目时服务端自动带入，多个项目时由用户选择。含标段记录还应校验标段属于当前线路。保存仍以服务端回写的 lineId/bidId/siteId/projectId 为准。
同一过滤覆盖列表、导出、详情、修改、删除、提交、逐孔选择、附件关联和候选办理人。写入更换工程范围时同时验证旧记录可操作与新归属可访问。子记录 ID 必须反查所属 taskId；附件上传成功不意味着可关联任意他人 OSS 对象。
菜单权限不是任务权限。当前办理人才能审批；草稿由createBy对应人员编辑；退回由引擎当前申请人任务持有人修改并续办，已通过与流转中业务数据只读。此为平台固定表单操作设计，不因原型通过行显示“办理”而允许无任务审批。候选办理人必须同时满足资源query权限、目标节点组织/岗位资格和目标人员本人工程可见性；完成和转办在引擎推进前按真实目标节点复核，不能因办不了就默认全员或管理员代替。节点组织/岗位映射使用平台现有SYS_DEPT组织分类（dept_category 设计20/勘察23等）和SYS_POST岗位名称；建设单位节点优先按项目BUILD_UNIT_ID限定本公司及下属部门，无法解析项目时只保留建设单位内设部门范围并记录缺口。不写死具体部门、岗位或人员；未知节点直接拒绝，不能退化为结束或全员可办。
6. 工作流调用与状态回写
优先参考 planning/workflow/PlanningWorkflowHelper.java 的机制：通过 WorkflowService.startCompleteTask(StartProcessDTO) 发起，设置 businessId=任务ID字符串、flowCode与 businessTitle；用 getInstanceIdByBusinessId 取得关联。listCurrentTaskIds 按登录用户核实当前任务，不信任前端 taskId。
五条节点顺序以需求分析为准；每条定义独立编码和分类。只复用适用的机制，不复制规划征求意见、会签、重启版本等无来源能力。新原型没有地勘监理/外业见证并行链，不从旧文档恢复。
| 操作/事件 | 业务状态 | 要点 |
|---|---|---|
| 保存新增 | draft | 不启动流程 |
| 草稿提交成功 | waiting | 发起失败整体回滚，不先写“进行中” |
| 非末节点通过 | waiting | 引擎进入下一节点，不能直接 finish |
| 退回申请节点 | back | 与FlwTaskServiceImpl.backProcess一致；当前申请人任务持有人可修改重提 |
| 退回中间审核节点 | waiting | 引擎保持进行中；仅目标审核节点办理人可处理，申请人不得编辑 |
| 退回后修改重提 | waiting | 完成当前申请人任务，延续实例，保留历史 |
| 引擎真正结束 | finish | 监听事件后回写；以适用定义结束语义为准 |
工作流还有 cancel/invalid/termination 等状态，若平台标准动作触发必须按枚举正确显示与只读控制，不当作 finish，不擅增模块专属撤销/作废业务按钮。事件处理必须按 businessId与flowCode限定本模块；读历史已办理任务记录意见，不能把新事件中的下一办理人当刚办完的人。审批历史优先由平台引擎查询，不再建一张重复审批表。
事务范围是本模块保存/提交的数据库边界；核对工作流 API 是否在同事务执行。若实际存在外部调用，先核实现有一致性处理再设计失败恢复，不宣称本地注解自动回滚远端，不默默补造重试/分布式事务。
7. 类与文件落点（设计）
后端在现有 business Maven 模块中增加 com.bokun.business.surveydesign 子包，按 controller/domain/bo/vo/mapper/service/impl/workflow 分层。推荐共同 SurveyTask、SurveyTaskService 与 SurveyWorkflowHelper，计划/进度复杂逻辑在对应 Service；不建立万能动态字段 JSON 表。
前端 src/views/business/surveyDesign/{resource}/index.vue 与 flowForm.vue，公共表头、附件及工作台按实际复用抽取到同域 components；计划和进度各自明细组件。API 为 src/api/business/surveyDesign/{resource}/index.ts 和 types.ts，共享类型按实际引用放同域。不得用 any 掩盖五种表单差异。
AxiosPromise 从 @/utils/api-types 引入，PageResult 从 @/api/types 引入；后端 BaseEntity 仅提供五个审计字段，不自带 delFlag/version/tenantId。全部 ID 保留 string|number 原值，后台 Long 沿用 BigNumberSerializer。
8. 待定边界与验证
Q-SM-001/002/003/008均已关闭，按已确认统计集合、选孔数量、完成率、台账和调整历史实施。节点组织映射及字典/合同先核实现状；确有缺项仅暂停依赖配置，不导入启用无人可办或全员可办的流程。
验证覆盖五类隔离、保存回显、导入失败不落库、删除保护、精确工程组合、无授权直接访问、无工点标段记录、当前办理权限、退回实例延续、附件取消编辑、状态事件回写。具体用例与未执行状态见测试与验收。
9. 实施结果与偏差（2026-11-03）
| 项目 | 实施结果 |
|---|---|
| 后端 | com.bokun.business.surveydesign 下 controller/domain/bo/vo/mapper/service/support/workflow 分层；五个薄 Controller 固定 outline/fieldPlan/progress/special/result，权限码逐字登记。 |
| 前端 | src/views/business/surveyDesign/ 五个台账与固定办理页；共享 SurveyLedgerPage、SurveyTaskFormDialog、SurveyDetailPanel、SurveyVersionDrawer、计划/进度明细编辑组件；API 在 src/api/business/surveyDesign/。 |
| 菜单/路由 | 菜单按“勘察设计管理 → 勘察管理 → 勘察大纲/外业计划/进度上报/专项勘察/勘察成果”平铺；/surveyDesign/survey/{resource} 与办理页 /surveyDesign/survey/{resource}/flowForm 均按设计落位，未使用 .. 拼接路径。 |
| 新增接口 | GET /{id}/process-info 供办理工作台展示流程名称/版本，并返回currentNodeCode、nextNodeCode、needNextHandler，用于区分结束节点与仍需选人的节点；钻孔模板下载改为 POST /boreholes/import-template 以复用平台下载封装；其余按 4.1/4.2 契约实现。 |
| 流程 | 开发库已导入并发布 survey_outline/survey_field_plan/survey_progress/survey_special/survey_result V1；生产入口有限连通检查不可达，生产待同步；节点为最新串行链，全部 ${nextHandlerId}，无并行/见证/监理节点。SurveyProcessEventListener 同步监听 WorkflowTaskCompletingEvent，校验 flowCode、业务类型、资源权限、工程范围、任务关联及下一办理人。 |
| 累计 | 服务端按同根计划 create_time,task_id 稳定顺序取截至本单的有效已提交记录；本次数量取有效选孔明细行数；不存手填数量；草稿仅编辑本单预览；退回改选重算；完成率分母取本单引用版本。 |
| 调整 | root_plan_task_id/previous_plan_task_id/revision_no/effective_plan_task_id/effective_time 按设计实现；仅最终通过时切换有效指针；调整版归属/阶段只读；多次调整序号含已软删除行递增；versions/comparison 按 source_borehole_id 对比。 |
| 偏差 | 菜单未单独建立“勘察外业”目录，以避免平台 filterChildren 对子路径的拼接使精确路由失配；流程分类仍保留“勘察外业”。此偏差不影响业务能力、权限或接口契约。 |