Files
order-notification-automation/README.md
T

168 lines
27 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 的能力。
**项目最终目标**:无人值守识别匹配订单、按模板整理、上传 210、按产品线群组每天两次自动发送邮件。当前实现团队工作台与 BPM Web 登录、会话保存,订单处理规则后续确定;BPM 知会不自动处理。已接入新版门户只读扫描、可配置 SMB 归档、通用通知队列、受控 ZCode 对话,以及服务守护和健康面板。实际 BPM 简要说明字段与产业接口人规则等待同事整理后配置。完整流程背景见 [无人值守系统设计](docs/unattended-system-design.md),登录实现见 [BPM 登录设计](docs/superpowers/specs/2026-10-16-bpm-login-design.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/deployment.md):安装、HTTPS、状态目录及备份。
- [后续业务资料整理表](docs/business-configuration.md):SMB 参数、来源字段和产业接口人需要整理的信息。
- [扫描验证记录](docs/bpm-scan-verification-2026-10-16.md):最近验证及实际范围。
## Web 看板
侧栏保留工作总览、订单与导出记录、异常待办、ZCode 助手、业务设置和系统设置六个入口。业务设置集中分类通知规则、发送计划、业务日历及模板与收件群组,兼容业务通知折叠在“兼容配置”中;系统设置集中 BPM、邮箱、存储、服务接入、运行监管、系统健康、团队账号和操作记录。团队账号仅管理员可见。设置子页面提供返回所属设置的入口,原页面链接仍然有效;个人修改密码保留在右上角。
1. 启动工具后,在部署机打开 http://127.0.0.1:18766 ,自行创建管理员账号(至少 12 位密码)。没有默认账号或默认密码。
2. 管理员在“团队账号”中创建同事账号;同事使用启动窗口打印的局域网地址访问。默认监听 0.0.0.0:18766,能否跨机器访问取决于路由和 Windows 防火墙;本工具不自动修改防火墙。
3. 业务日历支持月历、公司工作日/休息日/停发覆盖,采集与发送分别设置;可恢复每周默认规则,并预览发送时段。保存配置不会执行采集或发送。
4. 异常待办支持创建、认领、转交、提交验证、填写人工核验依据后关闭和重新打开;显示负责人和流转记录,防止多人同时覆盖。operator 可处理异常,viewer 只读,admin 可管理全部配置。
5. BPM 连接支持创建、账号托管、网页登录、检查保存、重启复用和停用。每个连接独立保存会话,由负责人或管理员操作。运行监管目前保存默认负责人、通知方式和重试上限草稿,不调用 ZCode、不执行恢复、不发送通知。
6. 邮箱管理支持公司 SMTP / IMAP、模板邮件收取、预览确认和历史版本;原 PDF 记录、每日两次时间、产品线群组、团队账号和操作记录继续可用。新版 BPM 扫描结果按流程到达日期分区;业务通知使用独立通用队列,默认暂停,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. 管理员进入 **邮箱管理 → 添加邮箱**,填写邮箱地址、SMTP / IMAP 服务器、端口、加密方式、登录账号和密码或授权码。支持 SSL/TLS 和必须升级加密的 STARTTLS,证书正常校验;不会猜测公司服务器参数。新邮箱默认暂停收信。
2. 填写 **允许提交模板的发件人**,保存后点击 **检查连接**。此操作验证 SMTP、IMAP 及 INBOX 访问,不发送邮件。确认正常后在管理邮箱中开启 **模板收信**,服务每分钟检查;也可点击 **立即收信**。
3. 从名单内的邮箱新建邮件发送到托管邮箱,主题为 `[模板][海外运营]订单通知 {{日期}}`;正文和附件作为对应产品线模板。`[模板]订单通知` 表示默认模板。回复/转发主题、范围标记不完整、未授权发件人和超出 10 MB 的邮件不导入。首次及邮箱 UID 变化只处理近 7 天邮件,保留该日期边界和 UID 游标;只读访问,不标记已读、不移动或删除邮件。
4. 打开 **模板与收件群组 → 预览并确认**,核对来源、发信标题、产品线、表格、图片和附件后点击 **确认生效**。可调整标题和产品线,或切换为纯文本编辑正文。旧版本留作历史;多人确认发生冲突时不覆盖新版本。名单控制导入,管理员确认后才生效。
5. 支持明确变量 `{{产品线}}`、`{{订单号}}`、`{{日期}}`、`{{订单列表}}`,不执行模板表达式。HTML 预览隔离,阻断脚本及外链图片;保留原 EML,管理员可下载原邮件与附件。邮件中的 To/Cc 不会修改业务收件群组。
6. 已生效模板可点击 **发送测试到本邮箱** 并确认目标。使用真实 SMTP 发送到托管邮箱自身,先记录发送任务,不自动重试不确定结果。此操作不会发给产品线群组。业务通知另在“业务通知”中配置来源映射,正文直接使用来源简要说明,不使用模板附件。
旧模板草稿首次启动迁为待确认版本,确认时选择实际托管邮箱。邮箱维护须从部署机回环地址或已配置的 HTTPS 反向代理访问;与 BPM 登录使用同一传输要求。密码留空保留原值,更换邮箱、登录账号或服务器时须重新录入。后台持续检查不要求一直打开网页。
复用 [Nodemailer](https://nodemailer.com/) 10.1.1、[ImapFlow](https://imapflow.com/) 2.4.3、[MailParser](https://nodemailer.com/extras/mailparser/) 3.9.39 和 [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。
## 服务守护与系统健康
双击 **启动工具.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)。
## ZCode 对话助手
工作台左侧 **ZCode 助手** 提供个人会话、连续追问、诊断依据、停止回复与操作结果。交互参考 [Open WebUI](https://github.com/open-webui/open-webui),界面在本项目内实现,共用工作台账号。
1. 本机已安装并校验官方 [ZCode v3.14.3](https://github.com/zai-org/ZCode/releases/tag/v3.14.3) 运行包,其附带 CLI 的实际版本为 **0.16.9**。换机时安装 7-Zip,运行 `node scripts/setup-zcode.cjs`:从官方 release 获取固定安装包、核对 SHA-256 后解包,不执行桌面安装程序。运行包存于 `%LOCALAPPDATA%\OrderNotificationAutomation\zcode-runtime`,服务启动时核对清单及 CLI 文件摘要并自动识别。
2. 管理员在 **ZCode 接入设置** 填写供应商的 OpenAI 兼容 API 根地址(例如含 `/v1` 的地址)、模型名和密钥,再启用并保存。仅本机或可信 HTTPS 可维护。密钥加密保存、不回传;留空保留,更换地址或模型须重新填写。**检查运行包** 仅验证本地入口,真实模型认证在发送对话时验证。
3. 默认只诊断。可单独开放固定操作卡片:检查启用的存储连接(管理员)、扫描授权 BPM 连接、重试失败归档。模型不能直接执行,必须由用户点击,服务器再次校验权限与目标,记录单次执行结果。暂停助手后旧卡片同样不可执行。
助手仅发送允许范围内的运行状态与异常摘要,不读取凭据、完整 BPM 表单、邮件正文或服务器文件内容。固定 CLI 的原生工具全部禁用,插件、MCP、技能、子代理、记忆和 hooks 关闭;每轮使用独立临时配置及过滤环境。模型输出只接受规定 JSON,不能执行任意命令、URL、路径,不审批、不发邮件、不改配置。限制属于已核对版本的应用控制,不是操作系统沙箱。
消息与模型配置加密保存在本机 `assistant/assistant.sqlite`。个人会话互相隔离,每会话最多 100 轮、每用户最多 50 个会话;全服务最多 2 个同时回复,支持 15–180 秒超时和每日轮次上限。上限统计对话轮次,运行包自身可能在一轮内重试模型请求。重启会标记未完成任务为中断,不自动重复执行。
当前已用**官方 CLI + 本机测试模型接口** 验证对话协议、模型参数和禁用工具;尚未配置或验证真实供应商模型认证。没有后台自主监管循环。来源、版本与限制见 [接入记录](docs/zcode-integration-2026-10-18.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 导出、团队协作、BPM 托管、SMTP / IMAP 邮箱与模板审核及明确操作的测试发信。支持 SMB 服务器配置、PDF 归档、通用通知队列与受控 ZCode 对话;BPM 业务匹配与简要说明自动入队、后台自主监管仍待接入;不会自动处理知会或修改 BPM 审批。
## 故障处理
- 无法连接本地工具:确认启动窗口仍在运行;端口或配对变更后刷新扩展。
- 端口占用:先运行 `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 中加载后才能完成真实会话的整体验证。