主题
工程进度监管 · 详细设计文档
文档版本：0.10 ｜ 最近核对日期：2026-11-10
本文展开前期管理来源卡点的必要接收和建设单位维护增量，包含前期来源卡点同步接收（ProgressDifficultySourceService）、建设单位管理维护及登记上报接口与前端页面（difficultyLedger/index.vue），已完整实现并通过定向单元测试（ProgressDifficultySourceServiceTest）。业务规则见需求分析第9节。
1. 范围及入口
复用既有规划的/progress/deviation/difficultyLedger问题库入口，前端目标文件digital-construction-ui/src/views/business/progress/difficultyLedger/index.vue，在同页按来源筛选并打开问题详情。若未来已有实现则增量接入，不创建第二个“前期问题库”。本次先保证前期来源的列表、详情、来源附件、督办记录、上报内容及附件维护可真实保存回读，不同时建设网络计划、全套年度上报审批或独立督办台账。
用户确认了办理责任，没有给上报接收人或外部发送/审批链。本增量中的上报动作准确命名“登记上报内容”，保存内容及材料留档，不宣称已发送上级或审批完成；后续启用既有年度上报审批时引用同一问题，不复制来源。不能用空链接、只有sourceIssueId或前期发送日志代替本页。
2. 数据所有权
| 数据组 | 来源及可写方 | 限制 |
|---|---|---|
| sourceType/objectId/issueKey/unitProjectId、获审描述、来源附件、获审版本 | 前期已审同步服务 | 建设单位不在此改写施工原报；源修订不改管理记录 |
| 是否督办、责任单位、完成时限 | 具本模块维护权限和工程范围的建设单位 | 施工不能借前期接口写入，首次接收不编造责任人或时限 |
| 督办进展记录、上报内容及材料 | 建设单位 | 追加记录，不覆盖其他来源或历史办理 |
| 处理状态、已办结历史 | 沿进度问题库实际业务 | 前期清空或改描述不能删除历史或重新打开已办结问题 |
字段关系见数据库设计。同sourceType+objectId+issueKey定位同一问题；首次生成ID和来源信息，后续只更新获审描述、附件、版本与审核人时，管理字段及记录不动。原来源已不存在时显示来源撤下/待核对，不自动删除进度办理。
3. 接口及身份
后端目标包com.bokun.business.progress.difficulty，使用现有business模块，同应用窄Java服务调用，不自调HTTP；共享事务参与前期审批，异常上抛。建议接口ProgressDifficultySourceService.acceptApprovedPreliminary与querySourceResult，不是任意客户端可调用的免审核写入口。
| HTTP目标 | 入参/输出 | 权限与边界 |
|---|---|---|
| GET /business/progress/difficulty/list | 来源、unitProjectId、页码→分页 | progress:difficultyLedger:list，来源真实工程范围 |
| GET /business/progress/difficulty/ | 来源信息、管理信息、记录、可访问附件 | progress:difficultyLedger:query，同源pair及业务查询权 |
| PUT /business/progress/difficulty/{id}/management | supervised、responsibleOrgId、dueDate | progress:difficultyLedger:edit，建设单位角色/组织资格＋范围 |
| POST /business/progress/difficulty/{id}/records | kind=SUPERVISION或REPORT、content、attachmentFileIds | progress:difficultyLedger:edit，建设单位＋范围，追加保存 |
不创造未登记supervise/report权限动词。组织资格沿平台真实角色/单位关系核验，不让施工只凭工程可见就拥有建设单位维护权。前期来源按其unitProjectId反取pair授权，不能继承其他全量可见问题域的宽松策略；其他来源保留已有规则。
文件引用仍验证当前用户对所属问题和文件的访问，源文件与办理附件区分，预览下载不能绕对象权限。
4. 成功和失败出口
接收前核对前期对象、审批版本及稳定issueKey，不能仅凭调用入参的reviewed=true。默认同纳管数据源同步事务、REQUIRED语义，不REQUIRES_NEW、不异步、不吞异常。审批监听中任何必要接收失败使本次审核整体失败；旧问题和管理记录不得被失败回滚清理。实际数据源或引擎行为不支持时先取得证据，再调整具体接入，不默认建设外部消息平台。
验证：前期首次通过→问题库真实新问题；建设单位保存督办和一条上报记录；前期改描述再审核→仍同问题ID且两条办理内容不丢；施工直接调用管理接口被拒绝；接收失败时审批不假通过。对应前期测试T33/T34/T39/T47。本轮均未执行。