WuYongJie/CaiWuXiTong
1
0
Fork 0
Code Issues Pull Requests 2 Packages Projects Releases Wiki Activity

报价变更与 E 签宝签署闭环 #47

Merged
limeng merged 7 commits from feature/limeng-courier-quote-change-workflow into main 2026-08-15 16:48:13 +08:00
Conversation 0 Commits 7 Files Changed 32 +3374 -283
limeng commented 2026-08-13 18:53:53 +08:00
Collaborator
Copy Link

任务占用与边界

  • 任务名称：报价变更与 E 签宝签署闭环
  • 实际开发者：limeng
  • 任务来源/团队分工：报价及变价后的报价需要生成 PDF，推送 E 签宝给快递公司签署，签完回传并留档；历史生效保留追溯核算状态
  • 目标结果：报价变更审核后生成不可变 PDF；按报价版本推送 E 签宝沙箱；支持签署状态同步与验签回调；完成后下载签署 PDF 和完成证书到私有业务存储；报价详情可查看状态与下载归档文件
  • 实际修改路径：报价变更 Controller/Model/Service/页面与测试；E 签宝 Client/签名器/回调/归档 Job；报价 PDF 模板与中文字体；routes/admin.php、routes/web.php、config/services.php；两项报价工作流迁移
  • 将写入的公共契约：表 business_courier_quote_changes、business_courier_quote_change_items、business_courier_quote_change_events、business_courier_quote_versions、business_courier_quote_signatures；路由 business.courier-quote-changes.*、business.courier-quote-signatures.*、integrations.esign.callback；配置 services.esign / ESIGN_*
  • 仅复用、明确不修改的公共契约：权限中间件 business.page:courier-payables,quote-management；管理员角色；私有逻辑盘 uploads；Dompdf；既有报价管理页面入口
  • 数据源、表/视图和字段：不新增上游查询；E 签宝仅接收批准后生成的报价 PDF 和管理员明确提交的签署联系人
  • 上游 source_key / scope：不新增、不修改
  • 权限名、菜单键或共享组件：复用报价管理权限和菜单键，不新增权限
  • 明确不修改的范围：协议签署模块、上游数据库、运费原记录、原报价 Excel、生产配置、历史运费自动补差算法

开工碰撞检查

  • 已读取最新 main、所有远程任务分支和主线既有实现
  • 已把写入与只复用契约分开
  • 已使用精确路径和公共契约运行 scripts/codex-task-preflight.ps1
  • 未发现远程任务分支与本任务的实际写入重叠

检查结论：分支已普通 merge 最新 origin/main（809bca2），无冲突；协议签署分支未修改本任务文件或契约。

实际改动

  • 完成报价变更草稿、提交、审核、退回、不可覆盖新版本与历史生效/追溯状态
  • 审核后生成不可变报价 PDF 并保存 SHA-256；签署开始后禁止重新生成原文
  • 接入 E 签宝沙箱文件上传、签署流程创建、状态查询与手动同步
  • 回调校验 App ID、时间窗和 HMAC-SHA256，按签署流程幂等更新状态
  • 完成后下载已签 PDF 与完成证书，写入私有 uploads/courier-quotes/{company_id}/{version_code}/
  • 报价详情页增加签署状态、联系人、通知方式、截止时间、推送、同步和归档下载；推送/同步仅管理员可操作
  • 沙箱未配置 App ID/AppSecret 时按钮禁用，不创建签署任务
  • 归档失败会保留错误并抛出，让队列正常重试；手动同步仍可兜底
  • 与原计划的差异：历史运费自动重算和补差仍未实现，签署完成不代表补差完成

验证证据

  • 自动测试：23 passed, 173 assertions；签署链路 9 项场景（其中隔离容器缺少 .env 产生 2 条环境警告，不影响断言）
  • 覆盖：正常推送、原文篡改阻断、签署后不可重生、非管理员 403、手动归档、队列重试、回调验签与幂等、历史生效、公式单元格保护、跨公司和无权限场景
  • PHP 语法：17 个相关 PHP 文件全部通过 php -l
  • 路由：4 条签署业务路由和 1 条回调路由均已通过 artisan route:list 核对
  • 页面：隔离环境桌面 1440x900、移动端 390x844 实测，无页面横向溢出、表单重叠或按钮错位；未配置沙箱时禁用状态和提示正确
  • PDF：Poppler 渲染两页复核，中文、数字、差异表、完整报价表、签章区���页脚无方框字、截断或重叠
  • 设计：符合根目录 DESIGN.md VIP 黑金规范，无批准偏差
  • 数据库：只在隔离 SQLite 验证；未执行共享或生产数据库迁移
  • E 签宝：HTTP 使用测试替身验证；未配置真实 AppSecret，未创建真实沙箱签署流程

