10 KiB
小程序合同打印 Implementation Plan
使用 subagent-driven-development 实施,并分别检查需求符合度和代码质量。
Goal: 从 Web 复制合同打印功能,接入小程序 H5,保持 Web 调用链不变。
Architecture: 移动端独立组件和编辑器副本;现有模板 API;新增移动文件交付适配和原生文档页。
Tech Stack: Vue 3、TinyMCE、html2canvas、jsPDF、HTML→DOCX、uni-app。
任务
- 1. 先添加文件交付、入口隔离和组件生命周期的回归测试,执行并确认缺失功能失败。
- 2. 在
web-admin/src/views/m/crm/contract/print/复制打印模板、保存和导出代码,复制 TinyMCE 到MobileContractEditor.vue,保留源文件不动。公开open(id),载入失败显示错误,重开重置状态,关闭防止旧请求回写。 - 3. 接入
web-admin/src/views/m/crm/contract/detail.vue,沿用captureOperation和操作列表,懒加载打印组件,切换合同销毁旧实例。 - 4. 实现
deliverContractFile(blob, fileName):浏览器下载;微信中调用fetchUploadAttachment,取得下载 URL,通过wx.miniProgram.navigateTo进入新文档页。失败抛错交由组件提示,不修改合同附件集合。 - 5. 新建
miniprogram/pages/common/contract-document.vue和下载辅助函数;注册页面。校验资源地址,下载成功后uni.openDocument({ filePath, fileType, showMenu: true }),支持重试和返回;不发送 Bearer 到资源域名。 - 6. 执行定向测试、Vue 编译/构建、移动浏览器验证。检查
git diff保证 Web 原打印和编辑器无变更,记录真机限制和结果。
UI 参考:现有移动合同详情全屏面板,以及 Web P10 查看弹窗中的合同打印编辑区。功能与隔离方案已在聊天中获用户确认,不重复请求确认。
执行与验证记录
- 代码在当前 V3.0 工作区内完成,保留用户既有未提交文件;未提交或发布。
pnpm exec tsx --test scripts/mobile-contract-seal-drag.test.ts scripts/mobile-contract-detail-review.test.ts scripts/mobile-contract-review.test.ts scripts/mobile-contract-picker.test.ts scripts/mobile-crm-detail-navigation.test.ts src/utils/crm/contract-pdf-pages.test.ts src/utils/crm/contract-table-layout.test.ts src/utils/crm/contract-product-table-widths.test.ts src/utils/crm/contract-docx-column-widths.test.ts src/utils/crm/contract-html-to-docx.test.ts src/utils/tinymce-table-edge-resize.test.ts:80 项通过。node --test miniprogram/scripts/test-contract-document.mjs:5 项通过,包括首页注册顺序保持不变。- Web 目录
node scripts/test-mobile-contract-print.mjs:Chrome 模拟触摸,375/414 全屏、模板编辑保存/关闭重开、默认模板、红章切换、真实 DOCX/PDF 下载、模拟微信上传失败重试和原生页跳转均通过。开发页面和vite preview构建产物均通过;补测非 SX 合同快速关闭。全部 API 为 fixture,不写真实业务数据。 pnpm build:通过;保留已有组件重名及大 chunk 警告。vue-tsc --noEmit:全仓历史错误未消除;与改动前基线比较无新增诊断,移动打印新增文件无诊断。不能称全仓类型检查通过。- Web 原
ContractDetailDialog.vue、TinyMceEditor/index.vue和共享导出工具无修改;git diff --check通过。
发布与真机验收
新增了小程序原生页面,需重新编译/上传小程序,单独更新 H5 不足以启用文档打开。保持现有环境配置;正式环境需确认当前 MinIO 主机(配置为 res.shanxiachem.com)已加入小程序 downloadFile 合法域名。尚未执行 HBuilderX 编译、iOS/Android 微信真机验收或生产部署。真机重点验收键盘/触摸选区、盖章移动、长合同导出及文件转发;超过移动截图16MP上限会给出使用电脑端导出的提示并保留内容。
真机空白反馈后的初始化修复
用户反馈 iOS 27.2 正式微信环境编辑区空白、导出报 serializer.serialize 未定义。正式域名核心/主题/模型/图标/样式/语言/表格资源均返回 200,字节与本地 TinyMCE 6.8.6 一致。能确认初始化前读取内容缺少保护;尚未直接调试该设备,不能断言真实设备空白的唯一根因。
移动专用编辑器启用 TinyMCE 官方 init_content_sync,绕过 srcdoc 异步 load 依赖;仅 init 完成且 serializer 可用后允许读取、保存或导出。增加加载状态、资源失败重试和20秒超时提示;核心脚本由副本管理加载错误,普通模型/主题失败重试仅清理未注册项。持续挂起的共享加载队列无法通过重建组件释放,超时采用明确的「重新加载页面」,使用详情已有 action=print 恢复当前合同。原 Web 组件和公共 TinyMCE 静态资源不变。
新增回归模式(均使用 fixture,不写真实业务数据):
CONTRACT_TEST_IOS=1 CONTRACT_TEST_WECHAT_UA=1 CONTRACT_TEST_BLOCK_SRCDOC=1 node scripts/test-mobile-contract-print.mjs:屏蔽 iframe srcdoc 初始化,修复前初始化超时,修复后通过编辑/保存/Word/PDF 全流程。CONTRACT_TEST_SLOW_EDITOR=1 node scripts/test-mobile-contract-print.mjs:模型未完成加载时保存/导出禁用、关闭可用;释放后可操作。修复前断言失败,修复后通过。CONTRACT_TEST_IOS=1 CONTRACT_TEST_RETRY_EDITOR=1 node scripts/test-mobile-contract-print.mjs:模型首次503,重试后通过。CONTRACT_TEST_IOS=1 CONTRACT_TEST_RETRY_EDITOR=core node scripts/test-mobile-contract-print.mjs:核心脚本首次503,重试后通过。CONTRACT_TEST_IOS=1 CONTRACT_TEST_SLOW_EDITOR=timeout node scripts/test-mobile-contract-print.mjs:首次模型持续挂起,超时刷新恢复合同并通过全流程。局部重试版本失败,页面恢复版本通过。- 定向原有回归51项通过;类型检查与原基线相比无新增诊断。
本机 WebKit 18.5/iPhone微信UA模拟不等价于用户 iOS 27.2 微信真机。未发布正式站点;H5更新后仍需用户原机复测。本次无需重新打包小程序原生页面。
真机提示成功但无文件去向的交付修复
用户确认点击 PDF 后始终停留编辑窗口,没有原生文档页或预览。此前所给165字节文件为其他档案接口的历史500 JSON,不能用作合同PDF样本。
确认移动交付器存在错误分支:同步环境标记/UA判定为false时立即调用FileSaver并返回,调用方无条件提示生成成功。微信桥接尚未就绪、UA无miniProgram时可以进入此分支。回归用iPhone微信UA、无同步标记、延迟getEnv=true复现;真实设备尚未连调,不能断言所有真机表现均由同一原因造成。
仅移动交付器增加JSSDK加载/桥接环境确认,微信环境不能确认时明确报错,不降级浏览器下载;环境确认8秒超时、原生页面跳转10秒超时。返回交付类型,界面分别提示文档页用途或浏览器下载记录,避免将浏览器下载请求等同于文件已保存。Word/PDF共用此逻辑。Web原打印、共享环境工具和小程序原生页面均未修改。
验证:
- 新增交付专项9项通过,覆盖延迟环境、SDK加载/超时、关闭窗口、普通浏览器、非小程序微信环境和原生跳转失败/无响应;修复前核心用例失败。
- 原移动合同与印章回归26项、小程序文档页5项通过。
- Chrome触摸及WebKit/iPhone微信UA的完整编辑/保存/Word/PDF/上传失败重试/原生跳转fixture回归通过;原生宿主由mock模拟,不等价于真机。
pnpm build通过,保留已有大chunk警告。
本次未部署。更新H5即可交付本轮修复;前提是已发布小程序包包含之前新增的pages/common/contract-document页。若该页尚未发布,仍需更新小程序包;失败提示会指明文档页打开失败。
- 本轮
vue-tsc --noEmit仍因仓库历史诊断退出2;与上一轮基线去除行列号后比较无新增诊断。不能称全仓类型检查通过。
代码复核未发现新的阻塞问题;补充按官方JSSDK顺序在bridge ready时注入环境标记的测试通过。getEnv本身仍读取该标记,因此永久缺失标记应明确报错,不能宣称已覆盖所有真机宿主异常。
文档页未出现:原生包同步确认
用户后续截图显示“已进入文档页”但仍停留H5,并确认只更新了H5。检查此前本机14:08的unpackage/dist/dev/mp-weixin/app.json确实没有pages/common/contract-document。页面只注册在源码,须随小程序原生包编译/上传/切换版本;H5更新不能增加原生页面。旧回调只代表跳转请求被接受,不应断言页面已呈现,移动提示已改为“已请求打开文档;若未跳转,请更新小程序后重试”,返回值改为mini-program-requested。
用户明确要求切换生产配置、由用户同步发布。已将原工程miniprogram/config/env.js的APP_ENV改为production;npm run release:check-api通过。HBuilderX launch mp-weixin --compile true编译成功,检查产物的环境为production且新文档页的js/json/wxml/wxss齐全,下载和打开接口已编译进入页面。交付9项、小程序文档5项测试通过。
publish mp-weixin --upload false被HBuilderX登录要求阻止,未产生发行包;以上成功编译为运行模式验证,不是正式发行包。用户需要登录HBuilderX后用“发行 → 小程序-微信”构建压缩包并上传。本轮未上传或发布小程序,也未部署H5;仍待真实设备验收。
原生文档页下载失败的排查
用户更新小程序后已进入合同文档页,出现下载fail通用提示。确认现有fail回调丢弃了微信errMsg,截图无法区分域名白名单、TLS、超时等原因。下载存储域名为res.shanxiachem.com;本机对该域名HTTPS检查成功,但这不能证明真机下载合法域名已配置或具体签名链接有效。已请求用户核对微信公众平台downloadFile合法域名配置,尚未拿到实际errMsg,不宣称根因已证实。
最小修正:原生文档页保留下载错误和错误码,识别域名拦截时明确指出待配置域名;隐藏错误中的文件URL避免展示临时签名。补充README中的MinIO下载域名要求。新增两项错误呈现回归先失败后通过,总计7项通过;HBuilderX运行模式编译及production配置检查通过。未上传或发布,若域名已配置仍报错,需要用更新后的原生包取得实际错误继续排查。