18 KiB
订单通知自动化:设计要求
2026-10-26确认:发送前五分钟截止收集。11:00只纳入10:55前到达任务,10:55起归17:00;16:55起归下一有效工作日首批。相邻到达区间含起点、不含终点,无空档。原接收时间及模板业务日期保持;新窗口保存独立收集边界,旧冻结/已发/未知结果不重写或重发。
模板 {{日期}} 使用订单原始 event.receivedAt 的北京时间日期;跨日按订单出现顺序去重,不能改用批次截止、纳入或创建日期。只有引用该变量的模板要求该时间完整;缺失阻断新冻结,不重写旧批次。
更新日期:2026-10-23。本文为当前设计要求入口;历史调研、旧根目录 pipeline 和阶段计划仅供追溯。业务规则调整须同步本文、实现与验收记录。
2026-10-23 当前权威边界
- 唯一来源为
source/订单通知书邮件发送信息.xls的原始 15 类。匹配必须使用 Excel 中的精确流程与精确节点;不接受“生效”别名,BOM 节点排除。海外 4 个流程均只允许订单专员(订单通知书)节点。 - 处理单位为
source + portalSource + taskId。业务修订字段缺失时保持缺失,不补revision=0。旧 ID、冻结回执、已知sent和unknown结果保留且禁止自动重演。 - 适配器必须区分
listVersion与formVersion;表单路径只能作为已核验适配证据,不能替代当前通知节点证据。原始brief与字段证据持久化;邮件展示层按订单号一单一行,保留模板问候、说明和签名。 - PDF 归档是通知前置条件;邮件固定 To
2639266652@qq.com、Cc 为空、附件为空。11:00/17:00(北京时间)按类别、绑定模板、窗口分别冻结;空批次不发,错过窗口不即时追赶或回填。 - 产品线和模板 ID 由类别配置显式指定,Excel 不提供这些字段;测试产品线暂用 rule.name,并明确标为测试标签。固定 QQ、空 Cc、Desktop 目录是受控测试覆盖值,不是原 Excel 的正式目的地;正式原始目的地不提交 Git。
- 不自动回填历史窗口:仅有提供器证明且已纳入不可变清单的待办,可保留到下一合法 11:00/17:00 窗口;非纳入历史任务保持 missedWindow 人工核验。已冻结 prepared 批次只有 30 分钟发送宽限,超时不得自动发送。
- BPM 只读,不已阅、不审批、不保存;受控测试仅归档到本机 Desktop 测试目录,正式存储权限验收另记。
- 服务端历史待办只有在新鲜提供器扫描、精确流程/节点命中后才能纳入不可变允许清单;保存
admittedAt,原始receivedAt不改;冻结与发送前都必须复核当前存在和内容新鲜。 - 当前原生入口只有
OrderExecutionCoordinator与OrderRuleDispatcher。旧根目录 pipeline 未启动;本机已完成原生代码切换,正式服务机未更新。
当前本机已更新为Excel规则执行桥版本,原数据与输出路径保留,正式服务机未更新。本轮核心回归29项全部通过,约74秒;此前基础整合全量990项为历史验收记录,并非本轮全量结果。13:03/13:09的17条待办快照均未匹配,不代表当天没有应通知任务。当天邮件反查已确认两笔试产类订单在11:24/11:25办理Excel确切通知节点,另有一笔海外返工节点名称与Excel不同,用户已选择继续按Excel保持阻断。当前只扫描待办,尚无已办通知任务补偿读取;历史步骤只提供完成时间而缺少通知任务ID/到达时间,不能伪造执行事件或自动补发。仍按Excel分类分批,不照抄人工邮件的跨类合并。PDF及归档运行能力待首笔合格任务实检,计划意图已启用,页面仍显示受阻。15类真实闭环未验收,零售国内返工订单更改评审仍缺适配器。详细证据和待确认项以本轮整合验证为准。
1. 产品目标与运行方式
团队成员在各自电脑访问同一台常驻服务器,通过 Web 管理 BPM 连接、流程到达记录、业务日历、异常、邮件模板和收件群组。正式工作台使用真实持久数据,不预置演示账号或虚构订单,不提供默认管理员密码。
目标业务按两条链路组织:PDF 提取生成后归档到可配置 SMB 服务器;业务通知将 BPM 简要说明原文按 Excel 类别发送。当前使用 11:00/17:00 北京时间窗口,PDF 归档是通知前置条件但不作为附件;15 类精确流程/节点以唯一 Excel 源文件为准,模板由类别显式配置。
当前阶段优先完成原生协调器/调度器的合并与验证;未切换部署前不启用自动处理或发信。不将知会或 BOM 候选等同于可处理订单,不自动已阅、审批或发送。
2. 功能范围与现状
| 模块 | 当前实现 | 后续要求 |
|---|---|---|
| 团队工作台 | 首次创建管理员、团队账号、角色权限、持久登录、审计 | 常驻部署与异机 HTTPS 验收 |
| BPM 连接 | 新版门户、远程交互登录、加密会话、账号托管与续登、唯一性、停用后删除 | 按上游认证变化维护适配 |
| 流程扫描 | 新版列表 API、分页、去重、定时和手动扫描、按到达日分区 | 按用户业务表格配置范围及字段映射 |
| 业务日历 | 周规则、工作日/休息日覆盖、采集与发送独立开关 | 接入正式发送调度 |
| 异常待办 | 创建、认领、转交、提交核验、关闭、重开及流转记录 | 业务执行失败自动建单与通知接口人 |
| 邮箱渠道 | 公司 SMTP/IMAP、加密凭据、连接检查、定时收信 | 公司真实邮箱连通性验收 |
| 邮件模板 | 模板邮件解析、预览确认、版本、HTML/CID/附件、自发测试 | 接入正式订单数据渲染与发送批次 |
| Chrome 扩展手动采集、离线生成、四字段命名、重名保留 | 按业务表单适配无人值守详情与导出 | |
| SMB 存储服务器 | 独立凭据加密、地址管理、读写检查、目录浏览、PDF 手动与新文件自动归档 | 录入服务器与权限,完成实机验收 |
| 自动业务邮件 | 通用来源字段映射、样本预览、持久队列、两时段调度、去重与人工核验 | 核实 BPM 简要说明来源和产业接口人映射后接通来源 |
| ZCode 助手 | 个人对话、加密历史、固定操作卡片、权限/工具约束,官方 CLI 与本机测试模型联调 | 配置并验证真实供应商模型,后台自主监管未实现 |
| 服务守护与健康 | 独立进程、双端口心跳、异常恢复、退避冷却、Windows 登录自启、历史健康面板 | 异机部署与备份恢复演练 |
| 青龙 | 保留部署准备及 CLI | 暂停部署,不作为当前服务启动依赖 |
3. 架构与模块职责
flowchart LR
U[团队浏览器] --> W[Web 工作台 :18766]
W --> A[认证、权限与业务 API]
A --> B[BPM 登录与会话托管]
A --> S[只读扫描与日期查询]
A --> M[邮件渠道与模板审核]
A --> D[(服务端本地状态与 SQLite)]
B --> P[新版 BPM / SSO]
S --> P
M --> E[公司 IMAP / SMTP]
X[Chrome 扩展] --> L[本机桥接 :18765]
L --> F[离线 PDF 排版]
采用 Node.js 单服务与模块化代码,前端复用 Tabler,浏览器执行使用 Playwright Core。邮件复用 Nodemailer、ImapFlow、MailParser 与 sanitize-html;依赖锁定在 package-lock.json。源码按功能拆分,避免将外部系统调用写入页面渲染逻辑。
| 代码位置 | 职责 |
|---|---|
src/server.cjs、src/dashboard*.cjs |
启动、桥接、Web 路由、工作台身份与设置 |
src/workspace-*.cjs |
日历、异常、连接、监管配置与审计 |
src/bpm-*.cjs |
会话加密、远程输入、续登、列表读取、扫描存储与 API |
src/mail-*.cjs |
邮箱存储、收发服务、模板解析与审核 API |
src/exporter.cjs、extension/ |
可见字段采集、静态快照、PDF 输出 |
web/ |
工作台页面及交互 |
tests/ |
隔离数据、HTTP、浏览器与存储回归 |
4. 角色、连接与登录
管理员管理团队、邮箱与全局设置;操作员处理授权业务及异常;只读成员查看记录。连接敏感操作还需检查管理员身份或连接负责人权限,不能只隐藏按钮。写入操作进行同源校验;多人修改使用版本校验,冲突时拒绝覆盖。
仅维护新版门户 https://bpmn.skyworthdigital.com/ 及所需 https://sso.skyworthdigital.com/。历史调研中的旧网站路径不构成旧版兼容要求。
远程登录必须直接在画面上点击、键盘输入、Tab、粘贴与中文输入,不在画面下方另放替代输入框。每个连接同时只有一个交互租约;人工操作期间后台托管让出控制权。登录成功检查后保存服务端会话,关闭画面释放操作权。
有效 Cookie 优先复用,服务重启后继续恢复。确认认证失效才提交托管账号;网络故障不触发重复密码登录。错误凭据至少冷却 15 分钟;验证码或额外验证生成去重待办,由人完成。
工作台登录有效期为 30 天,活动时续期;BPM 的上游有效期由公司认证系统控制,通过会话复用及自动续登维持长期托管,不改写 Cookie 到期值冒充上游续期。
账号规范化采用去除首尾空格、忽略大小写,以带密钥摘要及数据库唯一约束防止重复托管,页面提前查重不能替代保存事务约束。更换密码保留仍有效会话;更换账号清理原身份会话。连接须先停用再删除,删除清除凭据和 Cookie、保留审计。
5. BPM 扫描与日期视图
- 默认每 5 分钟扫描,遵循业务日历采集开关;管理员可调整或暂停,管理员及连接负责人可立即扫描。
- 从新版门户获取客户端认证信息,在内存使用 Bearer 调用
/bpm/worklist/informlist和/skyworth/todo/v2/workflow/get_process_of_inform_v4。后一个是新版门户聚合来源,不单独维护旧站登录。 - 处理
total/children及page/start/limit,全部来源全部分页成功后事务提交;失败记录运行结果,不把半次扫描写成成功。 - 去重键为连接、来源、任务标识;保存原流程名与业务收到时间,首次发现及最近扫描时间分别记录。
- 按接口
startTime对应的收到时间,以 Asia/Shanghai 划分“到达我们这边”的日期。缺失日期显式保留未知状态,不回填扫描时间。 - 一天一个可折叠分区,支持连接筛选、关键字查询和加载更早日期;后台新增自动刷新,扫描故障不阻断 PDF 记录。
- 当前待阅/知会仅为发现来源;只对精确通知规则命中的任务进行受控只读详情采集,不标已阅、不审批、不保存。不匹配记录保留为候选,不归档、不发信。
唯一业务表格规定 15 类原始类别及精确流程/节点;产品线、字段适配器、模板和受控测试目的地由类别配置显式指定。字段不完整、节点不符或映射冲突进入候选/阻断,不猜测处理。
6. 邮箱与模板
支持公司 SMTP/IMAP,服务器、端口、TLS 方式与登录身份由管理员维护。证书正常校验,连接检查不发信。新邮箱默认暂停收信,开启后后台每分钟检查,也支持立即收信。
仅接收允许发件人提交的模板。主题 [模板][产品线]发信标题 指定产品线;[模板]发信标题 为默认模板。回复、转发、无效范围及超 10 MB 邮件不导入。按邮箱、UIDVALIDITY 和 UID 去重,首次及 UID 变化只查近 7 天;只读访问,不标记已读、移动或删除。
解析正文、HTML、CID 图片、附件和原 EML;模板必须在 Web 预览并确认后生效。保留版本和来源,多人确认冲突不覆盖新版本。HTML 预览隔离、清理脚本并阻断外链图片,内嵌资源限制展开大小。
变量只替换 {{产品线}}、{{订单号}}、{{日期}}、{{订单列表}},不执行代码。原邮件 To/Cc 不修改业务收件群组。显式测试只发到托管邮箱自身,记录任务;不确定发送结果不自动重发。
7. 日历、异常与后续执行
业务时间统一为 Asia/Shanghai。日历区分采集与发送,支持周规则、公司工作日、休息日、停发覆盖;每天两个发送时段必须不同。保存配置不会立即发送。
异常需包含连接或任务引用、失败步骤、负责人、状态、时间和流转记录,支持认领及转交。核验关闭保存操作人和核验依据;自动步骤的结果来自实际执行回执。产品页面只呈现必要的业务操作、状态、数据和结果。
原生执行链路须持久化通知任务身份、导出、归档、待发、发送结果及批次;重启保留旧 ID 和冻结回执,同一任务不重复通知。PDF 归档失败或发送结果不明时保持阻断。11:00/17:00 窗口不回填、不发空批次;仅已证明纳入待办可保留到下一合法窗口,未纳入历史任务保留 missedWindow 人工核验;冻结和发送前复核当前存在。
ZCode 已接入有限诊断与固定恢复建议;任务状态、重试上限和外部结果判定由确定性程序维护。操作须用户点选后校验权限;后台自主监管尚未实现,真实模型认证待管理员配置。不向模型发送密码、Cookie 或完整业务表单。
8. 数据、保密与部署
运行状态位于部署机 %LOCALAPPDATA%\OrderNotificationAutomation,不写项目共享盘。
| 位置 | 数据 |
|---|---|
dashboard/state.sqlite、dashboard/auth.sqlite |
工作台账号哈希、配置、PDF 记录、登录令牌哈希 |
workspace/workspace.sqlite |
连接、日历、异常、审计与监管配置 |
bpm-sessions/accounts.sqlite、加密会话文件 |
托管账号、密码、冷却信息及会话 |
bpm-keys/ |
Windows DPAPI 保护的主密钥 |
mail/mail.sqlite |
邮箱、模板、原邮件、游标及测试发送记录 |
bpm-scan/scan.sqlite |
流程到达记录、扫描设置与运行结果 |
storage/storage.sqlite |
加密 SMB 服务器配置、自动归档设置与归档记录 |
notifications/notifications.sqlite |
字段映射、加密简要说明队列、发送批次及核验 |
assistant/assistant.sqlite |
加密模型配置、个人会话和固定操作记录 |
health/health.sqlite |
最近观测到的模块成功/失败时间 |
supervisor/supervisor.sqlite、日志与控制文件 |
守护状态、有限事件、登录自启及本机控制 |
敏感载荷使用 AES-GCM 加密,主密钥绑定 Windows 运行身份。账号 API 不返回已保存密码,客户端不取得 BPM Cookie。远程画面不录制,输入不写日志;导出快照移除密码及隐藏数据。
代码仓库只包含源码、锁定依赖、测试、示例配置和设计文档。排除 node_modules、output、实际 config.json、配对配置、数据库、密钥、Cookie、原邮件、业务文件及日志。测试样例使用虚构标识。备份应停服务后备份整个状态目录,并保护密钥恢复条件;跨 Windows 用户或主机迁移需单独验证 DPAPI 恢复或重新授权。
要求 Windows、Node.js 22.13+(建议 24)、Chrome 及到 BPM/邮箱的网络连通性。npm ci 后 npm start;首次创建管理员。桥接仅监听 127.0.0.1:18765,Web 默认 0.0.0.0:18766。多人敏感操作通过 HTTPS 反向代理,仅信任部署机回环代理,示例见 deploy/bpm-login.Caddyfile。当前已支持独立守护和 Windows 用户登录自启;防火墙、DNS、证书与备份由部署环境配置并验收。
9. 验收与实施顺序
- 登录与托管:重启复用、失效续登、验证码待办、账号并发查重、停用删除、远程画面直接输入、权限与租约。
- 扫描与日期:跨页完整、重复不新增、失败不半提交、收到日期跨日正确、后台新增刷新、日历暂停与手动覆盖。
- 邮件模板:中文 MIME、HTML/CID/附件、白名单、UID 重置、预览隔离、确认后生效、版本冲突、只向自身测试。
- 业务表格接入:确认流程范围、订单标识及字段映射,先核对候选清单,再连接自动详情和 PDF。
- 210 与自动发送:确认上传参数、模板群组及两个时段,验证批次去重、重启恢复、结果不明处理,再启用正式群组。
- 运维监管:完成异机 HTTPS、常驻、备份恢复,再按实际需求接入通知接口人与 ZCode。
自动验证入口为 npm test。不同阶段记录有各自范围,不能把隔离夹具测试当成公司真实系统的端到端验收。最近扫描验证详情见 BPM 扫描验证记录,其他阶段见 验证历史。
2026-10-17 通用配置补充
存储与通知的设计分别见 SMB 存储设计 与 通用通知设计。业务通知以简要说明原文为正文,不改写、不附加归档 PDF;来源字段未核实时不从标题推断。源数据由标准入队接口接收,实际 BPM 适配由后续业务资料确定。通用功能默认关闭,参数通过工作台配置,不硬编码服务器、产业、接口人或实际流程名。