Files
order-notification-automation/docs/design-requirements.md
T

17 KiB
Raw Blame History

订单通知自动化:设计要求

模板 {{日期}} 使用订单原始 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/附件、自发测试 接入正式订单数据渲染与发送批次
PDF 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. 验收与实施顺序

  1. 登录与托管:重启复用、失效续登、验证码待办、账号并发查重、停用删除、远程画面直接输入、权限与租约。
  2. 扫描与日期:跨页完整、重复不新增、失败不半提交、收到日期跨日正确、后台新增刷新、日历暂停与手动覆盖。
  3. 邮件模板:中文 MIME、HTML/CID/附件、白名单、UID 重置、预览隔离、确认后生效、版本冲突、只向自身测试。
  4. 业务表格接入:确认流程范围、订单标识及字段映射,先核对候选清单,再连接自动详情和 PDF。
  5. 210 与自动发送:确认上传参数、模板群组及两个时段,验证批次去重、重启恢复、结果不明处理,再启用正式群组。
  6. 运维监管:完成异机 HTTPS、常驻、备份恢复,再按实际需求接入通知接口人与 ZCode。

自动验证入口为 npm test。不同阶段记录有各自范围,不能把隔离夹具测试当成公司真实系统的端到端验收。最近扫描验证详情见 BPM 扫描验证记录,其他阶段见 验证历史。

相关模块设计:框架、BPM 登录、扫描、邮件。

2026-10-17 通用配置补充

存储与通知的设计分别见 SMB 存储设计 与 通用通知设计。业务通知以简要说明原文为正文,不改写、不附加归档 PDF;来源字段未核实时不从标题推断。源数据由标准入队接口接收,实际 BPM 适配由后续业务资料确定。通用功能默认关闭,参数通过工作台配置,不硬编码服务器、产业、接口人或实际流程名。