主题
勘察管理 · 概要设计
文档版本：1.01 ｜ 最近核对日期：2026-11-03
| 项目 | 内容 |
|---|---|
| 设计依据 | 需求分析与 2026-10-24 最新原型 |
1. 架构位置与边界
勘察管理位于勘察设计管理之下，包含五项固定表单业务。前端承载台账、编辑和业务办理内容，后端业务层承担单据、明细、附件引用、工程范围及流程协同。复用现有工程基础数据、组织人员、文件服务和 Warm-Flow，不建设主数据维护和独立任务中心。
总体与方案设计、初步设计、施工图、设计巡检、考核仍由父级资料维护，不借本次新原型统一改成五种业务的通用表单。
2. 业务分解
| 单元 | 职责 | 设计边界 |
|---|---|---|
| 大纲、专项、成果报审 | 基础信息、正文、分类附件、提交和流程关联 | 可复用实际相同的表单结构；保留各自业务标题、附件分类和审批链 |
| 外业计划 | 计划信息、布孔文件、计划钻孔与表格导入导出 | 调整走原流程，新版本通过前原已通过版本继续有效，历史不覆盖 |
| 进度上报 | 关联计划与勾选钻孔、实际日期/孔深、逐孔影像 | 本次数量按选孔数派生，累计和完成率按需求已确认规则计算；完成台账一行一次上报 |
| 工程范围 | 关联合法工程对象，统一过滤查询、写入和候选 | 依赖工程授权服务，不使用已移除的角色数据范围注解 |
| 流程协同 | 提交、待办、状态回写、办理历史与流程图 | 引擎负责运行时任务；业务表不能替代引擎判定办理人 |
主业务类型采用 outline/fieldPlan/progress/special/result。类型是服务端白名单，不允许请求参数动态选择任意表、类、权限码或流程编码。
3. 数据与流程关系
外业计划拥有计划钻孔明细；进度记录关联计划和稳定钻孔标识，逐孔记录关联各自影像资料。大纲、专项、成果保留分类附件。审核状态及流程关联落在业务记录，引擎运行与审批历史仍由 Warm-Flow 管理。
主表与专有明细的物理拆分、完整字段与约束见数据库设计。计划版本使用同一计划扩展表中的根计划、上一版本和当前有效版本关联；调整版本各自关联审批实例与递增调整序号，历史提供每次调整前后完整对比，支持多次调整；保留已有版本即可取得前后数据，不另建通用版本框架。进度保留引用版本和计划根标识，各行累计按同一业务计划内截至该记录的本次值求和；后续上报不进入较早记录。调整版本保持原工程归属，生效指针只由通过事件维护。
3.1 状态模型
| 状态 | 进入原因 | 退出与数据影响 |
|---|---|---|
draft | 新建并保存草稿 | 提交前校验通过后进入 waiting，保存不启动流程 |
waiting | 提交或合法重新提交 | 审批通过到下一节点仍为 waiting；流程结束才到 finish；退回申请节点到 back，退回中间审核节点保持 waiting |
back | 引擎确认退回申请节点 | 依允许目标和记录操作资格修改、重提；不能单凭前端状态恢复到任意节点 |
finish | 最终节点完成且引擎确认结束 | 普通接口只读；调整版本走原流程，通过后替换有效指针，历史版本状态仍为finish |
业务记录、流程实例、当前任务 ID 必须互相对应。状态变化从可信引擎结果回写，不能让前端提交 finish 或当前节点名称来推进流程。
3.2 五项流程
业务角色顺序的唯一正文见需求分析第 4 节。五项均按最新原型串行，不保留旧资料中的并行勘察审查分支。计划、进度、专项虽节点结构相似，仍保留各自流程身份、表单路径、业务权限及历史归属，不共用一个流程编码混淆业务。
流程分类沿页面层级建立：“勘察设计管理 / 勘察管理”下的大纲、专项、成果；外业计划和进度位于“勘察外业”分类。流程定义以叶子业务名称命名。实际节点办理人映射待 Q-SM-004，不能仅绘出图就声明可执行流程。
4. 页面与交互方案
五项业务分别有台账入口，外业计划与进度按勘察外业层级组织。新增和修改在台账编辑表单完成；查看与办理进入固定表单工作台，共用同一业务内容显示组件，只读与当前任务操作明确分离。
台账采用平台查询卡、列表卡、右侧操作组和分页。审批状态紧邻操作列并连续固定右侧；长文本省略并可查看完整值。外业计划钻孔表使用适合宽表的编辑空间，不能为复制原型小弹窗而叠加多层横向滚动。工作台左侧业务表单、右侧审批时间线，流程图使用底部抽屉；附件在站内预览。
用户选择、文件上传及工程选择沿用平台契约，具体已核对组件与属性见详细设计。不创建自有通讯录，不把字段名和 API 请求过程写在用户页面正文。
5. 权限与信任边界
功能资格、工程范围、记录操作资格、当前任务归属四层承担不同职责：
- Controller 校验实际资源对应的三段式功能权限。
- Service 按“标段+工点、无标段+工点、标段级、无标段整线”四类互斥分支使用
assertPairVisible/applyPairScope、assertSharedSiteVisible/applySharedSiteScope、assertBidVisible/applyBidScope、assertLineVisible/applyLineScope；标段暂未建立时允许为空，查询和写入使用一致规则。 - 修改、删除、提交校验状态及操作资格：草稿校验 createBy，退回校验当前申请人任务持有人，并核对功能权限和工程授权；不能通过“有 edit 权限”替代。
- 办理接口核验引擎任务归属、实例关联和允许动作，再通过统一流程机制执行。
附件引用、Excel 输入和客户端隐藏字段均为外部输入。文件对象存在不代表可关联到任意业务；导入孔号不能把记录关联到其他计划。ID 保持平台大整数契约。
6. 一致性与失败恢复
主单与明细、附件引用等关联更新在明确的 Service 事务内完成。导入先解析校验，再按确定的合并规则一次性保存；失败输出定位信息，不静默丢行。提交失败不能留下业务已进行中但引擎无有效任务的状态；复用成熟流程集成机制并针对实际异常验证回滚。
上传与业务保存是两个生命周期；取消编辑时不主动删除已保存业务所引用的文件。提交、退回或保存失败保留可恢复内容。项目按低并发设计，不为了理论竞争新增锁、分布式事务框架、通用幂等平台或无依据重试。
7. 设计依赖与验证
全部事项及边界见待确认事项与实施核对。统计、计划调整与台账粒度均已确认，可实施；角色候选、字典与合同由实施者先实际核对，确缺业务映射仅暂停对应配置。单任务单范围按一期设计推进，不新增确认点。
验证覆盖工程组合授权、五项实际流程、草稿与只读、导入、附件、失败回滚及大整数 ID；具体用例见测试与验收。本次已在开发环境完成六表落地、五条流程导入发布、前后端实现及代表性页面/流程验证；生产未访问，生产发布与完整业务验收待后续安排。
8. 实施结果（2026-11-03）
- 后端新增
com.bokun.business.surveydesign：任务头、计划扩展、计划钻孔、进度扩展、逐孔进度、分类附件六表；ISurveyTaskService统一五项业务，五个薄 Controller 固定资源类型与权限码。 - 前端新增
src/views/business/surveyDesign/{outline,fieldPlan,progress,special,result}台账与固定办理页，flowFormRoutes.ts/flowFormPaths.ts已登记 5 条办理路径。 - 开发库六表、索引已建并回读；五条流程已导入、发布并回读节点/连线；流程分类为“勘察设计管理/勘察管理”与“勘察设计管理/勘察外业”。
- 菜单为“勘察设计管理 → 勘察管理 → 勘察大纲/外业计划/进度上报/专项勘察/勘察成果”，外业两项按业务顺序排列；流程分类保留“勘察外业”分组，路由保持
/surveyDesign/survey/{resource}精确路径。 - 组织/字典核对见需求分析第9节。