5.1 KiB
5.1 KiB
购买证、运输证两种建档方式补充设计
日期：2026-10-30。状态：设计草案，未实现功能、未执行数据库迁移。
完整方案与后续实施清单现位于 openspec/changes/pl-contract-cert-quota-control/。本文保留建档方式补充记录；跨证自动预占、归档及取消证书齐备以完整方案为准。
需求与范围
购买证和运输证均支持手工录入、图片解析后确认两种建档方式。按用户举例，本次“没有证”指原件图片缺失，但可人工填写证件信息。图片不再是建档必填项，也不单独决定证件能否选用；本补充不新增无证号、无额度直接放行运输的规则。
现有SQL：docs/sql/designs/2026-10-25-purchase-transport-cert-draft.sql。先前2026-10-26设计及开发文档目前未在工作区找到，本文件只补充本次变化，不冒充原完整方案。
交互与保存
- 手工录入：直接打开购买证或运输证表单，填写已有9组证面字段及子字段，数量、单位分别填写；附件可空。缺图片原因可写现有备注，不强制增加审批或说明字段。
- 图片解析：用户上传图片，解析现有证面字段，回填同一表单；用户核对、修改、明确保存后才建档。识别失败可改手工录入，不能阻断保存正确的手填内容。
- 解析只返回候选字段，不直接创建有效档案、绑定合同、占用额度或核销。未识别字段留空，不猜测单位、数量、有效次数或证号；沿用字段校验，不以0或“未知”替代必填值。
- 上传和解析支持多个车号、多个购买许可/备案/出口许可证号；保留所有用户确认的子字段，仍不做数量单位自动换算。
- 后续补图直接编辑原档案；图片解析结果以待确认建议显示，不自动覆盖已填写信息。保持档案ID、合同关系、适用产品明细ID及历史用量不变，不重新生成余额。首次建档方式不因补图而改变。
- 同租户、同证种、同证号仍唯一；两种入口都不得重复创建同一证的第二份额度。重复号码提示定位已有记录，不自动覆盖；访问已有记录仍需数据权限。
- 表单核心校验保持一致：证号、物品名称、核定数量、单位等按当前SQL要求填写；已有状态、复核、有效期、有效次数及额度控制按原业务设计执行。无附件本身不阻止手工档案按相同流程使用，图片解析成功也不自动等于复核通过。
SQL调整
两张档案表各增加entry_mode VARCHAR(20) NOT NULL DEFAULT 'manual'，服务层限定manual、image_parse；表示首次建档来源，是系统字段，不增加第10组证面元素。
两表的attachment_urls TEXT改为允许NULL。无附件统一保存NULL，有附件仍按MinIO URL逗号分隔约定保存。仅在图片解析入口检查待解析图片存在；手工创建和后续普通保存不要求附件。图片解析来源由实际解析流程确认，不能仅凭客户端字段认为已验证证件。
不增加独立手工证件表、解析证件表或另一份额度表，现有8张表的合同多对多、分配与核销结构保持不变。
开发步骤及字段影响
- 后端档案读取、创建/编辑schema、前端TypeScript及表单统一增加entryMode和可空attachmentUrls。首次来源创建后只读；解析结果不包含可写的tenant_no、余额、状态、复核人等系统字段。
- 增加购买证、运输证图片解析服务入口，鉴权、当前租户及文件访问权限校验与现有业务一致。实现前检查现有图片解析能力并复用；本设计尚未选择或调用外部识别服务。
- 两个建档入口复用同一表单和保存接口；图片解析显示处理中、成功待确认和失败可手填状态。网络重试不得产生重复档案，证号唯一约束作为最终保障。
- 引用证号、合同绑定、适用产品等子集合按
docs/development/child-data-save-rules.md差量保存。遗漏集合保持不变，显式空集合申请清空但必须通过引用保护；保留子行ID、创建信息及未提交业务字段。主档与子数据在同一事务内保存，解析和补图不能全删全增。 - 实现时遵守当前后端及Web AGENTS和UI规范；graphify已停用，不执行旧计划中的图谱更新步骤。
验收场景
- 无图片、核心字段完整：购买证和运输证都能手工保存；attachmentUrls为空，entryMode为manual。
- 有图片：解析预填全部支持字段，数量和单位分开，多个车号/引用证号不丢失；修改后保存用户确认值，entryMode为image_parse。
- 解析失败或漏识别：提示用户手填，保存时按字段校验；不得伪造识别值或自动启用。
- 补图或重新解析：档案ID、合同关系、子行ID和已用/预占额度不变；无确认不覆盖原内容。
- 两种入口输入同一证号：不会生成第二份档案额度；跨租户、无权限文件与档案不可读取或更新。
- 用证一致性：同等完整信息的两种来源记录适用相同用证校验、手动单位折算、逐证占用和归档规则。