From 0cd120ef5e59fab36fafb479697a6495ad5985c2 Mon Sep 17 00:00:00 2001 From: wuzilong <704541015@qq.com> Date: Sat, 31 Oct 2026 22:34:11 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E8=AF=81=E4=BB=B6?= =?UTF-8?q?=E6=89=8B=E5=B7=A5=E4=B8=8E=E5=9B=BE=E7=89=87=E8=A7=A3=E6=9E=90?= =?UTF-8?q?=E5=BB=BA=E6=A1=A3=E6=96=B9=E6=A1=88=E5=B9=B6=E5=90=8C=E6=AD=A5?= =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E8=8D=89=E6=A1=88=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...26-10-25-purchase-transport-cert-draft.sql | 15 ++++--- .../2026-10-30-pl-cert-entry-modes-design.md | 44 +++++++++++++++++++ 2 files changed, 53 insertions(+), 6 deletions(-) create mode 100644 docs/superpowers/specs/2026-10-30-pl-cert-entry-modes-design.md diff --git a/docs/sql/designs/2026-10-25-purchase-transport-cert-draft.sql b/docs/sql/designs/2026-10-25-purchase-transport-cert-draft.sql index 759aea32f..f82395824 100644 --- a/docs/sql/designs/2026-10-25-purchase-transport-cert-draft.sql +++ b/docs/sql/designs/2026-10-25-purchase-transport-cert-draft.sql @@ -1,10 +1,11 @@ --- 购买证、运输证与用量核算模型（2026-10-26修订设计草案） +-- 购买证、运输证与用量核算模型（2026-10-30修订设计草案） -- 仅供评审，不是上线迁移；本次不执行DDL，不更改既有业务表。 -- 取代本文件2026-10-25版：证面仅保留用户分别确认的9项；删除自动换算系数。 --- 设计：docs/superpowers/specs/2026-10-26-pl-contract-cert-design.md --- 开发方案：docs/superpowers/plans/2026-10-26-pl-contract-cert.md +-- 建档补充设计与开发步骤：docs/superpowers/specs/2026-10-30-pl-cert-entry-modes-design.md +-- 原2026-10-26设计及开发文档当前工作区未找到，此补充不代表完整业务实现。 -- MySQL 5.7.8+ / InnoDB / utf8mb4 / UUID varchar(64) / 公共字段尾置。 --- JSON仅用于车牌列表与业务快照；证面不增加OCR、二维码、印章、核发机关字段。 +-- JSON仅用于车牌列表与业务快照；支持图片解析预填既有证面字段，不增加二维码、印章、核发机关字段。 +-- manual手工录入可无图片；image_parse为图片解析后人工确认建档，两者共用档案及用量规则。 -- 合同关联、附件、状态、余额、复核、修订号属于系统业务字段，不计入证面9项。 -- 本版8表：证件先绑定合同，再选择合同内多个适用产品；证件不绑定单一product_id。 -- 50%硫酸、98%硫酸可以共用证面品名为硫酸的证；需人工勾选适用合同产品行。 @@ -31,7 +32,8 @@ CREATE TABLE `pl_purchase_cert` ( `valid_from` date DEFAULT NULL COMMENT '有效期起始日期', `valid_to` date DEFAULT NULL COMMENT '有效期截止日期', `valid_use_text` varchar(32) NOT NULL COMMENT '有效次数：一次有效或多次有效；不增加数值次数表单', - `attachment_urls` text NOT NULL COMMENT 'MinIO原件附件地址，多附件逗号分隔', + `entry_mode` varchar(20) NOT NULL DEFAULT 'manual' COMMENT '首次建档方式：manual手工录入/image_parse图片解析后确认；补图不改变来源', + `attachment_urls` text COMMENT 'MinIO原件附件地址，可空，多附件逗号分隔；无图片也可手工建档', `status` varchar(20) NOT NULL DEFAULT 'draft' COMMENT 'draft草稿/active可用/suspended停用/void作废；到期由日期判断', `verified_by` varchar(64) DEFAULT NULL COMMENT '证件信息复核人', `verified_time` datetime DEFAULT NULL COMMENT '证件信息复核时间', @@ -71,7 +73,8 @@ CREATE TABLE `pl_transport_cert` ( `valid_from` date DEFAULT NULL COMMENT '有效期起始日期', `valid_to` date DEFAULT NULL COMMENT '有效期截止日期', `valid_use_text` varchar(32) NOT NULL COMMENT '有效次数：一次有效或多次有效；不增加数值次数表单', - `attachment_urls` text NOT NULL COMMENT 'MinIO原件附件地址，多附件逗号分隔', + `entry_mode` varchar(20) NOT NULL DEFAULT 'manual' COMMENT '首次建档方式：manual手工录入/image_parse图片解析后确认；补图不改变来源', + `attachment_urls` text COMMENT 'MinIO原件附件地址，可空，多附件逗号分隔；无图片也可手工建档', `status` varchar(20) NOT NULL DEFAULT 'draft' COMMENT 'draft草稿/active可用/suspended停用/void作废；到期由日期判断', `verified_by` varchar(64) DEFAULT NULL COMMENT '证件信息复核人', `verified_time` datetime DEFAULT NULL COMMENT '证件信息复核时间', diff --git a/docs/superpowers/specs/2026-10-30-pl-cert-entry-modes-design.md b/docs/superpowers/specs/2026-10-30-pl-cert-entry-modes-design.md new file mode 100644 index 000000000..241a72883 --- /dev/null +++ b/docs/superpowers/specs/2026-10-30-pl-cert-entry-modes-design.md @@ -0,0 +1,44 @@ +# 购买证、运输证两种建档方式补充设计 + +日期：2026-10-30。状态：设计草案，未实现功能、未执行数据库迁移。 + +## 需求与范围 + +购买证和运输证均支持手工录入、图片解析后确认两种建档方式。按用户举例，本次“没有证”指原件图片缺失，但可人工填写证件信息。图片不再是建档必填项，也不单独决定证件能否选用；本补充不新增无证号、无额度直接放行运输的规则。 + +现有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和已用/预占额度不变；无确认不覆盖原内容。 +- 两种入口输入同一证号：不会生成第二份档案额度；跨租户、无权限文件与档案不可读取或更新。 +- 用证一致性：同等完整信息的两种来源记录适用相同用证校验、手动单位折算、逐证占用和归档规则。