主题
前期管理 · 详细设计文档
文档版本:1.20 | 最近核对日期:2026-11-11
本设计落实用户已确认的12项业务答复及4项补充确认。前期十四表实体、强类型快照、A/B/C版本留痕、四类业务台账页面与flowForm办理页、流程定义及GIS受控发布与进度卡点互通服务均已完整实现并通过自动化测试验证。业务规则以需求分析为唯一正文,字段见数据库设计。
1. 页面、角色和单位工程
四个台账资源标识为landAcquisition、utilityRelocation、trafficDiversion、greeningTransplant,路由/preliminary/<资源>,组件business/preliminary/<资源>/index;固定办理页后缀/flowForm在flowFormRoutes.ts、flowFormPaths.ts、隐藏菜单和流程FORM_PATH一致注册。流程编码分别preliminary_land_change、preliminary_utility_change、preliminary_traffic_change、preliminary_greening_change。
本期不建独立总览、统计图表和原型聚合页签。台账保留条件查询、分页、详情、审核状态、逐关进度、滞后及缺证/期限提示。详情/表单分区为基础资料、单位工程、关口矩阵、植物(绿化)、手续、卡点、空间和审核差异;地图显示四类业务图层,可切显隐。
unitProjectId必填,选择器优先复用ProjectBidSiteCascader.unit及完整modelPath。后端读取有效UnitProject,以其真实lineId/bidId/siteId/majorCode和名称产生上下文,统一assertPairVisible及同源列表谓词。不得新增unit白名单权限或把major独立授权;用户已确认同标段×工点组合沿现有授权。不能信任客户端名称或归属,不按siteId反查首个标段。
施工维护资格:所属标段constructUnitId及有效人员组织归属、动作权、工程范围。监理资格:superviseUnitId、有效人员资格/角色、工程范围及本人有效任务。标段负责人不自动等于唯一审核人,选择器只解决交互,不替代服务端资格判定。已有企业引用组织ID和名称快照,外部责任主体不伪造账号。
1.1 可编辑矩阵
| 场景 | 施工维护人 | 当前合格监理 | 其他有查询权人员 |
|---|---|---|---|
| 初始或修订draft | 维护工作版本、保存、提交 | 无任务不可改 | 按范围只读 |
| waiting | 原提交只读 | 复核全部;仅卡点区可修订,疑似重复逐项确认;同意/退回 | 生效版与待审差异只读 |
| back | 修改原申请工作版、同实例重提 | 非本人当前任务不可继续办理 | 只读 |
| finish | 已生效版不可覆盖,可另发修订 | 不能再修改已完成审核工作版 | 当前及历史按范围可查 |
| 首次尚无currentRevision | 草稿/待审可查 | 正常审核 | 明示尚未生效,不报为正式完成 |
不额外开放删除、流程重启或全部标准工作流动作。动作显隐后端仍须鉴权,监理不能借卡点保存接口修改面积、计划、植物、手续或几何。
2. 强类型审核版本模型
目标模型:OBJECT稳定身份;CHANGE申请和流程;REVISION及分类/阶段/明细子表保存强类型业务快照。不再使用只有targetCompletedStep和几个目标日期的旧ChangeBo,该结构不能承载用户已确认的基础资料、附件、空间审核。
2.1 版本生命周期
- 新增生成OBJECT和初始CHANGE、工作REVISION及子项,currentRevisionId为空;修改已生效对象时从currentRevision克隆完整工作版,baseRevisionId指向原正式版。
- 施工在draft/back保存工作版;提交验证后冻结一份submittedRevision,另有workingRevision供本轮审核。提交版保存施工原稿,不能被监理修改覆盖。
- 监理只在workingRevision保存卡点修订,记录修订人/时间并可与提交版逐项对照;不把修订直接写currentRevision。
- 同意时将审核工作版以APPROVED冻结并关联本轮SUBMITTED及监理人时,成为正式内容,原子切换OBJECT.currentRevisionId;旧版及施工提交快照保留。
- 退回时将本轮工作稿冻结为REVIEWED,SOURCE_SUBMITTED_REVISION_ID指向本轮施工提交并记录审核人/时间,再复制新WORKING给施工修改;申请和流程实例不变。重提产生新冻结提交,旧SUBMITTED与REVIEWED均保留,施工A→监理B→施工C的B不能被覆盖。
snapshotRole用于数据用途,不是乐观锁version。版本子表不存整份业务JSON或任意字段EAV;空间WKT是明确几何类型,不是绕开业务建模。
2.2 首次保存和完整克隆算法
首次草稿最低要求为有效unitProjectId、当前用户有施工维护资格及非空objectName。其他分类资料可未齐;保存草稿与正式提交使用不同校验组。流程状态、快照角色、归属、操作者和正式指针均由服务端设置。不得在CreateBO上使用一套提交必填注解,使草稿也必须先填全部计划、面积或附件。
首次创建在同一事务预分配objectId、changeId、workingRevisionId,再依次插入OBJECT(currentRevisionId为空)、CHANGE(workingRevisionId已是预分配的非空ID)、REVISION、对应一行分类扩展和全部关口骨架。其余实际提供的子项按顺序写入。不采用“先插workingRevisionId=null,最后UPDATE”的写法。当前关系为逻辑外键;若实施增加即时物理外键,须先调整循环引用约束和写入顺序,不直接照搬本顺序。
每次复制快照,必须在同一事务执行以下步骤:
- 为新REVISION及所有需要复制的子行分配新主键,创建新角色及正确的objectId/changeId关联;不复用旧子行主键。
- 复制分类扩展、关口、植物;扩展主键改为新revisionId,其余行同时改新ID和revisionId。审计字段由当前插入填充,不将原创建人当本轮操作者。
- 先复制ATTACHMENT_REF,建立
oldAttachmentRefId -> newAttachmentRefId映射;FILE_ID沿用同一真实文件。PERMIT再复制,并将attachmentRefId改成新快照附件行ID,不得继续指向旧快照。 - 卡点ISSUE_KEY、空间SPATIAL_KEY沿用同对象的稳定键;卡点附件的BLOCKER_KEY沿用稳定键,但REVISION_ID必须变为新快照。sourceIssueId等系统结果只从受控旧正式结果读取,客户端不得伪造。
- 从正式版开始新修订时,以已发布要素结果解析空间基线:publishedFeatureId优先,其次是原existingFeatureId;向GIS读取有效要素当前revision,写为新工作稿的existingFeatureId/expectedRevision。不得把初次发布前的null ID或旧revision直接复制成下一轮基线。
- 清空不属于新工作稿的审核人时和sourceSubmittedRevisionId;正式提交冻结时设置本轮关联。旧SUBMITTED、REVIEWED、APPROVED及其全部子行不可更新或清理。复制任何一步失败,整次复制回滚。
提交复制SUBMITTED、退回冻结REVIEWED后复制新WORKING、从正式版发起UPDATE都调用上述同一深复制职责。审批通过只把当前审核工作稿冻结为APPROVED并切换正式指针,不再次复制一份会丢卡点修订的施工原稿。接口返回新快照及新附件行ID,前端必须回填,不能继续用上一轮attachmentRefId保存手续。
2.3 DTO
LedgerQuery:pageNum/pageSize、unitProjectId、线路/标段/工点筛选、类别条件、审核/滞后/手续状态;后端附加真实授权。ObjectVO:objectId/type/code、unitProjectId及工程/单位快照、currentRevisionId、pendingChange、正式连续完成步数/总数、单条进度及本功能警告。无正式版与正式零完成区分。CreateBO:unitProjectId、initialRevision及初始申请说明,POST新增时必填真实单位工程;后续申请从OBJECT反取,不开放搬移归属。initialRevision使用下述RevisionBO。RevisionBO:revisionId、objectName、sourceBusinessCode(可空的来源台账编号,区别于系统生成编号)、类别基础资料detail、完整stages、plants、attachmentRefs、permits、blockers、spatialDrafts(SpatialDraftBO数组);四类detail单独强类型,禁止任意Map透传。没有空间候选为[],不写一行空几何占位。StageBO:stageCode、plannedCompletionDate、actualCompletionDate;不接收客户端自报completedStep。未完成实际可空,真实完成必须填写。PermitBO:attachmentRefId、attachmentLabel、expiryDate(上传fileId先保存到同快照ATTACHMENT_REF,不在PERMIT重复存fileId),一条台账可多条;不新增发证/续期字段。缺附件或日期作为警告,不让“辅助审核”变成强制停工。BlockerBO:稳定issueKey、描述、附件引用、既有sourceIssueId(服务端核实);不允许施工提交督办/上报/关闭结果。SpatialDraftBO:spatialKey、geometryType、geometryWkt、crsCode、layerId、existingFeatureId/expectedRevision(有则校验),新建可无existingFeatureId。字段分别对应GIS_DRAFT同名逻辑列,publishedFeatureId是受控服务结果,不接收客户端写入。业务类别决定面/点/点/点,客户端不得改成其他类型。SubmitBO:changeId、nextHandlerId;用户与原值由服务端取得。提交返回changeId/instanceId/flowStatus,正式内容仍由currentRevision读取。ReviewBlockerBO:changeId、工作版卡点列表,不接收其他业务区;服务端以当前有效监理任务和允许字段保存修订。
对象类别及单位工程作为身份上下文,不提供普通改归属入口;确需更正应先核实业务影响,不因表单有ID就允许跨单位工程搬移。
3. 逐关、日期和导入契约
3.1 计划和实际
每个版本有本类全部关口行,stageCode稳定,完整顺序见需求1.2。初始计划送审要求本类各关计划完成日期,实际仅已申报完成项填写。先后顺序校验来自关口顺序,业务日期使用平台自然日,不硬编码当前日期。
普通推进只允许在原正式连续完成数k上申报k+1实际完成,不允许同时将后面多关实际补成已完成;前置必须已审。初始进度也不免审核。用户已确认历史首次导入例外:连续前若干关真实已完成、各关计划和实际齐全且顺序正确时,可一次提交监理审核形成初始进度;这不是自动补关。历史缺真实时间可存草稿但不能伪造,日常UPDATE不能借历史标记跨关。仅计划或基础资料修订允许完成数不变;纯已交面积增加也可不推进关口,仍经审核。
已生效关口实际日期不因下一步提交重写。后续计划、实际、面积等纠正用新版本,检验顺序与已生效事实自洽;不默认实现“退回业务进度”新动作。阶段采用未完成/待审完成/正式完成,若没有真实开始事实,不凭0步臆断未启动。
征地腾地交地的计划/实际与交地确认计划/实际分别保存,避免“交付”和“确认”混一日期;交通恢复计划/实际直接取恢复关口,避免另外两组日期不同。单关滞后=未正式完成且业务日>计划完成日,提示阶段和天数;已完成晚于计划是历史偏差,不继续累计当前逾期。
3.2 完全重复和疑似重复
预检查不写业务对象;比较统一强类型规范值,排除生成编号/ID、审计、流程、修订标识等技术字段。业务明细按业务行集合比较,不以行排序制造新数据。输入文件内及库内(含已登记待审候选)都检查,不能同文件换行或再次上传绕过。
比较器显式接收excludeObjectId:本对象已经落库后首提、退回重提时,排除该对象及全部历史/工作/提交快照,不能把本条与自身比较成完全重复。库内每个其他对象只取当前正式版及有效未结束申请的当前候选,不遍历全部历史快照制造多份匹配。文件内按原始主表行号顺序处理,首个合法对象保留为候选,后续完全相同行拒绝;不能互相比对后把两行同时删掉。该规则用于正常导入/重提,不建立并发查重平台。
完全一致的对象及其明细拒绝,返回文件表名/行号、重复候选对象和原因,不提供“监理确认后放行完全重复”。若包含无权候选,不能泄露对方详情或越权跳转。
疑似重复匹配在同unitProjectId+类别内,分类识别:征地按工点业务对象+性质+批次;其余优先来源业务编号sourceBusinessCode(模板及REVISION.SOURCE_BUSINESS_CODE持久化),无则对象名+位置;仅线路/单位/类型相同不触发。识别相同但其他业务资料不同标为疑似,逐项列出差异和候选,监理在当前任务明确确认。响应包含submittedRevisionId及候选快照;每次退回重提重新比较,新一轮判断置PENDING并绑定本轮SUBMITTED_REVISION_ID,旧确认留存不复用;同意前校验确认与当前送审资料一致。不同批/永久临时分条允许,不按同工点一刀切。
导入将合法行和疑似行写为完整待审候选,疑似标记不能关闭或丢失;完全重复/非法对象拒绝,合法部分可继续。绿化主行与植物/阶段子行作为整体。监理确认允许保留新对象而非覆盖旧对象;不同意则退回该候选,不能删除已存在记录。审核前重查最新候选,不能信任前端布尔值。
4. 目标API
全部路径已实现,前缀/business/preliminary。资源标识参与三段式权限码,控制器不使用 @SaCheckPermission 注解占位符(Sa-Token 不解析路径变量),统一在方法入口按真实资源执行 StpUtil.checkPermission("preliminary:<资源>:<动作>"),与 SYS_MENU.PERMS 逐字一致。{resource}仅四类白名单,<资源>对应同名三段式权限。响应沿R、分页沿PageQuery/PageResult;ID前端string|number原值,后端复用BigNumberSerializer。
| 方法/路径 | 请求→输出 | 权限/责任 |
|---|---|---|
| GET /{resource}/list | LedgerQuery→分页对象 | preliminary:<资源>:list,同工程范围 |
| GET /{resource}/ | 当前正式/待审摘要及历史 | preliminary:<资源>:query,检查真实类别 |
| POST / | CreateBO→objectId/changeId | preliminary:<资源>:add,只建草稿 |
| POST /{resource}/{objectId}/change | 当前版→changeId/workingRevision | preliminary:<资源>:edit,克隆正式版 |
| PUT /{resource}/change/ | RevisionBO→草稿 | preliminary:<资源>:edit,施工本人draft/back,不能写currentRevision |
| POST /{resource}/change/{changeId}/submit | SubmitBO→流程关联 | preliminary:<资源>:submit,首提或同实例重提 |
| GET /{resource}/change/ | submitted/working/base及差异 | preliminary:<资源>:query,原稿历史可追 |
| GET /{resource}/{objectId}/reviewers | 对应候选 | preliminary:<资源>:query,真实监理资格与范围 |
| PUT /{resource}/change/{changeId}/review-blockers | ReviewBlockerBO→审核工作版 | preliminary:<资源>:edit+本人监理任务,白名单只卡点 |
| PUT /{resource}/change/{changeId}/duplicate-confirmations | 候选ID/确认结论/意见→结果 | preliminary:<资源>:edit+本人监理任务,不能确认完全重复 |
| POST /{resource}/import/check | 文件→错误/完全重复/疑似/可导入 | preliminary:<资源>:import,无业务写入 |
| POST /{resource}/import | 文件→待审候选及行级结果 | preliminary:<资源>:import,重新校验、无直接生效 |
| GET /{resource}/import/template | 分类多表模板 | preliminary:<资源>:import,平台下载 |
| POST /{resource}/change/{changeId}/spatial/preview | 候选点/面→预览和校验 | preliminary:<资源>:edit,施工草稿,非正式发布 |
| GET /{resource}/{objectId}/spatial | 正式/有权候选及图层 | preliminary:<资源>:query,两个版本明确 |
| GET /{resource}/{objectId}/blockers | 已审源内容+有权进度办理摘要 | preliminary:<资源>:query,不把断连当无卡点 |
手续、植物、卡点输入和空间候选通过版本保存,不新增直写正式资料接口。审核仍走平台任务办理API,不自建/approve绕开引擎;监理同意前必须保存卡点工作区及疑似确认。聚合summary/overview统计接口本期不建设。
5. 业务层与一致性
建议LedgerService负责对象及版本,RevisionSupport负责强类型克隆/冻结/差异,ChangeService负责提交和生效,StageRules负责逐关与日期,ImportService负责分类比较。只提取实际共享职责,不建任意资源通用引擎。
WorkflowHelper按draft首次startCompleteTask、back当前本人申请任务completeTask;businessId为changeId。WorkflowStartHandler在引擎办理前校验真实对象、资格、状态、逐关前置、已保存卡点及疑似重复确认。ProcessEventListener只匹配本四类flowCode,waiting/back不切正式版,finish应用候选。
同期审批引用BaseEntity完整审计列。审核意见及逐节点历史由平台流程提供,不再复制一套任意可改审批记录。工作版本只在特定用户/状态可改,提交快照及正式版冻结。
5.1 事务与失败
审核成功的必要写入包括正式指针切换、空间发布/绑定及有卡点时问题库接收。优先核实同源同步事务,参考工程手续普通同步EventListener;业务异常应使办理失败,原事实保留。无卡点/无空间候选不虚构接收动作,缺手续只警告,不引起事务失败。
本任务默认实现方式确定为同应用内窄Java服务/端口同步调用、同纳管数据源事务参与。business已依赖GIS,GIS不反依赖business;前期卡点接收和GIS发布新服务应参与外层事务,不使用REQUIRES_NEW,不经HTTP调用本应用接口,不用@Async/AFTER_COMMIT,不捕获异常后返回成功。先校验,后在同一事务应用必要集成和正式指针/流程结果;通过受控服务返回的发布ID和源问题ID只作结果关联。
P0核验实际数据源及引擎事务,若与上述首选不一致,先报告可复核差异并修订最小接入方案;不自行切换外部队列、异步补偿或放弃一致性。已有正式GIS引用或进度督办不能因审批失败清理掉。故障测试至少在业务生效、GIS写入后、问题接收后分别抛错,回读任务、申请、正式指针、GIS要素和问题来源记录,不能仅看接口返回失败或事务注解。
6. 三项能力的最新落地责任
6.1 手续已转为本模块辅助附件
每份Permit为attachmentLabel+attachmentRefId+expiryDate,FILE_ID仅在其同快照附件引用中持久化,允许多份;不建证照号、发证、续期、外部办件,更不继续等待工程手续有效期API。无附件、未知期限作为具体警告,允许进度维护/送审/生效。30日前临期、当天有效、次日过期,仅本功能红提示并配文字;不扩首页、通知或停工控制。正式警告取正式版本,审核页同时显示候选状态,待审上传不提前消除旧警告。
6.2 卡点由前期输入并互通进度
接收契约建议为sourceType=PRELIMINARY_OBJECT、objectId、unitProjectId、issueKey、approvedRevisionId、description、attachmentRefs、submittedBy、reviewedBy及审批时间。服务端核实工程和来源版本,不接受前期自报督办结论。
同sourceType+objectId+issueKey更新同问题,返回sourceIssueId;不同问题用不同issueKey。仅更新获审来源描述与附件,不覆盖建设单位的督办、上报、责任处理及闭环字段;已受理问题不能因下一版清空卡点就物理删除。读取问题库结果时同样鉴权,失败标不可用,不返回假零。
当前未发现通用问题库服务,需要补接收/关联查询及必要持久化能力作为本任务直接依赖,不能拿工程手续is_key_blocker替代,也不扩建整个进度监管流程。进度承接方的完整表结构按其实际资料/纳管核实后同步到所属模块,不在前期库造第二套督办表。
最小可用接收端除upsert外,还须提供有权问题列表/详情、建设单位维护的督办进展及上报记录和文件引用,使用户能在进度模块实际处理前期来源问题;不能只落一行然后链接到不存在的页面。来源描述、来源附件、unitProjectId及稳定源键由审核接收服务维护;建设单位办理记录、办理附件及督办/上报状态由进度维护接口写入,施工的前期BO不得传入这些字段。仅建设单位有权办理,其他有查询权限角色只读。此处“上报记录”不擅自增加外发渠道、接收单位审批链或进度全模块菜单;具体最小页面/记录契约以实施方案对应章节落实。
6.3 GIS采集、复核、发布和显隐
既有GET /gis/features/list、GET/PUT /gis/features/{featureId}只支持查询和属性/绑定,几何编辑未开放;本次必须新增受控点/面写入口及候选预览、审后发布能力。不能把尚未存在的通用POST接口当已可调用。复用GIS已有地图组件/坐标和图层数据结构,不另起地图引擎。
坐标契约确定为:施工地图采集和候选WKT使用EPSG:3857,crsCode请求/保存码为EPSG_3857;发布服务转换为正式GeoJSON的EPSG:4326,经纬度bbox与正式GeoJSON一致。既有useGisVectorLayers以dataProjection=EPSG:4326、featureProjection=EPSG:3857读取,保持一次转换。不能把米坐标直接写进既有GEOMETRY_JSON后当经纬度读取,不能重复套高德偏移。候选预览明确以3857读取WKT,正式成果以4326读取GeoJSON,不混用两个读取器。征地Polygon,其余Point;服务端校验几何合法、类型、真实单位工程上下文与源目标权限。新点面在审核页可预览但不进正式公共图层。
审后由窄端口发布或更新GIS要素,扩展PRELIMINARY_OBJECT目标鉴权、名称解析及按对象反查。存GIS featureId及既有expectedRevision映射,保留PROJECT/SITE/BID绑定;bindings=null保留、空数组解除全部的旧语义不能误用。发布结果与当前正式修订关联,原空间版可追溯;退回不能改旧图。
每次批准先按spatialKey比较基线与候选的规范几何及图层归属。只有新增或真实修改的空间项发布;仅改计划、面积、手续、植物或卡点而空间未变化时,沿用旧正式要素,不重复新建点面、不增加无意义GIS修订、不重复绑定。EXISTING_FEATURE_ID和EXPECTED_REVISION是本轮有效基线,PUBLISHED_FEATURE_ID是成功结果元数据;不能从上一轮初始候选的null ID认定每次都是新增。
图层控制复用scene/index.vue及useGisVectorLayers.setVisible,按四类业务及真实工程上下文组织。显隐不写审批状态,不替代后端权限;不能把CAD文件来源字段硬造给前期人工点面。现GIS若强依赖图纸/版本,新增业务来源应明确资源归属及读取适配,不伪造图纸或破坏CAD现有读取、修订和场景过滤。
GIS业务来源分支与读取清单
正式来源使用SOURCE_TYPE=PRELIMINARY,前期业务绑定类型仍为PRELIMINARY_OBJECT,两者不是同一个枚举。业务图层补明确来源分类,按真实标段×工点组合和业务类别组织,界面合并为征地/管线/交通/绿化四个逻辑显隐组;不在一个共享图层混入不同pair而只靠前端隐藏。人工业务来源允许drawingId/drawingVersionId为空,实际约束须MCP核实并维护GIS数据库矩阵,不能填伪图纸ID绕过约束。
| 位置 | PRELIMINARY分支必须实现 | CAD分支必须保留 |
|---|---|---|
| 图层/场景目录、数量、bbox | 取已发布业务图层及业务要素,按前期真实unit/pair和业务查询权过滤,不要求图纸和AMAP_V2 | 现图纸、当前图纸版本、配准状态及工点共享授权 |
| 要素分页/详情/导出 | 不与GIS_DRAWING强制内连接;从稳定要素/修订/业务图层读取,业务归属再次核实 | GisFeatureLedgerMapper既有图纸当前版过滤 |
| 地图图层读取和定位 | 业务图层直接返回已审4326 GeoJSON和正确bbox;不调用不存在图纸的drawing/features | 原图纸/图层读取和缓存/版本语义 |
| 新建/更新发布 | 窄服务写GIS要素及不可变修订、绑定,业务来源不锁空drawingId,不写伪CAD版本映射 | 原图纸锁、CAD要素版本映射及修订保护 |
| 属性/几何/绑定入口 | 前期已审要素的业务修改只由审核发布服务应用;通用GIS编辑接口必须拒绝绕过业务审核的写入 | PROJECT/SITE/BID与非前期CAD维护现有行为 |
| 反查/名称/权限 | 按前期对象精确反查,读、计数、导出、地图、绑定源目标都校验真实unit对应pair | 不把CAD工点共享策略全局改为pair |
已核实GisFeatureLedgerMapper.xml.scopeFilter对CAD按线路+工点投影授权,不使用bid;不能直接套给前期专属数据。同工点A标段用户访问B标段前期点面应拒绝,而其原来有权共享的CAD图层仍可读。这是必要权限回归,不新增专业独立授权。实际GIS_FEATURE、GIS_LAYER、GIS_FEATURE_REVISION及读取关联的字段差异在所属GIS资料完整记录,本十四表矩阵不冒充这些既有表已经改造。
7. 编码前核实与交付回填
单位工程及施工/监理组织配置、角色资格、当前数据库实际对象、引擎事务及GIS/进度接入需要实际核查。已确认业务不再等待D01–D09批准;首次前后端代码实施仍需用户“开始实施”。本轮只写文档,无数据库、服务或发布操作。
按测试与验收执行适用用例,重点是逐关、待审隔离、监理卡点白名单、多份期限、重复确认及空间审后发布,补充真实代码与环境证据。若实际模型调整,同步十四表字段矩阵和操作手册,不留旧的累计补齐/卡点只读/线状管线或仅阶段目标DTO分支。