feat(pl): 购买证运输证改为客户品类额度并支持齐备完善。

按客户与证用品类自动选证,未配置生效时间拦住安排;齐备仅放行安排,归档前须完善挂证,并补充迁移与测试造数脚本。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
wuzilongandCursor committed 2026-11-14 23:31:01 +08:00
1 parent aad74505c0
commit cd94ebc56d
31 files changed
+2835 -39

No files matched your search

@@ -0,0 +1,112 @@
-- 客户+品类证件额度:证用品类、规则切点、证件/计划扩展字段。
-- MySQL 5.7。可重复执行。
-- 回滚思路(勿自动执行):停用新规则配置;新表可 DROP;新增列可 ALTER DROP(上线后有数据时先备份)。
SET NAMES utf8mb4;
SET @schema_name = DATABASE();
-- ---------- 证用品类 ----------
CREATE TABLE IF NOT EXISTS `pl_cert_category` (
`id` varchar(64) NOT NULL COMMENT '主键UUID',
`category_name` varchar(128) NOT NULL COMMENT '证用品类名称,如硫酸',
`category_code` varchar(64) DEFAULT NULL COMMENT '品类编码,可选',
`status` char(1) NOT NULL DEFAULT '1' COMMENT '状态 1启用 0停用',
`tenant_no` varchar(64) NOT NULL COMMENT '租户编号',
`order_num` int DEFAULT NULL COMMENT '排序号',
`remark` varchar(1000) DEFAULT NULL COMMENT '备注',
`create_by` varchar(64) DEFAULT NULL COMMENT '创建人',
`create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建部门',
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`update_by` varchar(64) DEFAULT NULL COMMENT '更新人',
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
`del_flag` smallint NOT NULL DEFAULT 0 COMMENT '软删除 0正常 1删除',
PRIMARY KEY (`id`),
KEY `idx_cert_category_tenant` (`tenant_no`, `del_flag`, `status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 ROW_FORMAT=DYNAMIC COMMENT='证用品类';
CREATE TABLE IF NOT EXISTS `pl_cert_category_product` (
`id` varchar(64) NOT NULL COMMENT '主键UUID',
`category_id` varchar(64) NOT NULL COMMENT '证用品类ID',
`product_id` varchar(64) NOT NULL COMMENT 'CRM产品ID',
`scope_status` varchar(20) NOT NULL DEFAULT 'active' COMMENT 'active/inactive',
`tenant_no` varchar(64) NOT NULL COMMENT '租户编号',
`order_num` int DEFAULT NULL COMMENT '排序号',
`remark` varchar(1000) DEFAULT NULL COMMENT '备注',
`create_by` varchar(64) DEFAULT NULL COMMENT '创建人',
`create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建部门',
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`update_by` varchar(64) DEFAULT NULL COMMENT '更新人',
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
`del_flag` smallint NOT NULL DEFAULT 0 COMMENT '软删除 0正常 1删除',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_cert_category_product` (`tenant_no`, `category_id`, `product_id`),
KEY `idx_cert_cat_prod_product` (`tenant_no`, `product_id`, `del_flag`, `scope_status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 ROW_FORMAT=DYNAMIC COMMENT='证用品类关联系统产品';
-- ---------- 规则切点配置(每租户一行) ----------
CREATE TABLE IF NOT EXISTS `pl_cert_quota_rule_config` (
`id` varchar(64) NOT NULL COMMENT '主键UUID',
`effective_at` datetime DEFAULT NULL COMMENT '客户品类额度生效时间;空表示未配置,安排将被拦住',
`tenant_no` varchar(64) NOT NULL COMMENT '租户编号',
`order_num` int DEFAULT NULL COMMENT '排序号',
`remark` varchar(1000) DEFAULT NULL COMMENT '备注',
`create_by` varchar(64) DEFAULT NULL COMMENT '创建人',
`create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建部门',
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`update_by` varchar(64) DEFAULT NULL COMMENT '更新人',
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
`del_flag` smallint NOT NULL DEFAULT 0 COMMENT '软删除 0正常 1删除',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_cert_quota_rule_tenant` (`tenant_no`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 ROW_FORMAT=DYNAMIC COMMENT='运输证件额度规则切点';
-- ---------- 购买证扩展 ----------
SET @col = (SELECT COUNT(*) FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA=@schema_name AND TABLE_NAME='pl_purchase_cert' AND COLUMN_NAME='customer_id');
SET @sql = IF(@col=0,
'ALTER TABLE pl_purchase_cert ADD COLUMN customer_id varchar(64) DEFAULT NULL COMMENT ''系统客户ID;选证必填'' AFTER purchase_purpose',
'SELECT 1');
PREPARE s FROM @sql; EXECUTE s; DEALLOCATE PREPARE s;
SET @col = (SELECT COUNT(*) FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA=@schema_name AND TABLE_NAME='pl_purchase_cert' AND COLUMN_NAME='category_id');
SET @sql = IF(@col=0,
'ALTER TABLE pl_purchase_cert ADD COLUMN category_id varchar(64) DEFAULT NULL COMMENT ''证用品类ID;选证必填'' AFTER customer_id',
'SELECT 1');
PREPARE s FROM @sql; EXECUTE s; DEALLOCATE PREPARE s;
SET @idx = (SELECT COUNT(*) FROM information_schema.STATISTICS
WHERE TABLE_SCHEMA=@schema_name AND TABLE_NAME='pl_purchase_cert' AND INDEX_NAME='idx_purchase_cert_customer');
SET @sql = IF(@idx=0,
'ALTER TABLE pl_purchase_cert ADD KEY idx_purchase_cert_customer (tenant_no, customer_id, category_id, status, del_flag)',
'SELECT 1');
PREPARE s FROM @sql; EXECUTE s; DEALLOCATE PREPARE s;
-- ---------- 运输证扩展 ----------
SET @col = (SELECT COUNT(*) FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA=@schema_name AND TABLE_NAME='pl_transport_cert' AND COLUMN_NAME='customer_id');
SET @sql = IF(@col=0,
'ALTER TABLE pl_transport_cert ADD COLUMN customer_id varchar(64) DEFAULT NULL COMMENT ''系统客户ID;选证必填'' AFTER applicant_name',
'SELECT 1');
PREPARE s FROM @sql; EXECUTE s; DEALLOCATE PREPARE s;
SET @idx = (SELECT COUNT(*) FROM information_schema.STATISTICS
WHERE TABLE_SCHEMA=@schema_name AND TABLE_NAME='pl_transport_cert' AND INDEX_NAME='idx_transport_cert_customer');
SET @sql = IF(@idx=0,
'ALTER TABLE pl_transport_cert ADD KEY idx_transport_cert_customer (tenant_no, customer_id, status, del_flag)',
'SELECT 1');
PREPARE s FROM @sql; EXECUTE s; DEALLOCATE PREPARE s;
-- ---------- 计划规则版本 / 待完善 ----------
SET @col = (SELECT COUNT(*) FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA=@schema_name AND TABLE_NAME='pl_plan' AND COLUMN_NAME='cert_quota_rule_version');
SET @sql = IF(@col=0,
'ALTER TABLE pl_plan ADD COLUMN cert_quota_rule_version varchar(32) DEFAULT NULL COMMENT ''legacy|customer_category;创建时打标'' AFTER quota_cert_waived_time',
'SELECT 1');
PREPARE s FROM @sql; EXECUTE s; DEALLOCATE PREPARE s;
SET @col = (SELECT COUNT(*) FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA=@schema_name AND TABLE_NAME='pl_plan' AND COLUMN_NAME='quota_cert_pending_fulfill');
SET @sql = IF(@col=0,
'ALTER TABLE pl_plan ADD COLUMN quota_cert_pending_fulfill tinyint NOT NULL DEFAULT 0 COMMENT ''新规则证书齐备待完善 0否 1是'' AFTER cert_quota_rule_version',
'SELECT 1');
PREPARE s FROM @sql; EXECUTE s; DEALLOCATE PREPARE s;
@@ -0,0 +1,5 @@
-- 证用品类、运输证件规则菜单说明(路由已挂 web-admin;若侧栏走库表菜单,按租户补插)。
-- 证用品类:可挂在「运输证件管理」下,path 对齐 /pl/cert-upload/cert-category,权限复用 pl:quota-cert:list / edit。
-- 运输证件规则:可挂在「系统信息」下,path 对齐 /system/info/cert-quota-rule;保存接口要求管理员。
-- 本文件仅文档占位,不强制插入,避免破坏现有菜单树。
SELECT 1;
@@ -0,0 +1,112 @@
-- 客户+品类证件额度:证用品类、规则切点、证件/计划扩展字段。
-- MySQL 5.7。可重复执行。
-- 回滚思路(勿自动执行):停用新规则配置;新表可 DROP;新增列可 ALTER DROP(上线后有数据时先备份)。
SET NAMES utf8mb4;
SET @schema_name = DATABASE();
-- ---------- 证用品类 ----------
CREATE TABLE IF NOT EXISTS `pl_cert_category` (
`id` varchar(64) NOT NULL COMMENT '主键UUID',
`category_name` varchar(128) NOT NULL COMMENT '证用品类名称,如硫酸',
`category_code` varchar(64) DEFAULT NULL COMMENT '品类编码,可选',
`status` char(1) NOT NULL DEFAULT '1' COMMENT '状态 1启用 0停用',
`tenant_no` varchar(64) NOT NULL COMMENT '租户编号',
`order_num` int DEFAULT NULL COMMENT '排序号',
`remark` varchar(1000) DEFAULT NULL COMMENT '备注',
`create_by` varchar(64) DEFAULT NULL COMMENT '创建人',
`create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建部门',
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`update_by` varchar(64) DEFAULT NULL COMMENT '更新人',
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
`del_flag` smallint NOT NULL DEFAULT 0 COMMENT '软删除 0正常 1删除',
PRIMARY KEY (`id`),
KEY `idx_cert_category_tenant` (`tenant_no`, `del_flag`, `status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 ROW_FORMAT=DYNAMIC COMMENT='证用品类';
CREATE TABLE IF NOT EXISTS `pl_cert_category_product` (
`id` varchar(64) NOT NULL COMMENT '主键UUID',
`category_id` varchar(64) NOT NULL COMMENT '证用品类ID',
`product_id` varchar(64) NOT NULL COMMENT 'CRM产品ID',
`scope_status` varchar(20) NOT NULL DEFAULT 'active' COMMENT 'active/inactive',
`tenant_no` varchar(64) NOT NULL COMMENT '租户编号',
`order_num` int DEFAULT NULL COMMENT '排序号',
`remark` varchar(1000) DEFAULT NULL COMMENT '备注',
`create_by` varchar(64) DEFAULT NULL COMMENT '创建人',
`create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建部门',
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`update_by` varchar(64) DEFAULT NULL COMMENT '更新人',
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
`del_flag` smallint NOT NULL DEFAULT 0 COMMENT '软删除 0正常 1删除',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_cert_category_product` (`tenant_no`, `category_id`, `product_id`),
KEY `idx_cert_cat_prod_product` (`tenant_no`, `product_id`, `del_flag`, `scope_status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 ROW_FORMAT=DYNAMIC COMMENT='证用品类关联系统产品';
-- ---------- 规则切点配置(每租户一行) ----------
CREATE TABLE IF NOT EXISTS `pl_cert_quota_rule_config` (
`id` varchar(64) NOT NULL COMMENT '主键UUID',
`effective_at` datetime DEFAULT NULL COMMENT '客户品类额度生效时间;空表示未配置,安排将被拦住',
`tenant_no` varchar(64) NOT NULL COMMENT '租户编号',
`order_num` int DEFAULT NULL COMMENT '排序号',
`remark` varchar(1000) DEFAULT NULL COMMENT '备注',
`create_by` varchar(64) DEFAULT NULL COMMENT '创建人',
`create_dept_id` varchar(64) NOT NULL DEFAULT '' COMMENT '创建部门',
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`update_by` varchar(64) DEFAULT NULL COMMENT '更新人',
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
`del_flag` smallint NOT NULL DEFAULT 0 COMMENT '软删除 0正常 1删除',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_cert_quota_rule_tenant` (`tenant_no`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 ROW_FORMAT=DYNAMIC COMMENT='运输证件额度规则切点';
-- ---------- 购买证扩展 ----------
SET @col = (SELECT COUNT(*) FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA=@schema_name AND TABLE_NAME='pl_purchase_cert' AND COLUMN_NAME='customer_id');
SET @sql = IF(@col=0,
'ALTER TABLE pl_purchase_cert ADD COLUMN customer_id varchar(64) DEFAULT NULL COMMENT ''系统客户ID;选证必填'' AFTER purchase_purpose',
'SELECT 1');
PREPARE s FROM @sql; EXECUTE s; DEALLOCATE PREPARE s;
SET @col = (SELECT COUNT(*) FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA=@schema_name AND TABLE_NAME='pl_purchase_cert' AND COLUMN_NAME='category_id');
SET @sql = IF(@col=0,
'ALTER TABLE pl_purchase_cert ADD COLUMN category_id varchar(64) DEFAULT NULL COMMENT ''证用品类ID;选证必填'' AFTER customer_id',
'SELECT 1');
PREPARE s FROM @sql; EXECUTE s; DEALLOCATE PREPARE s;
SET @idx = (SELECT COUNT(*) FROM information_schema.STATISTICS
WHERE TABLE_SCHEMA=@schema_name AND TABLE_NAME='pl_purchase_cert' AND INDEX_NAME='idx_purchase_cert_customer');
SET @sql = IF(@idx=0,
'ALTER TABLE pl_purchase_cert ADD KEY idx_purchase_cert_customer (tenant_no, customer_id, category_id, status, del_flag)',
'SELECT 1');
PREPARE s FROM @sql; EXECUTE s; DEALLOCATE PREPARE s;
-- ---------- 运输证扩展 ----------
SET @col = (SELECT COUNT(*) FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA=@schema_name AND TABLE_NAME='pl_transport_cert' AND COLUMN_NAME='customer_id');
SET @sql = IF(@col=0,
'ALTER TABLE pl_transport_cert ADD COLUMN customer_id varchar(64) DEFAULT NULL COMMENT ''系统客户ID;选证必填'' AFTER applicant_name',
'SELECT 1');
PREPARE s FROM @sql; EXECUTE s; DEALLOCATE PREPARE s;
SET @idx = (SELECT COUNT(*) FROM information_schema.STATISTICS
WHERE TABLE_SCHEMA=@schema_name AND TABLE_NAME='pl_transport_cert' AND INDEX_NAME='idx_transport_cert_customer');
SET @sql = IF(@idx=0,
'ALTER TABLE pl_transport_cert ADD KEY idx_transport_cert_customer (tenant_no, customer_id, status, del_flag)',
'SELECT 1');
PREPARE s FROM @sql; EXECUTE s; DEALLOCATE PREPARE s;
-- ---------- 计划规则版本 / 待完善 ----------
SET @col = (SELECT COUNT(*) FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA=@schema_name AND TABLE_NAME='pl_plan' AND COLUMN_NAME='cert_quota_rule_version');
SET @sql = IF(@col=0,
'ALTER TABLE pl_plan ADD COLUMN cert_quota_rule_version varchar(32) DEFAULT NULL COMMENT ''legacy|customer_category;创建时打标'' AFTER quota_cert_waived_time',
'SELECT 1');
PREPARE s FROM @sql; EXECUTE s; DEALLOCATE PREPARE s;
SET @col = (SELECT COUNT(*) FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA=@schema_name AND TABLE_NAME='pl_plan' AND COLUMN_NAME='quota_cert_pending_fulfill');
SET @sql = IF(@col=0,
'ALTER TABLE pl_plan ADD COLUMN quota_cert_pending_fulfill tinyint NOT NULL DEFAULT 0 COMMENT ''新规则证书齐备待完善 0否 1是'' AFTER cert_quota_rule_version',
'SELECT 1');
PREPARE s FROM @sql; EXECUTE s; DEALLOCATE PREPARE s;
@@ -0,0 +1,227 @@
# 客户+品类证件额度 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use `.agents/skills/subagent-driven-development/SKILL.md`(推荐)或 `.agents/skills/executing-plans/SKILL.md` 按任务推进。步骤用 checkbox(`- [ ]`)跟踪。
> **设计权威:** `docs/superpowers/specs/2026-11-14-pl-customer-cert-quota-design.md`
> **硬性闸门:** 每期全部 checkbox 完成并验证后,必须停下来等用户回复「开始第N期」再继续;未经确认不得进入下一期或 commit(除非用户当轮明确要求提交)。
**Goal:** 将运输计划购买证/运输证从合同产品绑定改为客户+证用品类自动选证,并落地可配置切点与齐备完善流程。
**Architecture:** 保留 `pl_plan_cert_usage` 账本;新建证用品类与规则配置表;证件增加 `customer_id`/`category_id`;新规则下用证来源按段次外部客户提取,选证改为整笔贪心(到期早且余量够优先);`quota_cert_waived` 仅放行安排,归档与完善走真证 reserve/settle。
**Tech Stack:** Python 3.9 / FastAPI / SQLAlchemy / Pydantic v2;Vue 3 / Element Plus / pnpm;MySQL 5.7;pytest。
---
## 文件地图(将创建或重点修改)
| 区域 | 路径 |
| --- | --- |
| SQL | `docs/sql/2026-11-14-pl-customer-cert-quota.sql`(及 migrations 副本若仓库惯例需要) |
| 模型 | `backend/app/models/pl_quota_models.py`、`pl_models.py` |
| 选证/账本 | `backend/app/services/pl_quota_sources.py`、`pl_quota_planning.py`、`pl_quota_allocation.py`、`pl_quota_usage_service.py`、`pl_quota_business.py`、`pl_quota_waiver.py`、新建 `pl_quota_customer_select.py`(建议)、`pl_cert_category_service.py`、`pl_cert_quota_rule_config_service.py` |
| API | `backend/app/api/pl/quota_cert.py`、`transport.py`、`plan.py`;系统配置 API(新建或挂 system) |
| 测试 | `backend/tests/test_pl_quota_*.py` 扩展;新建 `test_pl_customer_cert_quota.py` |
| Web | `web-admin/src/views/pl/` 品类页、quota-cert、证书齐备、系统信息 Tab、计划详情/查看组件;去掉安排手工用证入口 |
| 路由/菜单 | `web-admin/src/router/modules/sqxp.ts`、`pl.ts`;菜单 SQL 若需要 |
---
## 一期:主数据 + 切点配置 + 列表默认过滤
### Task 1.1:DDL
**Files:**
- Create: `docs/sql/2026-11-14-pl-customer-cert-quota.sql`
- [ ] **Step 1:** 编写可重复执行的 MySQL 5.7 迁移,包含:
- `pl_cert_category`
- `pl_cert_category_product`
- `pl_cert_quota_rule_config`(tenant_no + effective_at + 审计)
- `pl_purchase_cert.customer_id`、`category_id`(可空,兼容历史)
- `pl_transport_cert.customer_id`(可空)
- `pl_plan.cert_quota_rule_version` VARCHAR(可空/默认 legacy)
- `pl_plan.quota_cert_pending_fulfill` TINYINT 默认 0(或设计等价字段)
- [ ] **Step 2:** 字段注释与 AGENTS 字段序一致;索引含 tenant_no + 常用筛选。
- [ ] **Step 3:** 在设计实现备注中列出回滚思路(DROP/列删除仅文档说明,不自动执行破坏性回滚)。
### Task 1.2:模型与品类 CRUD API
**Files:**
- Modify: `backend/app/models/pl_quota_models.py`、`pl_models.py`
- Create: `backend/app/services/pl_cert_category_service.py`
- Modify: `backend/app/api/pl/quota_cert.py` 或新建 `quota_category.py` 并注册到 `api/__init__.py`、`main.py`
- Create: schemas under `backend/app/schemas/pl/`
- [ ] **Step 1:** 增加 SQLAlchemy 模型与 Pydantic schema(camelCase alias)。
- [ ] **Step 2:** 品类 CRUD + 关联产品差量保存(遵守 child-data-save-rules)。
- [ ] **Step 3:** pytest:创建品类、关联两产品、停用关联、租户隔离。
- [ ] **Step 4:** 证件 create/update 接受 `customerId`/`categoryId`;运输证品类由引用推导的只读接口字段。
### Task 1.3:规则配置 API + 安排门禁(未配置则拦)
**Files:**
- Create: `backend/app/services/pl_cert_quota_rule_config_service.py`
- Modify: `backend/app/api/pl/transport.py`(arrange 入口最前)
- Modify: 计划创建服务(写入 `cert_quota_rule_version`)
- [ ] **Step 1:** GET/PUT 当前租户 `effective_at`。
- [ ] **Step 2:** `assert_cert_quota_rule_configured`:`effective_at is None` → HTTP 409 固定中文文案。
- [ ] **Step 3:** 计划创建时按设计 §7 打 `cert_quota_rule_version`。
- [ ] **Step 4:** pytest:未配置安排失败;配置后创建计划版本正确。
### Task 1.4:证件列表默认过滤
**Files:**
- Modify: `backend/app/services/pl_quota_cert_service.py` list 默认
- Modify: `web-admin/src/views/pl/quota-cert/` 状态漏斗
- [ ] **Step 1:** 列表 API 默认 `status not in (closed, void)`;显式传 status 时以参数为准。
- [ ] **Step 2:** 前端列头漏斗可选到已核销/作废;默认不选。
- [ ] **Step 3:** 回归测试或前端约定注释。
### Task 1.5:Web 品类页 + 系统信息 Tab + 证件表单字段
**Files:**
- Create: `web-admin/src/views/pl/cert-category/index.vue`(或等价路径)
- Modify: `web-admin/src/router/modules/pl.ts`、`sqxp.ts`
- Modify: 证件建档表单(含 H5 `m/pl/plan-cert` 若同表单模型)
- [ ] **Step 1:** 品类列表/编辑/关联产品(Fresh Mint,选 P 模式并在说明中写明)。
- [ ] **Step 2:** 系统信息下 Tab「运输证件规则」编辑生效时间。
- [ ] **Step 3:** 购买证/运输证表单增加客户、品类(运输证展示派生品类)。
- [ ] **Step 4:** 菜单 SQL/权限码文档化(若需插入菜单,写 SQL 片段)。
### Task 1.6:计划详情展示位(可读)
**Files:**
- Modify: `web-admin/src/components/business/pl-plan-view-tabs/` 或等价详情
- Modify: 计划详情 API 若需返回 usage 证件摘要
- [ ] **Step 1:** 详情区展示已关联购买证/运输证(无数据时占位「暂无」)。
- [ ] **Step 2:** 同市来源可只显示购买证。
### 一期完成门禁
- [ ] 本地执行相关 pytest,记录命令与结果。
- [ ] `pnpm build:typecheck`(若改了 web-admin)或说明未跑原因。
- [ ] **停止并等待用户:「开始第二期」**
---
## 二期:安排/归档新选证 + 祖父条款
### Task 2.1:用证来源按段客户(D6/D7/D8/D9)
**Files:**
- Modify: `backend/app/services/pl_quota_sources.py`
- [ ] **Step 1:** 外部装/送段均进入来源(非仅单侧计量吞掉对侧额度需求——按设计 D7);内部山峡/云栋过滤保留。
- [ ] **Step 2:** `same_city` → `requires_transport=False` 保留。
- [ ] **Step 3:** 来源快照写入 `customer_id`/`customer_name`。
- [ ] **Step 4:** pytest 覆盖双外部段、单侧内部、同市。
### Task 2.2:整笔贪心选证模块
**Files:**
- Create: `backend/app/services/pl_quota_customer_select.py`
- Modify: `pl_quota_allocation.py` 或在 `execute_usage` 分支按 rule_version 调用
- [ ] **Step 1:** 实现设计 §5 伪代码;单测:10 吨跳过、100 吨命中;无运输证跳过该购买证;同市无运输证成功。
- [ ] **Step 2:** 新规则路径禁止拆分到多购买证。
- [ ] **Step 3:** legacy 计划不走此模块(祖父)。
### Task 2.3:替换合同绑证为客户品类候选
**Files:**
- Modify: `pl_quota_planning.py`、`pl_quota_business.py`、`pl_quota_usage_service.py`
- Modify: `backend/app/api/pl/transport.py`、前端安排提交
- [ ] **Step 1:** `customer_category` 版本:`build_usage_request` 不再 `resolve_contract_bound_certs`。
- [ ] **Step 2:** 安排失败文案引导证书齐备;移除/隐藏手工 `quotaConfiguration` 安排入口。
- [ ] **Step 3:** 归档 settle 仍走账本;新规则余额不足文案更新为客户/品类语境。
- [ ] **Step 4:** legacy:已安排归档不因缺少客户品类绑证失败(单测)。
### Task 2.4:合同绑证 UI 收敛
**Files:**
- Modify: `web-admin/src/views/pl/contract-quota/` 等
- [ ] **Step 1:** 新规则生效后隐藏或只读提示,避免双轨操作。
### 二期完成门禁
- [ ] 相关 pytest 全绿并记录。
- [ ] **停止并等待用户:「开始第三期」**
---
## 三期:证书齐备 2.0
### Task 3.1:waiver 语义
**Files:**
- Modify: `backend/app/services/pl_quota_waiver.py`、`pl_quota_business.py`
- Modify: `backend/app/api/pl/plan.py` archive
- [ ] **Step 1:** 标记齐备 → `quota_cert_pending_fulfill=1`,安排可跳过 reserve。
- [ ] **Step 2:** `settle`/`archive`:若 pending 或 waived 未完善 → 409,不得跳过额度。
- [ ] **Step 3:** pytest:齐备可安排、不可归档;完善后可归档。
### Task 3.2:完善并关闭 API
**Files:**
- Modify: `backend/app/api/pl/plan.py` 或 `quota_cert.py`
- Create service:对单计划执行与安排相同的选证 + reserve
- [ ] **Step 1:** `POST .../fulfill-quota-certs`(单条)与 batch 接口。
- [ ] **Step 2:** 成功:写 usage、清 pending、出队;失败:保留 pending + 原因。
- [ ] **Step 3:** 并发单测或文档化行锁策略。
### Task 3.3:证书齐备 Web
**Files:**
- Modify/Create: 证书齐备列表页(现有 menu 路由对齐)
- [ ] **Step 1:** 仅列出新规则待完善计划。
- [ ] **Step 2:** 上传购买证/运输证入口。
- [ ] **Step 3:** 操作列完善并关闭 + 批量;成功刷新列表。
- [ ] **Step 4:** 归档弹窗对接「未完善」错误引导。
### Task 3.4:详情展示真实挂证
- [ ] **Step 1:** 完善或安排成功后详情可见证号/品类/占用等摘要。
### 三期完成门禁
- [ ] 全链路 pytest + 必要前端 typecheck。
- [ ] 更新本 plan 所有 checkbox;在设计文档顶部标注「已实现待验收」或按用户要求提交。
- [ ] **停止并等待用户验收;非用户要求不要 push。**
---
## 数据迁移作业(可穿插在一期后、切点打开前)
- [ ] 提供只读 SQL/脚本:按 `product_name_on_cert` 分组列出候选品类名。
- [ ] 文档说明:用户手工建品类并关联产品、回填证件 `customer_id`/`category_id` 后再配置 `effective_at`。
## Spec 覆盖自检
| 设计条款 | 任务 |
| --- | --- |
| 品类主数据 | 1.1–1.2, 1.5 |
| 客户绑证/解析保留 | 1.2, 1.5 |
| effective_at + 未配置拦安排 | 1.3, 1.5 |
| 列表过滤 closed/void | 1.4 |
| 详情展示 | 1.6, 3.4 |
| 选证 A + 双段扣证 | 2.1–2.3 |
| 无手工选证 | 2.3 |
| legacy 祖父 | 2.3 |
| 齐备只放行安排 | 3.1–3.3 |
| 合法使用证明不动 | 无任务改动(回归时确认) |
## 执行说明(给 Agent)
1. 先完整阅读设计文档与本计划,再读 `backend/AGENTS.md`、将改动的端 AGENTS。
2. 使用 personal-dev 任务分级;每 Task 优先补/改 pytest 再写实现。
3. 一期未完成不得开始二期逻辑依赖(可先写二期测试草稿但不合并行为)。
4. 每期结束用简体中文汇报:改了什么、验证命令与结果、未跑项、请用户确认下一期。
@@ -0,0 +1,229 @@
# 运输计划购买证/运输证:客户+品类额度改造设计
> 状态:实现中(2026-11-14 本会话已落地核心后端 + 关键 Web;待执行 SQL 与业务验收)
> 关联计划:`docs/superpowers/plans/2026-11-14-pl-customer-cert-quota.md`
> 现状参考:`openspec/changes/pl-contract-cert-quota-control/`(合同绑证模型,本需求起新规则不再作为选证来源)
## 1. 目标与非目标
### 目标
将易制毒购买证/运输证的适用范围从「合同 + 合同产品」改为「客户 + 证用品类」,安排仅自动选证(整笔不拆证),证书齐备只放行安排、归档必须真证挂载,并用可配置生效时间做历史祖父,降低上线冲击。
### 非目标
- 不改变易制爆「合法使用证明」现状。
- 不推倒 `pl_plan_cert_usage` / `pl_cert_qty_log` 核销账本,只改候选来源与门禁。
- 不复用 CRM `crm_product_category` 作为证用品类。
- 安排界面不做手工选证。
- 产品行 `purchase_cert_url` / `transport_cert_url` 附件能力可保留作展示/打包,但**不再**作为安排/归档额度门禁。
## 2. 已拍板决策一览
| 编号 | 决策 |
| --- | --- |
| D1 | 证绑定客户,不绑定合同/合同产品 |
| D2 | 独立证用品类;购买证绑一个品类;品类 → 多个系统产品 |
| D3 | 运输证绑客户 + 引用购买证;品类 = 引用购买证品类并集去重 |
| D4 | 同客户下所有合同可用该客户证件(仍受品类/有效期/车号/余量约束) |
| D5 | 选证规则 A:单证须整笔盖住本次需求,不够则跳过换下一张到期更晚但够量的;按 `valid_to` 升序 |
| D6 | 按段次外部客户选证:装货段用供应商客户,送货段用收货客户 |
| D7 | 装、送凡外部且需用证的段,各扣各的(可双套) |
| D8 | 安庆山峡、安徽云栋豁免购买证/运输证 |
| D9 | 同市(段次 `same_city=1`)只要求购买证 |
| D10 | 安排只自动选证;选不到只能「证书齐备」;无手工选证 |
| D11 | 证书齐备:可安排;归档不可绕过 |
| D12 | 齐备列表:上传证 → 单条/批量「完善并关闭」(同安排选证)→ 成功出队 |
| D13 | 计划详情展示已关联购买证/运输证 |
| D14 | 解析后自动绑定系统客户:保留 |
| D15 | 证件列表默认不展示 `closed`/`void`,列头漏斗可筛 |
| D16 | 切点:【系统信息】配置 `effective_at`;未配置则拦住安排;计划创建时打规则版本 |
| D17 | 上线前创建计划:不因新规则挡归档;旧齐备不进待完善 |
| D18 | 品类↔产品映射由人工配置;可从证面品名辅助归纳品类 |
## 3. 现状要点(改造锚点)
| 能力 | 路径 | 改造动作 |
| --- | --- | --- |
| 合同绑证选证 | `pl_quota_planning.resolve_contract_bound_certs` 等 | 新规则停用为选证源 |
| 用证来源 | `pl_quota_sources.extract_sources` | 按段客户;双侧外部都进来源(对齐 D7);内部客户过滤保留 |
| 分配 | `pl_quota_allocation.allocate_plan` | 改为整笔贪心(D5),不再为新规则做跨证拆分 |
| 安排挂钩 | `pl/transport.py` → `apply_plan_quota(reserve\|resize)` | 切点校验 + 新候选 |
| 归档挂钩 | `pl/plan.py` → `settle_plan_quota` | 齐备不可跳过 settle(新规则) |
| 齐备 | `pl_quota_waiver` | 安排可 waive;归档不可;完善写账本 |
| 证件主数据 | `pl_purchase_cert` / `pl_transport_cert` | 增加客户 ID、品类 ID 等 |
## 4. 数据模型
### 4.1 新建:证用品类
**表 `pl_cert_category`**
- 标准业务字段序:id → 业务字段 → tenant_no、order_num、remark、审计、del_flag
- 业务字段建议:`category_name`(如硫酸)、`category_code`(可选)、`status`(启用/停用)
**表 `pl_cert_category_product`**
- `category_id`、`product_id`(CRM 产品)、`scope_status`(active/inactive)
- 租户内 `(category_id, product_id)` 有效行唯一
### 4.2 证件主数据扩展
**`pl_purchase_cert`**
- `customer_id`(系统客户,必填后方可 active 参与选证;解析自动匹配保留)
- `category_id`(证用品类,必填后方可参与选证)
- 保留 `product_name_on_cert` 证面原文
**`pl_transport_cert`**
- `customer_id`(系统客户)
- 品类不落冗余主字段亦可:选证时由 `pl_transport_cert_purchase_ref` → 购买证 `category_id` 并集计算;若需列表筛选可冗余缓存并在引用变更时刷新
**`pl_transport_cert_purchase_ref`**
- 继续作为运输证 ↔ 购买证引用;选证要求引用的购买证参与本段配对
### 4.3 合同绑证表
- `pl_contract_cert_link` / `pl_contract_cert_product`:**新规则选证不再读取**
- 表可保留只读/历史;前端合同绑证入口对新规则租户隐藏或只读提示「已改为客户+品类」
### 4.4 计划与切点
**系统配置(新建表,推荐 `pl_cert_quota_rule_config` 或租户参数表)**
- `tenant_no`
- `effective_at`(DATETIME,可空)
- 审计字段
- 每租户一行(或最新有效一行)
**`pl_plan` 增加**
- `cert_quota_rule_version`:`legacy` | `customer_category`(创建时写入;空/null 视为 legacy)
- 可选保留 `quota_cert_waived*`;语义见 §6
- 建议增加完善标记,例如:
- `quota_cert_pending_fulfill`:1 = 已齐备待完善(新规则)
- 或用「waived=1 且无 settled/reserved 新规则用量」推断;实现时优先显式字段以免歧义
### 4.5 用量账本
- 继续使用 `pl_plan_cert_usage` / `pl_plan_cert_usage_item` / `pl_cert_qty_log`
- item 上原「合同绑定」维度改为可空或改为记录 `customer_id` + `category_id` 快照;以最小迁移为准,保证对账可追溯
## 5. 选证算法(新规则)
对每个用证来源(段 × 易制毒产品行,外部客户,非豁免):
```
需求量 Q,单位 U,客户 C,产品 P,是否同市 S,车号 V,业务日 D
1. 解析品类:P 落在哪些 active 的 pl_cert_category_product → 得到 category 集合
2. 候选购买证:
- customer_id=C, category_id∈集合, status=active 且已复核
- D ∈ [valid_from, valid_to]
- available = total - reserved - used(及一次有效等现有占用规则)≥ Q(同单位;异单位按现有换算/拦截策略)
3. 按 valid_to ASC, id ASC 排序
4. 依次尝试购买证 B:
- 若 S(同市):选中 B,结束本源
- 若异地:在「引用了 B」的运输证中找 T:
- customer_id=C(或与业务确认是否允许仅购买证客户一致)
- 车号覆盖 V,有效期与 active/复核,available ≥ Q
- 可按 T.valid_to ASC 取第一张
- 找不到 T 则跳过 B,试下一张购买证
5. 若无一整笔覆盖 → 本源失败 → 整单安排失败(或完善失败)
```
多产品/多段:每个来源独立跑上述算法;详情与账本按来源挂多证。
**禁止**:把 Q 拆到多张购买证(D5)。
## 6. 证书齐备 2.0
| 动作 | 新规则行为 |
| --- | --- |
| 标记齐备 | 允许在证件不足时安排;释放已有预占(若有);置待完善;**不**写 usage 预占 |
| 安排 | `apply_plan_quota` 对 waived+pending 跳过 reserve(与今类似,但仅安排路径) |
| 归档 | **禁止**因 waived 跳过 settle;若仍 pending 完善 → 409 提示先去证书齐备完善 |
| 完善并关闭 | 按 §5 自动选证并 `reserve`(计划已安排)或等价补记账;成功清除 pending,出列表 |
| 批量完善 | 对勾选行逐单执行;部分成功部分失败,返回明细 |
| 列表范围 | 仅 `cert_quota_rule_version=customer_category` 且待完善的计划;legacy 齐备不进列表 |
界面:证书齐备页支持上传购买证/运输证(解析绑客户保留)+ 操作列完善并关闭 + 批量。
## 7. 切点与门禁
```
arrange / resize:
if effective_at is null:
409「请先在系统信息中配置客户品类额度生效时间」
resolve plan.cert_quota_rule_version(已打标用标;未打标且 create_time>=effective_at 视为新规则并补标——仅创建路径应打标,安排时以已存字段为准)
if version == customer_category:
走 §5;失败可引导证书齐备
else:
祖父:不按新客户品类规则拦截归档相关;安排若仍发生,建议对 legacy 保持「不强制新选证」或只读旧行为——
【定稿】上线前创建的计划:已安排不挡归档;若 legacy 计划再次调整运输,实现时默认也不强制新规则选证(避免历史单改派被卡死),在设计实现备注中写清并单测覆盖。
```
**系统信息 Tab**
- 路由挂在现有「系统信息」下(`web-admin/src/router/modules/sqxp.ts` 的 SystemInfo 子级)
- 配置 `effective_at`;保存权限建议管理员
- 文案说明:未配置将无法安排运输;修改只影响之后新建且按创建打标的计划
**计划创建**
```
if effective_at and create_time >= effective_at:
cert_quota_rule_version = customer_category
else:
cert_quota_rule_version = legacy
```
## 8. 前端范围
| 页面/组件 | 变更 |
| --- | --- |
| 证用品类管理 | 新建列表+关联产品 |
| 购买证/运输证建档 | 客户、品类;运输证引用;列表默认排除 closed/void |
| 合同绑证 UI | 新规则下隐藏或只读说明 |
| 安排 | 去掉手工用证配置;失败文案引导齐备 |
| 计划详情/查看 | 展示关联购买证/运输证 |
| 证书齐备 | 列表、上传、完善并关闭、批量 |
| 系统信息 | 新 Tab 配置生效时间 |
| 归档 | 待完善不可归档的提示 |
H5 `m/pl/plan-cert`:评估与 Web 对齐的上传/建档;完善列表以 Web 为主时可第二期补齐,但不可破坏现有 H5 建档。
## 9. 历史数据迁移
1. **证件**:从现有证面 `product_name_on_cert` 归纳候选品类名,脚本/SQL 可生成品类草稿;**品类↔产品**由用户在界面手工完成后再开切点。
2. **客户**:尽量用现有解析/名称匹配回填 `customer_id`;匹配不上保持空,active 选证前必须补齐。
3. **计划**:不批量改历史 `quota_cert_waived`;不强制历史单进待完善。
4. **切点**:业务准备好后在系统信息填写 `effective_at`(可等于「今天 0 点」或切换瞬间)。
## 10. 分期
| 期 | 内容 | 可验收结果 |
| --- | --- | --- |
| 一期 | 品类主数据、证件绑客户/品类、列表默认过滤、系统信息 effective_at、详情展示位(可先读账本) | 未配时间则安排被拦;可维护品类与证件 |
| 二期 | 新选证算法接入安排/归档;legacy 祖父;停用合同选证源 | 新计划按客户品类自动占证/结转 |
| 三期 | 齐备 2.0 列表与完善并关闭;归档强制已完善 | 齐备可安排、完善后可归档 |
## 11. 验收要点
- 同市只扣购买证;异地购买证+运输证;山峡/云栋不扣。
- 10 吨早到期 + 100 吨晚到期、需求 >10 → 只用 100 吨那套。
- 硫酸+盐酸两产品 → 两套(或多段)独立挂证。
- 未配置 effective_at → 安排 409。
- legacy 已安排 → 可归档不被新规则卡死。
- 新规则齐备 → 可安排、不可归档;完善成功后可归档且账本有用量。
- 证件列表默认无已核销/作废。
- 合法使用证明行为与改前一致。
## 12. 风险
- D7 双侧扣证可能使额度消耗快于客户直觉,需在界面展示「本段客户/用证」。
- 改 `effective_at` 若未打标会漂;必须创建打标。
- 完善批量并发抢同一证余量:逐单事务 + 行锁(沿用现有证件锁)。
- 分配器从可拆分改为整笔:旧单测需分流 legacy/新规则。