风险检查

  • 不涉及金额、权限、审批、数据库迁移、生产配置或数据修复
  • 涉及金额展示、审批后文件固化、外部签署、回调和数据库迁移
  • 回调按官方 App ID、时间窗和 HMAC 签名验签，幂等处理；本地无法接收公网回调时保留手动同步
  • PDF、签署件和证书使用私有 uploads 逻辑盘，不提供公开直链
  • 未提交 .env、AppSecret、Token、私钥、真实财务数据、生产日志或构建产物
  • 前端改动遵守 DESIGN.md VIP 黑金规范，无批准偏差

风险与回滚：金额和历史运费原记录不被覆盖；新表和归档文件按报价版本独立保存。代码可回退 squash 合并提交；迁移回滚必须在获授权维护窗口执行，归档文件不自动删除。生产迁移、真实 E 签宝配置和部署均不在本 PR 中执行。

合并前复查

  • 已重新拉取远程引用并用实际修改范围再次运行碰撞检查
  • PR 不再是 WIP:，所有测试结果已经补齐
  • Codex 已重新读取原始需求和验收标准，并逐文件审核 origin/main...任务分支 的完整 diff
  • Codex 自审确认无越界修改、重复实现、敏感内容、未处理冲突和未验证结果
  • 合并顺序不会覆盖其他未合并任务
  • 已授权当前任务的 Codex 执行 Squash merge、验证 main 并清理任务分支
  • 本次不执行生产迁移、数据修复、删除、覆盖配置或部署；如后续执行需另行取得高风险授权
