Files
order-notification-automation/README.md
T

169 lines
26 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.
# 订单通知自动化工作台
面向团队的 BPM 订单工作台,提供业务日历、异常待办与转交、连接管理和运行监管配置;保留 Chrome 已登录订单页导出本地 PDF 的能力。
**订单通知流程**:以 Excel 的15类为准,从真实 BPM 待办按流程和节点精确匹配订单,再按表单版本适配字段,导出并校验归档文件,按北京时间每天两个有效时段同类别汇总一封。收件人由分类规则维护,BPM 节点人工办理,惠州额外通知条件待确认。自动发信保持暂停,类别字段、目录、邮箱与预览须现场核验后才可启用。旧通用通知写入和调度已退役,历史记录保留查询。当前要求见[设计要求](docs/design-requirements.md)。
## 设计与部署入口
- [工具使用指南](docs/user-guide.md):简短上手流程、当前导航逐页功能介绍及页面截图。
- [开发交接(2026-10-19)](docs/HANDOFF.md):接续分支、当前进度、启动命令、验证边界及下一步建议。
- [设计要求(当前基准)](docs/design-requirements.md):功能范围、架构、数据存储、权限、验收和实施顺序。
- [模块重构方案(2026-10-19)](docs/superpowers/specs/2026-10-19-modular-refactor-design.md):代码职责、兼容约束及七项鲁棒性修复。
- [本轮重构验证](docs/modular-refactor-verification-2026-10-19.md):故障回归、全量结果和实机验证边界。
- [订单通知管理与分段横栏验收](docs/notification-navigation-verification-2026-10-19.md):新入口、独立路由、角色/手机及正式更新证据。
- [部署说明](docs/deployment.md):安装、HTTPS、状态目录及备份。
- [后续业务资料整理表](docs/business-configuration.md):SMB 参数、来源字段和产业接口人需要整理的信息。
- [扫描验证记录](docs/bpm-scan-verification-2026-10-16.md):最近验证及实际范围。
## Web 看板
侧栏七项:业务首页、订单中心、邮件批次、工具、异常待办、业务设置、系统设置。工具中包含流程到达记录、PDF 导出记录和 DSH 助手;系统设置维护服务连接、邮箱、助手权限、健康和审计。首页展示实际发送窗口、批次与异常,支持窄屏与减少动态效果。
1. 启动工具后,在部署机打开 http://127.0.0.1:18766 ,自行创建管理员账号(至少 12 位密码)。没有默认账号或默认密码。
2. 管理员在“团队账号”中创建同事账号;同事使用启动窗口打印的局域网地址访问。默认监听 0.0.0.0:18766,能否跨机器访问取决于路由和 Windows 防火墙;本工具不自动修改防火墙。
3. 业务日历支持月历、公司工作日/休息日/停发覆盖,采集与发送分别设置;可恢复每周默认规则,并预览发送时段。保存配置不会执行采集或发送。
4. 异常待办支持创建、认领、转交、提交验证、填写人工核验依据后关闭和重新打开;显示负责人和流转记录,防止多人同时覆盖。operator 可处理异常,viewer 只读,admin 可管理全部配置。
5. BPM 连接支持创建、账号托管、网页登录、检查保存、重启复用和停用。每个连接独立保存会话,由负责人或管理员操作。系统健康提供守护状态和按权限过滤的执行阻塞信息;旧监管草稿入口已退役。
6. 邮箱管理支持公司 SMTP / IMAP、模板邮件收取、预览确认和历史版本;模板按 Excel 类别显式关联,收件人在分类规则维护。只读 BPM 到达历史按日期分区,独立于通知执行;旧群组与通用通知记录仅供历史查询。
界面复用 [Tabler](https://tabler.io/admin-template) 免费开源版(@tabler/core 1.6.1),CSS/JS 全部在本机提供;MIT 原文见 licenses/Tabler-MIT.txt。青龙已有独立部署准备和 CLI,尚未接通业务,本次不启动它或复制其内部源码。
工作台账号、群组设置和原 PDF 记录保存在 `%LOCALAPPDATA%\OrderNotificationAutomation\dashboard\state.sqlite`;业务日历、异常、连接与监管草稿保存在同级 `workspace` 目录的 SQLite 数据库中。邮箱、模板版本、原邮件、收信游标和测试发送记录保存在 `mail\mail.sqlite`,密码、原邮件和完整正文附件加密保存。BPM 会话与托管账号加密保存在 `bpm-sessions/accounts.sqlite`,旧 `.enc` 会话按读取迁移;主密钥经 Windows 当前运行用户 DPAPI 保护。数据留在运行机本地磁盘,不放项目所在的 Z: 共享盘。备份前停止服务并保护整个本地状态目录。旧版 `dashboard\state.json` 会首次导入 SQLite 并原样保留为迁移备份;后续以 `state.sqlite` 为准。所有成员可从右上角“修改密码”维护个人密码(须验证当前密码,12–128位、两次输入一致且不得沿用原密码)。管理员可在“团队账号”验证自己的当前密码后重置其他成员密码;自己的密码使用个人入口修改。改密或重置会使该账号全部旧登录失效,关闭关联的临时BPM登录窗口,并写入不含密码的操作记录。改密成功后需重新登录,其他成员会话不受影响。
工作台登录有效期为 30 天,每日活动自动续期;令牌哈希保存在 `dashboard\auth.sqlite`,服务重启后继续有效,退出登录立即撤销。已保存的 BPM 会话在同一 Windows 运行账号下恢复。
## 邮箱与邮件模板
1. 管理员进入 **邮箱管理 → 添加邮箱**,默认使用一份邮箱地址与授权码。163/126/QQ 等有服务器预设;自定义服务器和独立收发凭据位于高级设置。SMTP 用于发信,IMAP 收信/历史查询可选;模板自动收信另有开关。
2. 填写 **允许提交模板的发件人**,保存后点击 **检查连接**。此操作验证 SMTP、IMAP 及 INBOX 访问,不发送邮件。确认正常后在管理邮箱中开启 **模板收信**,服务每分钟检查;也可点击 **立即收信**。
3. 从名单内的邮箱新建邮件发送到托管邮箱,主题为 `[模板][海外运营]订单通知 {{日期}}`;正文和附件作为对应产品线模板。`[模板]订单通知` 表示默认模板。回复/转发主题、范围标记不完整、未授权发件人和超出 10 MB 的邮件不导入。首次及邮箱 UID 变化只处理近 7 天邮件,保留该日期边界和 UID 游标;只读访问,不标记已读、不移动或删除邮件。
4. 打开 **模板与收件群组 → 预览并确认**,核对来源、发信标题、产品线、表格、图片和附件后点击 **确认生效**。可调整标题和产品线,或切换为纯文本编辑正文。旧版本留作历史;多人确认发生冲突时不覆盖新版本。名单控制导入,管理员确认后才生效。
5. 支持明确变量 `{{产品线}}`、`{{订单号}}`、`{{日期}}`、`{{订单列表}}`,不执行模板表达式。HTML 预览隔离,阻断脚本及外链图片;保留原 EML,管理员可下载原邮件与附件。邮件中的 To/Cc 不会修改业务收件群组。
6. 已生效模板可点击 **发送测试到隔离邮箱**,固定发送至 `2639266652@qq.com`,空 Cc、无附件。发送前和 SMTP 验证后复查测试期限与模板版本;结果不明禁止重复发送。分类业务通知使用规则绑定模板,PDF 仅归档,不作为附件。
旧模板草稿首次启动迁为待确认版本,确认时选择实际托管邮箱。邮箱维护须从部署机回环地址或已配置的 HTTPS 反向代理访问;与 BPM 登录使用同一传输要求。密码留空保留原值,更换邮箱、登录账号或服务器时须重新录入。后台持续检查不要求一直打开网页。
复用 [Nodemailer](https://nodemailer.com/) 10.2.1、[ImapFlow](https://imapflow.com/) 2.4.3、[MailParser](https://nodemailer.com/extras/mailparser/) 3.12.4 和 [sanitize-html](https://github.com/apostrophecms/sanitize-html) 2.18.1,版本已锁定。公司邮箱真实连接需管理员录入参数后检查。
## 存储服务器与业务通知
- **存储服务器**:管理员可先填写服务器 IP / 主机名,点击“浏览”列出共享并逐层选择目录,也可粘贴完整 Windows 共享路径(例如 `\\210服务器\订单\归档`),自动识别主机、共享和子目录;名称可留空自动生成。默认“免填账号密码(使用 Windows 权限)”,直接复用部署机现有 SMB 会话或运行服务账号的共享访问权限,适用于已获授权和系统允许的免密共享。需要独立凭据时选择“指定账号”;无密码账号勾选“此账号无密码”。密码加密保存在部署机,编辑留空保留原密码;更换主机、共享或账号需重新录入。旧配置按指定账号方式继续使用。添加前先点击“检查连接”,能读取目录后才能保存;修改连接或重新启用时需重新检查,保存接口会再次确认可读取。服务器入口只用于选择共享,不会直接保存为文件目录。草稿检查不保存配置、不创建文件;检查/目录选择使用独立进程,15 秒超时并提供“取消操作”,取消后终止工作进程,避免网络目录等待占住工作台;“检查读写”用于归档前的写权限验证,会创建、读取并清理随机探测文件。配置维护要求部署机回环地址或可信 HTTPS。
- **免填模式说明**:使用服务部署机上的权限及既有 SMB 会话,不是网页访问者电脑的身份。切换模式会清除托管凭据、重置检查状态并暂停该服务器的自动归档,但不会强制断开 Windows 已有共享会话;若已有其他账号连接,实际访问可能继续使用该会话,需由部署机管理员处理。服务器要求认证或 Windows 禁止来宾/空密码访问时仍可能被拒绝,本工具不自动更改这些系统设置。
- **文件管理**:管理员与操作员可浏览归档目录、创建子目录、下载文件和内嵌预览,将已有成功导出的 PDF 归档。归档读取 BPM 表单订单号,使用明确的完整 6/7 位订单号建立同名子目录,保留前导零;已有订单目录直接复用,在同名订单目录内手动归档也不会重复嵌套。订单号缺失、冲突、含后缀或长度尚不明确时记录失败,不自动截取,也不从 PDF 文件名推断。目标存在相同内容时幂等完成;不同内容保留新文件,原件不覆盖。只读成员查看服务器和归档记录。启用自动归档后仅处理新导出的 PDF,历史文件由人选择归档;失败记录可通过重新选择同一任务重试。
- **文件预览**:在已托管服务器的目录中点击“预览”,支持 PDF、PNG/JPEG/GIF/WebP/BMP、文本(含 UTF-8、UTF-16 与 GB18030)、DOCX 和 XLSX。支持全屏、图片缩放与工作表切换;文本仅按原文显示。单文件预览及下载上限 64 MiB,文本预览上限 2 MiB;Office 展开内容最多 64 MiB、4096 个条目,Excel 每张表最多预览前 500 行、50 列。旧 DOC/XLS 与其他未支持格式可下载原文件。Office 预览以内容阅读为主,不保证与桌面 Office 排版完全一致,Excel 数值按原始值展示,不执行宏或重新计算公式。PDF 已关闭公网补充字体,缺少内嵌字体的文档可能出现字体替代。
- **开源预览组件**:适配 [OpenList Frontend](https://github.com/OpenListTeam/OpenList-Frontend/tree/v4.2.7) 的 DOCX/XLSX 预览思路,采用 EmbedPDF、docx-preview、ExcelJS 与 PhotoSwipe;脚本和 PDFium WASM 由本机提供,界面使用系统字体,不调用公网 Office 在线服务。文件经现有登录权限读取,在独立沙箱中渲染。选型及许可见 [预览选型记录](docs/storage-preview-open-source-research-2026-10-17.md) 和 [第三方许可](licenses/storage-preview-NOTICES.md)。
- **Windows SMB**:使用原生协议,不映射盘符、不强行断开已有共享连接。同一主机已有其他账号连接而产生 1219 冲突时,由部署机管理员处理。共享及所配置归档根目录需已存在并授予读写权限。PDF 上限 64 MiB,单层浏览最多 500 项。
- **业务通知**:配置来源名称、JSON 字段路径、托管发件邮箱及尝试上限,产业接口人维护在现有“模板与收件群组”。通知 ID、产业、简要说明必填;正文复制简要说明原文,**不附带 PDF,也不因 PDF 存档而触发邮件**。可粘贴样本预览字段及收件人,预览不入队、不发信。
- **自动发送**:默认暂停。开启前需要 SMTP 检查通过及产业收件组;开启后每 30 秒检查既有的两个北京时间时段及业务日历,逐项或按产业汇总。错过时段保留待发数据至下个正常时段;空队列不发信。SMTP 检查失败受尝试次数限制,发送结果不明确或部分收件人未接受则停在“待核实”,管理员填写核验依据后才能确认成功或重新入队。
- **后续业务配置**:标准来源事件通过已认证同源 `POST /api/notifications/events` 提交 `{ "data": { ...来源对象... } }`;`/api/notifications/preview` 使用相同结构进行预览。当前没有把 BPM 全部待阅记录直接转成通知;同事整理实际字段与产业映射后,再接入来源适配器。不能将当前通用模块视为已完成 BPM、SMB 实机及公司邮件端到端联调。
存储配置及记录位于本机 `storage/storage.sqlite`;通知配置、加密队列正文和发送批次位于 `notifications/notifications.sqlite`。与其他状态目录一起停服备份,不提交至 Git。
## 服务守护与系统健康
左侧菜单底部显示当前版本,登录后自动检查一次更新,也可点击“检查更新”。有新版本时显示更新标记,并可查看发布日期、说明及远端发行页面。尚无 Release、已是最新版本和检查暂不可用会分别显示;检查失败不会阻塞业务。当前功能提供更新提示,由部署管理员根据发行说明安排更新。发行流程见[版本发布与更新检查](docs/system-updates.md)。
双击 **启动工具.cmd** 或运行 `npm start`,工作台由独立守护程序在后台运行;启动窗口关闭后服务继续运行,重复启动会复用现有实例。打开 **系统健康**(`/#health`)查看本次启动时间、连续运行时长、守护心跳、恢复次数、最近事件及 Windows 登录自启状态。
守护通过两个本机端口的私有心跳确认业务进程身份。启动宽限 120 秒,之后每 10 秒检查,连续 4 次失败才终止本工具启动的进程树并恢复。退出重试采用 2/5/10/30/60 秒退避,15 分钟内达到 8 次恢复尝试后冷却 5 分钟,避免反复启动。人工停止不会触发恢复,不会结束未知的占用端口进程。自动恢复仍遵守原有任务规则,邮件结果不明时保留待核实状态。
| 命令 | 用途 |
|---|---|
| `npm start` | 后台启动并等待两个端口就绪 |
| `npm run service:status` | 查询守护实际响应和持久状态 |
| `npm run service:restart` | 正常停止业务进程,再启动并检查心跳 |
| `npm run service:stop` | 停止业务服务及守护;保留登录自启设置 |
| `npm run service:install` | 安装当前 Windows 用户登录自启动 |
| `npm run service:uninstall` | 移除登录自启;保留业务状态与日志 |
| `npm run start:foreground` | 排错时直接前台启动,不经过守护 |
自启动在当前 Windows 用户登录后后台执行,沿用该账号的 DPAPI 和 SMB 权限,无须保存 Windows 登录密码。启动目录使用专用快捷方式,不覆盖其他程序的同名入口。它不是未登录即可运行的系统服务;电脑仍需开机并能访问业务网络。
模块卡片展示 **已保存的上次检查结果**,分开显示未配置、待检查、已暂停、失败与正常;只读采集不会新建 BPM 登录、SMB 探测文件或发送邮件。最近观测到的成功/失败时间保存在本机 `health/health.sqlite`,BPM 明细按负责人权限过滤。页面每 10 秒刷新,服务暂不可达时保留上次数据并提示,恢复后自动更新。
守护控制、事件和安装记录保存在本机 `supervisor/supervisor.sqlite`;当前用户 ACL 保护 `control.key` 与日志,管理令牌不发送到 HTTP,业务心跳每次启动使用独立随机令牌。`supervisor/service.log` 达 5 MiB 时轮转,保留 3 份历史。停服备份整个本机状态目录,勿将控制密钥或运行状态提交到 Git。实现与验证见 [服务守护设计](docs/superpowers/specs/2026-10-18-service-health-design.md)。
## DSH 受控助手
在 **工具 → DSH 助手** 查询授权范围内的订单、批次和运行状态。管理员在 **系统设置 → 助手设置** 配置模型。
1. 运行 `node scripts/install-dsh-runtime.cjs` 安装固定官方 DeepSeek Harness 运行包;`--check` 仅检查。运行包独立安装在 LocalAppData,项目依赖不变。
2. 使用 Messages 兼容 API 根地址(官方默认 `https://api.deepseek.com/anthropic`)、实际模型名称和密钥。密钥加密保存、不回传;未配置密钥时助手停用。检查运行包不代表真实模型认证成功。
3. 固定操作卡片按工作台权限执行,用户点击后重新核验目标。管理员可另行开放代码修复:明确选择已跟踪文件,先审查建议,再在独立 Git 工作区运行固定测试。通过后待人工审查,失败恢复基线并保留提交;结果不明停止并待核验,不自动合并或部署。
4. AI 操作记录只追加保存步骤、提交、测试与恢复结果,支持按账号查询历史。原生文件、Shell、网络、MCP 工具不注册;代码验证以本机服务身份运行,Git 工作区不等同操作系统沙箱。
已用官方 DSH + 本地假模型验证协议与空工具列表,真实模型密钥尚未配置。来源、设计与边界见 [受控助手设计](docs/superpowers/specs/2026-10-27-mail-dsh-controlled-optimization-design.md)。
## BPM 登录
### 自动扫描与流程到达记录
在 **订单与导出记录 → 流程到达记录** 查看,每个到达日期单独一个分区,按北京时间倒序展示,可按连接及关键字查询、折叠日期、加载更早日期。PDF 导出记录保留在同页另一标签。
默认每 5 分钟通过新版门户列表 API 扫描已连接账号,遵循业务日历的“采集”开关。管理员可在“扫描设置”调整间隔、暂停或开启;管理员和连接负责人可“立即扫描”,手动扫描不受日历限制。当前待阅列表作为临时采集来源,保留真实流程名,后续按业务表格配置流程范围,不标记已阅或审批。
按接口的“收到时间”划分日期,不使用扫描时间、发起日期或流水号日期。正常扫描直接复用服务端 Cookie,认证失效时调用现有续登。全部分页读取成功才提交;按连接、来源、任务标识去重,历史记录保留。记录、扫描设置及最近运行结果保存在本机 `bpm-scan\scan.sqlite`,不随网页关闭或服务重启丢失。
1. 在正式工作台打开 **BPM 连接**,创建连接并指定负责人。
2. 点击 **开启自动续登**,录入 BPM 账号和托管密码,点击 **保存账号**。账号输入完成后检查是否已托管,保存时以数据库唯一约束再次检查;忽略首尾空格和大小写,同一账号只能在一条连接中开启。保存后自动检查现有会话,Cookie 有效时直接复用;确认失效后,使用已托管账号在已识别的新 SSO 表单自动续登。开启后可从 **管理账号** 更新密码或 **关闭自动续登**;关闭自动续登保留有效 Cookie。
3. 只有需要验证码或额外验证时,点击 **远程登录**,在页面显示的 BPM 画面中完成验证。有托管账号会自动填入对应入口,也可点击 **填入托管账号**;不复制其他浏览器的 Cookie。
4. 完成新版门户登录后点击 **检查并保存**。新版账号验证通过即显示“已连接”;只维护新版 BPM,不提供旧版入口或检查。
5. 服务启动及每 5 分钟自动恢复检查并保存有效的刷新 Cookie,无须一直打开工作台。错误密码自动重试间隔至少 15 分钟,网络故障不触发密码提交,正在人工登录的连接暂不接管。需要人工处理时建立去重待办;重复失败合并为同一未关闭待办。BPM 服务端的强制到期或注销不能靠修改本地 Cookie 期限延长,届时由自动续登恢复,验证码仍需人工完成。
6. 管理员可先 **停用连接**,再点击已停用卡片上的 **删除**。确认后清理该连接的托管账号和已保存 Cookie,并移除连接;历史审计保留。正在使用的连接需要先停用。
7. 关闭登录画面会释放操作权,其他负责人可继续操作;停用连接会关闭对应浏览器并清除保存的会话与托管账号。每个连接同时只允许一个工作台会话操作。
部署机可直接通过 `http://127.0.0.1:18766` 操作登录。其他电脑操作 BPM 登录须使用 HTTPS 工作台:可使用公司已有反向代理,代理在部署机本地连接 `127.0.0.1:18766` 并设置 `X-Forwarded-Proto: https`,再在 `config.json` 设置 `dashboard.trustedProxy: true`。仅信任本机代理;远端直接传入此头不会启用登录。代理需保留公开 Host,工作台的同源检查会比对该 Host 与 Origin。示例见 `deploy/bpm-login.Caddyfile`。
托管账号登记在 `%LOCALAPPDATA%\OrderNotificationAutomation\bpm-sessions\accounts.sqlite`。账号和密码以 AES-GCM 加密后写入数据库,账号唯一键使用带密钥的摘要,主密钥由 Windows 当前服务账号 DPAPI 保护;账号接口只返回用户名和更新时间,已保存密码不回传。服务启动先将原加密账号文件事务迁移到数据库,迁移成功再移除原条目;发现旧账号重复则回滚并保留源文件,避免覆盖。远程画面输入不会另行记录,也不保存截图文件。状态检查只访问新版门户,不执行已阅、审批、知会或通知操作。
## PDF 扩展首次使用
1. 双击本目录的 **启动工具.cmd**,或运行 `npm start`。服务在后台守护运行,无须保持启动窗口打开。本机已有 Node.js、Chrome 和依赖,可直接启动。换电脑使用时,安装 Node.js 22.13+(建议 Node.js 24)和 Chrome,然后在项目目录运行 `npm install`。框架使用 Node 内置 SQLite,部分 Node 版本会打印实验性 API 提示。
2. 在 Chrome 地址栏打开 `chrome://extensions`,启用“开发者模式”,点击“加载已解压的扩展程序”。
3. 选择服务窗口给出的本机目录:`%LOCALAPPDATA%\OrderNotificationAutomation\extension`。**不要选择项目内的 extension 源码目录**:启动时会把源码和本机配对配置一起准备到上述目录。
4. 在 Chrome 扩展菜单中固定“订单通知书 PDF”。在你已登录的 BPM 中打开订单详情,点击扩展,再点击 **导出当前订单**。
5. 面板显示保存位置后,在本目录 `output\pdf` 查看结果。导出在后台继续,关闭面板不会取消;可再次点击扩展查看结果。
Chrome 加载扩展只需做一次。修改扩展源码、重新配对或变更端口后,先重启本地工具,再到扩展管理页点击刷新。
内置浏览器无法安装这份 Chrome 扩展。使用独立工具时,在原有 Chrome 的已登录页面操作;若该 Chrome 尚未登录,需要在该 Chrome 中登录一次。工具不复制其他浏览器的登录状态。
## 命名和重复导出
规则:`订单号_项目编号_产品型号_通知书编号.pdf`。
虚构示例:`900001_DEMO-PROJECT-001_DEMO-MODEL_DEMO-CHANGE-001.pdf`。
四项来自表单 `xdatabind`:`OrderNum`、`ProductNum`、`ProductModelNEW`、`SN`,不依赖示例订单值。缺少任一项时停止并提示;非法文件名字符替换为下划线。同名文件追加 ` (2)`、` (3)`,不覆盖旧文件。
## 设置
复制 `config.example.json` 为 `config.json`,可更改 `outputDir`、本地服务 `port`、PDF 缩放 `scale`。默认 A4 纵向,缩放 0.59,与本次验证样稿采用相同参数。`outputDir` 可以是相对项目路径,也可以是 Windows 绝对路径。
扩展桥接服务仅监听 `127.0.0.1:18765`;Web 看板默认监听 `0.0.0.0:18766`,可用 `dashboard.host` 改为 `127.0.0.1`。配对密钥只用于本机扩展和本机程序通信,不是 BPM 登录凭据。不要分享 `%LOCALAPPDATA%\OrderNotificationAutomation` 中的配对配置。
## 能力范围
- 扩展直接读取当前浏览器页的显示值、CSS 和图片,复用该 Chrome 的登录状态;不启动远程调试端口。
- 本地程序使用隔离的无界面 Chrome 排版,禁用页面脚本和网络;保存后关闭该排版进程,不影响你正在使用的 Chrome。
- 不导出密码、隐藏控件、ViewState、讨论输入和操作按钮,不提交或修改 BPM 订单。
- **输出是页面导出样稿,不是服务器原版 PDF,也不保证与 XForm 原生打印完全一致。** 不支持的图片、资源读取失败会在扩展中提示。网页内的附件只显示名称,不会自动合并附件。
- 本版包含按规则匹配、只读采集、PDF/SMB归档、分类模板与计划批次、确认未发送订单顺延、受控DSH助手和业务台账。历史表单及隔离回放通过不等于十五类真实通知与实收全部验收完成;正式服务机部署另行安排。
## 故障处理
- 无法连接本地工具:确认启动窗口仍在运行;端口或配对变更后刷新扩展。
- 端口占用:先运行 `npm run service:status` 确认状态;需要停止本工具时运行 `npm run service:stop`。未知程序占用端口时工具不会接管,可在 `config.json` 修改端口,再启动并刷新扩展。
- 缺少字段:进入“海外运营订单更改评审 V7”实际订单详情;其他表单的绑定不同,需要增加映射。
- 缺少排版依赖:在项目目录运行 `npm install`。
- 启动入口直接运行 Node,不需要 PowerShell 脚本,也不修改系统执行策略。
## 开发和验证
`npm test` 运行命名、重名保留、真实 PDF、可见字段采集和回环 API 访问控制测试。运行时优先使用本项目安装的 `playwright-core`,本机也兼容 Codex 提供的依赖目录;Chrome 路径可用 `ORDER_CHROME_PATH` 指定。
运行本地快照回归:`node scripts/export-snapshot.cjs --snapshot <snapshot.json> --assets <assets.json>`。该入口仅用于已有离线快照;日常使用扩展按钮。
验证记录见 `docs/verification.md`。浏览器扩展需要在 Chrome 中加载后才能完成真实会话的整体验证。