Files
shanxia2.0/docs/superpowers/specs/2026-10-30-pl-cert-entry-modes-design.md
T

47 lines
5.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 购买证、运输证两种建档方式补充设计
日期: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设计及开发文档目前未在工作区找到,本文件只补充本次变化,不冒充原完整方案。
## 交互与保存
1. 手工录入:直接打开购买证或运输证表单,填写已有9组证面字段及子字段,数量、单位分别填写;附件可空。缺图片原因可写现有备注,不强制增加审批或说明字段。
2. 图片解析:用户上传图片,解析现有证面字段,回填同一表单;用户核对、修改、明确保存后才建档。识别失败可改手工录入,不能阻断保存正确的手填内容。
3. 解析只返回候选字段,不直接创建有效档案、绑定合同、占用额度或核销。未识别字段留空,不猜测单位、数量、有效次数或证号;沿用字段校验,不以0或“未知”替代必填值。
4. 上传和解析支持多个车号、多个购买许可/备案/出口许可证号;保留所有用户确认的子字段,仍不做数量单位自动换算。
5. 后续补图直接编辑原档案;图片解析结果以待确认建议显示,不自动覆盖已填写信息。保持档案ID、合同关系、适用产品明细ID及历史用量不变,不重新生成余额。首次建档方式不因补图而改变。
6. 同租户、同证种、同证号仍唯一;两种入口都不得重复创建同一证的第二份额度。重复号码提示定位已有记录,不自动覆盖;访问已有记录仍需数据权限。
7. 表单核心校验保持一致:证号、物品名称、核定数量、单位等按当前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和已用/预占额度不变;无确认不覆盖原内容。
- 两种入口输入同一证号:不会生成第二份档案额度;跨租户、无权限文件与档案不可读取或更新。
- 用证一致性:同等完整信息的两种来源记录适用相同用证校验、手动单位折算、逐证占用和归档规则。