## 任务占用与边界 - 任务名称：报价变更与 E 签宝签署闭环 - 实际开发者：limeng - 任务来源/团队分工：报价及变价后的报价需要生成 PDF，推送 E 签宝给快递公司签署，签完回传并留档；历史生效保留追溯核算状态 - 目标结果：报价变更审核后生成不可变 PDF；按报价版本推送 E 签宝沙箱；支持签署状态同步与验签回调；完成后下载签署 PDF 和完成证书到私有业务存储；报价详情可查看状态与下载归档文件 - 实际修改路径：报价变更 Controller/Model/Service/页面与测试；E 签宝 Client/签名器/回调/归档 Job；报价 PDF 模板与中文字体；`routes/admin.php`、`routes/web.php`、`config/services.php`；两项报价工作流迁移 - 将写入的公共契约：表 `business_courier_quote_changes`、`business_courier_quote_change_items`、`business_courier_quote_change_events`、`business_courier_quote_versions`、`business_courier_quote_signatures`；路由 `business.courier-quote-changes.*`、`business.courier-quote-signatures.*`、`integrations.esign.callback`；配置 `services.esign` / `ESIGN_*` - 仅复用、明确不修改的公共契约：权限中间件 `business.page:courier-payables,quote-management`；管理员角色；私有逻辑盘 `uploads`；Dompdf；既有报价管理页面入口 - 数据源、表/视图和字段：不新增上游查询；E 签宝仅接收批准后生成的报价 PDF 和管理员明确提交的签署联系人 - 上游 `source_key` / `scope`：不新增、不修改 - 权限名、菜单键或共享组件：复用报价管理权限和菜单键，不新增权限 - 明确不修改的范围：协议签署模块、上游数据库、运费原记录、原报价 Excel、生产配置、历史运费自动补差算法 ## 开工碰撞检查 - [x] 已读取最新 `main`、所有远程任务分支和主线既有实现 - [x] 已把写入与只复用契约分开 - [x] 已使用精确路径和公共契约运行 `scripts/codex-task-preflight.ps1` - [x] 未发现远程任务分支与本任务的实际写入重叠 检查结论：分支已普通 merge 最新 `origin/main`（`809bca2`），无冲突；协议签署分支未修改本任务文件或契约。 ## 实际改动 - 完成报价变更草稿、提交、审核、退回、不可覆盖新版本与历史生效/追溯状态 - 审核后生成不可变报价 PDF 并保存 SHA-256；签署开始后禁止重新生成原文 - 接入 E 签宝沙箱文件上传、签署流程创建、状态查询与手动同步 - 回调校验 App ID、时间窗和 HMAC-SHA256，按签署流程幂等更新状态 - 完成后下载已签 PDF 与完成证书，写入私有 `uploads/courier-quotes/{company_id}/{version_code}/` - 报价详情页增加签署状态、联系人、通知方式、截止时间、推送、同步和归档下载；推送/同步仅管理员可操作 - 沙箱未配置 App ID/AppSecret 时按钮禁用，不创建签署任务 - 归档失败会保留错误并抛出，让队列正常重试；手动同步仍可兜底 - 与原计划的差异：历史运费自动重算和补差仍未实现，签署完成不代表补差完成 ## 验证证据 - 自动测试：`23 passed, 173 assertions`；签署链路 `9` 项场景（其中隔离容器缺少 `.env` 产生 2 条环境警告，不影响断言） - 覆盖：正常推送、原文篡改阻断、签署后不可重生、非管理员 403、手动归档、队列重试、回调验签与幂等、历史生效、公式单元格保护、跨公司和无权限场景 - PHP 语法：17 个相关 PHP 文件全部通过 `php -l` - 路由：4 条签署业务路由和 1 条回调路由均已通过 `artisan route:list` 核对 - 页面：隔离环境桌面 `1440x900`、移动端 `390x844` 实测，无页面横向溢出、表单重叠或按钮错位；未配置沙箱时禁用状态和提示正确 - PDF：Poppler 渲染两页复核，中文、数字、差异表、完整报价表、签章区���页脚无方框字、截断或重叠 - 设计：符合根目录 `DESIGN.md` VIP 黑金规范，无批准偏差 - 数据库：只在隔离 SQLite 验证；未执行共享或生产数据库迁移 - E 签宝：HTTP 使用测试替身验证；未配置真实 AppSecret，未创建真实沙箱签署流程 ## 风险检查 - [ ] 不涉及金额、权限、审批、数据库迁移、生产配置或数据修复 - [x] 涉及金额展示、审批后文件固化、外部签署、回调和数据库迁移 - [x] 回调按官方 App ID、时间窗和 HMAC 签名验签，幂等处理；本地无法接收公网回调时保留手动同步 - [x] PDF、签署件和证书使用私有 `uploads` 逻辑盘，不提供公开直链 - [x] 未提交 `.env`、AppSecret、Token、私钥、真实财务数据、生产日志或构建产物 - [x] 前端改动遵守 `DESIGN.md` VIP 黑金规范，无批准偏差 风险与回滚：金额和历史运费原记录不被覆盖；新表和归档文件按报价版本独立保存。代码可回退 squash 合并提交；迁移回滚必须在获授权维护窗口执行，归档文件不自动删除。生产迁移、真实 E 签宝配置和部署均不在本 PR 中执行。 ## 合并前复查 - [x] 已重新拉取远程引用并用实际修改范围再次运行碰撞检查 - [x] PR 不再是 `WIP:`，所有测试结果已经补齐 - [x] Codex 已重新读取原始需求和验收标准，并逐文件审核 `origin/main...任务分支` 的完整 diff - [x] Codex 自审确认无越界修改、重复实现、敏感内容、未处理冲突和未验证结果 - [x] 合并顺序不会覆盖其他未合并任务 - [x] 已授权当前任务的 Codex 执行 Squash merge、验证 `main` 并清理任务分支 - [x] 本次不执行生产迁移、数据修复、删除、覆盖配置或部署；如后续执行需另行取得高风险授权
limeng added 1 commit 2026-08-13 18:53:53 +08:00
limeng added 1 commit 2026-08-13 19:32:55 +08:00
limeng added 2 commits 2026-08-14 14:08:00 +08:00
limeng added 1 commit 2026-08-14 16:47:53 +08:00
limeng changed title from WIP: 报价变更工作流第一期 to WIP: 报价变更与 E 签宝签署闭环 2026-08-14 17:12:22 +08:00
limeng added 2 commits 2026-08-15 16:44:53 +08:00
limeng changed title from WIP: 报价变更与 E 签宝签署闭环 to 报价变更与 E 签宝签署闭环 2026-08-15 16:46:41 +08:00
limeng merged commit eb76dc4754 into main 2026-08-15 16:48:13 +08:00
limeng deleted branch feature/limeng-courier-quote-change-workflow 2026-08-15 16:48:14 +08:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aaron chenxi DoDo jj404877757 limeng qiuxiang renshen shanshi sumu wangshu yueyang yutu zhoushengchen WuYongJie
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: WuYongJie/CaiWuXiTong#47
No description provided.
Delete Branch "feature/limeng-courier-quote-change-workflow"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?