主题
工程质量管理 · 详细设计文档
文档版本：1.00 ｜ 最近核对日期：2026-11-10
1. 契约性质与分层
本文是依据20261104定稿资料重新制定的目标契约，旧质量代码、旧接口、旧流程均不作为依据。不声称下列接口已经存在或已可调用。业务规则和待决编号引用需求分析，数据落地见数据库设计；D01等仅暂停其依赖功能。
后端按Controller→Service→Mapper/Entity实现；输入BO、输出VO，分类专有内容用明确DTO。前端API与types放src/api/business/quality/，页面放src/views/business/quality/；目录只是新实现组织建议，不要求照旧代码拆分。复用平台R、PageQuery/PageResult、统一异常、日志、文件与流程SPI。
所有ID逻辑类型为Id=string | number，后端Long、输出BigNumberSerializer；不做Number/parseInt转换。日期型使用YYYY-MM-DD，时间点用带时区ISO8601，界面按平台时区展示；后端按业务日期或时间戳区别存储，不让Excel日期文本代替日期字段。数值和字典值外部输入须运行时校验。
2. 页面和路由
下表为拟定目标路由，台账由菜单配置、办理页由固定路由注册。显示名称不能用通用“办理”代替“业务名称+办理”。
| 菜单/页面 | 路由 | 主要行为 |
|---|---|---|
| 首件验收 | /quality/acceptance/firstItem | 查询、草稿、申请、两阶段材料、详情 |
| 分部工程验收 | /quality/acceptance/subProject | 单位/分部选择、五项结论、同意开会及正式成果 |
| 单位（子单位）工程验收 | /quality/acceptance/unitProject | 预验收、整改、正式申请、会签、最终纪要 |
| 项目工程验收 | /quality/acceptance/projectAcceptance | 五类成果；D01决定是否有审核 |
| 专项验收 | /quality/acceptance/specialAcceptance | 分类成果、适用计划/前置文件、统计；不新增顶层菜单 |
| 竣工验收 | /quality/acceptance/completionAcceptance | 五类成果归档 |
| 质量消缺 | /quality/acceptance/defect | 五分类，批次任务/问题总台账，导入、批次详情和逐问题办理 |
| 验收目录配置 | /quality/acceptance/catalog | 两级引用、分部排序备注、导出 |
| 不合格台账 | /quality/testing/ncLedger | 报告及补充项登记、总监审核 |
| 不合格处置 | /quality/testing/ncDisposal | 选来源报告、回复明细及审核 |
| 质量问题 | /quality/inspection/problem | 日常问题单独登记、导入、逐问题流程 |
| 质量事故 | /quality/inspection/accident | 类型/等级筛选、登记、报告与处置、接收 |
| 记录办理/查看 | 对应记录台账后接/flowForm | 根据recordId与类型加载同一业务表单，当前任务开放节点字段 |
| 消缺问题办理/查看 | /quality/acceptance/defect/issue/flowForm | 必须传issueId，不以batchId代替实际待办业务ID |
列表筛选类型固定来自路由配置，不能让客户端businessType决定可访问所有业务。消缺任务视图显示批次名称、分类、填报信息、总问题/闭环数、当前概况；问题视图显示真实问题工程、等级、主责、进度、流程状态。批次详情可逐条进入办理，批次不出现误导性的“整批审批通过”。
草稿有继续编辑/删除/提交，办理只对当前任务显示；有查询权限可只读详情。长表固定左侧识别列、右侧状态和操作列；表单分区及弹窗按UI规范。通用选人、概况、操作、时间线、文件预览均复用平台组件；界面正文不出现实现流程、框架名称或内部待办。
3. 字段与节点编辑契约
3.1 共用字段
| 字段组 | 逻辑字段 | 生成/可编辑规则 |
|---|---|---|
| 身份 | id、businessType、businessNo、title | ID/编号由服务端生成，businessType创建后不可切换，标题经办录入 |
| 工程 | lineId、bidId、siteId、unitProjectId、subProjectId | 各业务适用维度按需求R02，单位反取组合，分部校验父级，不接收任意名称冒充引用 |
| 快照 | lineName、bidName、siteName、unitProjectName、subProjectName | 服务端从主数据生成，历史展示使用保存快照 |
| 填报 | reportOrgId、reporterId、reportTime | 默认当前组织/本人/服务端时间，授权补录另按实际需求，不信任客户端审计字段 |
| 流程 | instanceId、flowCode、flowVersion、flowStatus、currentTasks | 后端由引擎维护，客户端不可写；当前任务从引擎实时读取 |
| 专有资料 | typed payload | 按businessType解析，未知字段或越节点字段拒绝，不允许任意Map覆盖 |
| 文件 | attachment references | 只传OSS文件ID及业务用途，名称/大小/类型由服务端核验 |
草稿仅要求可识别业务类型/归属和必要标题；提交及节点办理按下表最小业务信息校验。尚未确定的材料必填用D12显式约束，不能开发者自行把所有字段设成必填。
3.2 验收资料
| 类型 | 业务字段 | 节点责任与阶段 |
|---|---|---|
| 首件 | 工程部位及名称、施工执行依据、施工情况；预验收申请；自检结论、正式验收记录表/纪要 | 施工初始填写前三项及预申请；正式成果节点填写自检/记录/纪要；其他节点只写本次意见 |
| 分部 | 工程设计与合同完成、质量控制资料具备、安全功能检验结果、观感结果、自检结论；预申请及正式成果 | 施工填五项与申请；负责人同意开会节点不修改申请；获准后施工上传正式记录/纪要 |
| 单位 | 合同完成、分部验收、资料核查、安全主要功能核查/抽查、观感、缓建缓验、自检；预申请、预问题清单、预纪要、预结论、正式申请、正式结论、正式纪要 | 项目经理填申请资料；总监组织预验收上传清单/纪要；负责人审批开会；施工补整改正式申请；总监签预验收意见；经办发会签；组长最终确认上传正式纪要 |
| 项目 | 情况说明、方案、缓建缓验批复、验收意见、纪要、监督意见 | 经办维护，审核与否按D01；不适用批复须说明而非上传空白假文件 |
| 专项 | specialtyCode、适用计划ID、情况说明、成果、完成依据日期、前置业务文件 | 经办归档，计划维护人维护适用性及前置资料；是否完成由D09确定的证据规则推导 |
| 竣工 | 情况说明、方案、甩项批复、验收意见、纪要、监督意见 | 经办归档，无流程 |
单位工程原型支持通用文档，首件/分部明确PDF，不统一成全部仅PDF；材料在D12确认后分节点校验，不能申请阶段要求上传尚未形成的会议纪要。
3.3 五类消缺问题字段
批次字段为名称、分类、填报组织/人员/时间、说明、来源批次标识；每条问题必须有稳定ID、问题序号、所属批次、各自工程范围、问题内容、责任链及业务结果。分类不能在进入流程后改成另一类别。
| 分类 | 原始问题字段（S02/S03） | 回复/确认字段 |
|---|---|---|
| 施工阶段 | 线路/标段/工点或系统、施工及监理单位与联系人、存在问题、问题附件、建设单位整改责任人、备注 | 计划完成日期与实际完成日期分开；整改完成情况/说明、成果附件、监理复核及现场确认 |
| 运营提前介入/初期运营后 | 提出部门、专业、段线、车站或区间、事项内容、影响等级、发现日期、运营现场联系人、问题附件、初运前应完成标识、建设责任分公司、业主及施工责任人 | 是否提出异议、原/建议/确认等级、降级说明、运营确认、轨行区标识、作业点数/预计天数（拆分为两个字段仅建议，D02确认后落定）、是否影响行车、是否涉及轨行区作业、计划/实际完成日期、完成说明、整改附件、监理销项意见、运营闭环 |
| 消防 | 问题来源三方/四方、类别（水/风电/车控室/建筑防火等）、工点、问题描述、照片、不符合条文、归口公司、存在问题分类、责任标段、整改专业/单位、攻坚责任人、监理/施工/第三方检测联系人 | 是否需设计核实、设计回复/附件、计划完成日期、整改说明、回复照片/成果；复验/销项证据D10确定后加入节点规则 |
| 初期运营评估 | 文档/意见页码、专家、板块、可空点位、问题类型、问题描述、处理措施、问题附件、运营责任单位/部门/负责人、交建责任单位、相关参建单位及责任人 | 运营/交建计划日期分别保存、佐证资料/受控链接、专业分解、任务分解、任务细化、类别、开展方式、责任人、开展状态、已整改标识、进度、成果列表、初复终审意见 |
重复“备注”按业务区分为提出方备注/整改方备注，不映射到同一字段互相覆盖。历史“计划作业点数（天）”存在数量与单位混用，推荐点数、预计天数分开；业务提供一份有效样例确认含义（D02）。历史单一“整改完成时间”不得同时代表计划与实际。
问题照片/附件原则选填；最终销项必须的证据由D12补齐。评估成果1—4用有序成果列表表示，不硬编码最多4条，也不丢失多项成果名称及文件关系。专家名等资料属业务内容，不在公开设计文档填真实姓名电话。
3.4 检测、日常问题、事故
| 类型 | 字段 | 责任 |
|---|---|---|
| 不合格报告 | reportNo、sampleName、commissionDate、testDate、responsibleOrgId、reportAttachments、supplements[{content,files,remark}]、检测结论 | 项目经理登记，总监审核；检测结论固定为此台账语义的不合格，与flowStatus分离 |
| 处置 | sourceRecordId、title、replyItems[{description,files,remark}]、处置结果 | 来源只读，项目经理回复、总监复核、现场代表确认；跨类型/跨工程来源拒绝 |
| 日常问题 | 工程、问题描述/部位、发现日期、问题资料、责任岗位、整改说明/完成日期/成果 | 施工总工程师登记整改，总监→现场代表→项目负责人；不复制五类消缺页签 |
| 事故 | occurrenceYear/month、incidentType、incidentLevel、情况说明、事故报告、处置销项文件、主管组织 | 项目经理登记，总监→主管经办闭环→主管负责人接收；月份1—12，类型和等级用明确字典，不以示例值认定业务等级 |
3.5 节点字段策略
每个流程定义的nodeCode与服务端字段白名单、必填矩阵一一对应。客户端不能提交flowStatus、办理人历史、上阶段结论等只读字段。业务资料保存接口和审批动作通过同一服务端编排完成；不能要求先随意PUT全单据再调用通用通过接口。
正式会签与共同确认由引擎协作类型实现，不以多个普通下一办理人混成或签；岗位资格按每个目标节点校验。未知节点、资料schema不匹配、引擎实例与业务ID不一致时拒绝推进并保留已填写内容。
4. 目标API
前缀/business/quality。下列为本版新契约；实现可按平台路由样式微调，但必须同时更新客户端、菜单和文档，不兼容旧质量API。
| 方法/路径 | 输入与输出 | 权限资源与责任 |
|---|---|---|
GET /records/list | type+工程/日期/状态+PageQuery → PageResult<RecordVO> | 按type映射业务资源list，不能任意切换绕权 |
GET /records/{id} | type → R<RecordDetailVO> | 对应query，类型匹配与工程校验 |
POST/PUT /records | RecordDraftBO → R<Id>/R<Void> | 对应add/edit，仅草稿及允许补正范围 |
DELETE /records/{ids} | type → R<Void> | 对应remove，逐条校验状态/类型/范围 |
POST /records/{id}/submit | SubmitBO → R<ProcessRefVO> | 对应submit，校验已保存草稿并启动流程；无流程类型不调用 |
POST /records/export | 与list同筛选 → 文件流 | 对应export，范围一致 |
GET /defect-batches/list、/{id} | category/筛选 → PageResult/详情含问题汇总 | defectBatch:list/query，汇总仅有权问题，不能泄漏未授权问题内容 |
POST/PUT /defect-batches | BatchDraftBO含新增问题草稿 → R<BatchSaveVO> | defectBatch:add/edit，批次归集不是审批 |
GET /defect-issues/list、/{id} | 批次/类别/工程/业务状态/流程状态 → 分页/详情 | defectIssue:list/query，每条工程授权 |
POST/PUT /defect-issues | IssueDraftBO → R<Id>/R<Void> | defectIssue:add/edit，禁止修改其他在途问题 |
DELETE /defect-issues/{ids} | IDs → R<Void> | defectIssue:remove，仅允许删除草稿；批次有在途问题时不能级联删 |
POST /defect-issues/{id}/submit | SubmitBO → R<ProcessRefVO> | defectIssue:submit，每问题一个实例 |
POST /defect-issues/batch-submit | issueIds+逐问题节点人员 → R<SubmitResult[]> | defectIssue:submit，逐条事务，结果逐条成功/失败，不假称整批原子 |
POST /defect-batches/export、/defect-issues/export | 各自当前筛选 → 文件流 | 对应export，视图粒度不同 |
POST /imports/template | category/businessType → 文件流 | 对应import，下载分类标准模板 |
POST /imports/preview | file+businessType+适用category+selectedSheets+范围 → R<ImportPreviewVO> | 对应import，预检无业务写入，不存真实通讯录到公开日志 |
POST /imports/confirm | previewToken+确认映射+适用批次信息 → R<ImportConfirmVO> | 对应import，重新核对文件摘要/操作者/范围与问题归属，整批草稿事务 |
GET /workflow/handler-options | businessKind、businessId、目标节点 → R<HandlerOptionVO[]> | 对应submit或办理操作权限+资格，候选岗位由服务端解析 |
POST /workflow/tasks/{taskId}/complete | NodeCompleteBO → R<ProcessRefVO> | 对应业务submit动作能力+引擎当前任务权限，后端检查节点字段及责任 |
POST /workflow/tasks/{taskId}/return | targetNodeCode、reason → R<Void> | 同上，平台允许的退回目标，意见必填 |
GET /workflow/{businessKind}/{id}/process | → R<ProcessDetailVO> | query+业务范围，引擎历史与业务主体一致 |
GET /responsibilities/list、POST/PUT /responsibilities | 工程范围/岗位任职 → 分页/保存结果 | responsibility:list/add/edit，管理员或责任配置授权人 |
GET /special-plans/list、POST/PUT /special-plans | 线路/专项项适用计划 → 分页/保存结果 | specialPlan:list/add/edit，计划维护资格 |
GET /special-plans/statistics | lineId → R<SpecialStatisticsVO> | specialPlan:query，整线资源，按确认口径去重 |
GET /catalog-config/list、PUT /catalog-config | 单位/分部引用、排序备注 → R | catalog:list/edit，不创建工程对象 |
普通分页直接PageResult，详情/写入为R；不把分页再包两层。枚举、固定字段名称与每个type的资源映射在共享契约中维护。
提交前先保存草稿并等待保存成功；submit只接收流转人员，不接受隐藏的业务字段修改。提交失败保留已保存草稿，返回明确失败原因，不显示已进入流程。单问题提交事务负责实例关联与状态一致。
4.1 示例结构
ts
type Id = string | number;
type EngineeringRef = {
lineId: Id;
bidId?: Id;
siteId?: Id;
unitProjectId?: Id;
subProjectId?: Id;
};
type SubmitBO = {
// 服务端解析业务类型、下一节点和岗位资格
nextHandlers: Array<{ nodeCode: string; userIds: Id[] }>;
};
type NodeCompleteBO = {
businessKind: 'record' | 'defectIssue';
businessId: Id;
opinion: string;
nodeData: QualityNodeData;
nextHandlers: Array<{ nodeCode: string; userIds: Id[] }>;
};QualityNodeData必须按实际节点定义联合类型，不使用any或任意JSON替代。无下一节点时nextHandlers为空，不强制选人；协作岗位按服务端目标节点配置校验，不接受客户端提供一个不存在节点注入任意办理人。
4.2 权限矩阵
记录type资源固定为firstItem/subProject/unitProject/projectAcceptance/specialAcceptance/completionAcceptance/ncLedger/ncDisposal/problem/accident，权限采用quality:<resource>:list/query/add/edit/remove/export/import/submit中适用项；消缺、责任配置、计划、目录使用上表资源名。节点办理复用submit操作权限与平台当前任务校验，不凭文档新增未登记handle动词。前端v-hasPermi、后端SaCheckPermission及SYS_MENU.PERMS逐字一致。无流程资料不配置submit；无导入需求的页面不补import按钮。
资源角色范围不是仅createBy或所属部门过滤。跨工程批次的头部名称等公共信息也应避免无关信息泄漏；批次只展示有权问题汇总并明确“当前可见”数量。办理人和知会人缺基础工程权限时拒绝配置并报缺项，不用抄送记录绕过工程权限。
5. 导入导出与专项集成
5.1 标准模板与历史文件
导入businessType区分消缺和日常质量问题；category仅消缺适用，其他类型传入则拒绝。ImportConfirmVO为区分联合：消缺返回{businessType: defectIssue, batchId, issueIds, count}，日常问题返回{businessType: problem, recordIds, count}。日常问题导入生成独立草稿记录，不生成消缺批次或分类。
分类模板具有明确列键及schema版本，包含每问题工程归属、问题内容和分类适用字段；显示列名不能靠位置猜测。预览含工作表、原行、规范值、工程候选和错误列表；存在多候选需用户在导入界面选择真实对象，不能自动取第一个。确认令牌沿平台受控临时文件机制，过期可重新预检，不额外建设通用导入平台。
历史一期/二期、消防汇总/副本/保留图像表与实际Sheet由D07清单决定。合并单元格仅按明确表头及业务归属继承，不能全表向下填充；公式缓存不可靠时标预检错误，不执行外部链接/宏。照片迁移若纳入需将嵌入图片、DISPIMG与问题行建立可复核映射；否则只导结构字段并明确待补照片，不能把公式文本当文件。
导出使用当前视图及服务端完整筛选，不只导当前页；业务日期/等级/人员用可读值，保留原始问题号与工程身份以利核查。敏感电话仅向授权业务用户导出，公开文档不附原通讯录。
5.2 专项适用性与统计
每线路每专项适用计划项一条，支持适用/不适用、计划日期、前置业务文件、完成证据。推荐完成数=截至统计时点满足完成证据的适用计划项去重数，总数=适用计划项数；分母0时完成率显示“不适用/暂无适用项”，不显示100%。重复成果不重复计数，更新/撤销完成依据须重算。本版默认统计当前有效适用清单及成果，generatedAt为服务端生成时间，不承诺历史版本回溯统计。具体完成证据和不适用审批由D09确认，不擅设新审批流程。
统计VO拟含lineId、generatedAt、applicableCount、completedCount、pendingCount、completionRate、items；数据来源是业务计划与成果，不保存手填完成率。大屏优先消费经授权只读统计；必须推送时由D09提供目标地址/鉴权/字段/频率/失败处置契约后接入，不在业务代码写死地址或密钥。
6. 事务、异常与验证
| 边界 | 失败要求 |
|---|---|
| 草稿批次及问题确认导入 | 任一写入或归属校验失败全部回滚，不残留半批问题 |
| 单问题/记录提交 | 业务资料、实例绑定和状态按平台实际事务能力一致；失败不显示已提交，允许明确补正 |
| 节点完成 | 当前人/任务/业务/节点匹配且字段有效才推进；禁止先推进再保存必交成果 |
| 通知 | 业务提交成功后非阻塞发送；失败沿平台可见提示/补发能力处理，不回滚业务、不创建伪审批 |
| 附件 | 校验真实元数据及业务关联，文件预览下载与单据权限一致；失效文件提示补传，不静默丢附件 |
| 导出/统计 | 服务端权限与筛选统一；未裁决口径不返回伪统计 |
接口使用平台统一错误返回和可理解中文提示。重点错误包括工程关系不匹配、没有数据范围、岗位缺员、办理人失效、节点不允许修改、材料缺失、模板缺列、来源报告非法。不要吞异常或在各层重复校验同一可信结果；不因理论并发默认加锁、版本、幂等框架和压力专项。
验收覆盖需求AC01—AC12和测试用例：节点顺序、逐问题隔离、同工点多标段、空候选、越节点写入、附件实际归属、错误导入整批回滚、专项去重/零分母。实施后须通过纳管入口核对实体实际列及真实读写；涉及新流程按项目规则核实发布版本、在途实例及双环境，不能仅验证JSON文件存在。本轮未执行上述运行检查。