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

14 KiB
Raw Blame History

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

更新日期:2026-10-18。本文为当前设计要求入口;与早期调研或阶段计划冲突时,以本文及对应模块最新设计为准。业务规则的调整需要同步本文、实现与验收记录。继续开发先读 交接说明。

1. 产品目标与运行方式

团队成员在各自电脑访问同一台常驻服务器,通过 Web 管理 BPM 连接、流程到达记录、业务日历、异常、邮件模板和收件群组。正式工作台使用真实持久数据,不预置演示账号或虚构订单,不提供默认管理员密码。

最终业务按两条链路组织:PDF 提取生成后归档到可配置 SMB 服务器;业务通知将 BPM 简要说明原文按产业发送给接口人,使用每日两个约定时段。PDF 归档不触发邮件,也不附加 PDF;具体 BPM 字段与产业规则由同事整理后配置。

当前阶段优先保证账号托管、只读扫描、日期视图与邮件模板维护。业务匹配规则由后续表格确定;在规则确认前,不将知会状态等同于可处理订单,不自动已阅、审批或发送业务通知。

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/app/ 正式入口、生命周期装配、扩展桥接与 HTTP 公共处理
src/modules/dashboard/ 工作台认证、账号、设置、任务记录与业务路由
src/modules/workspace/ 日历、异常、连接、监管配置与审计
src/modules/bpm/ 远程输入、安全登录表单、续登、列表读取、扫描存储与 API
src/modules/mail/ 邮箱存储、收发服务、模板解析与审核 API
src/modules/storage/ SMB 隔离工作进程、文件边界、归档与预览
src/modules/notifications/ 来源映射、通知事务、时段发送及人工核验/恢复
src/modules/assistant/、src/modules/health/ 受控模型对话与只读运行健康
src/modules/pdf/、extension/ 可见字段采集、静态快照、PDF 输出
src/platform/、src/shared/ 浏览器、加密、守护、自启动、状态目录独占与公共路径/脱敏/时段计算
web/modules/<业务>/ 各业务页面与交互;公开资源 URL 保持兼容
tests/<业务>/、tests/fixtures/ 按模块组织的隔离数据、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 记录。
  • 当前待阅/知会仅为临时采集来源;不打开详情、不标已阅、不审批。保留不匹配流程,等待后续表格定义筛选。

后续业务表格至少需明确流程名称与版本、触发节点、产品线、字段映射、通知类型、新单/更改单范围、模板和收件群组。字段不完整、范围不明或映射冲突进入待办,不猜测处理。

6. 邮箱与模板

支持公司 SMTP/IMAP,服务器、端口、TLS 方式与登录身份由管理员维护。证书正常校验,连接检查不发信。新邮箱默认暂停收信,开启后后台每分钟检查,也支持立即收信。

仅接收允许发件人提交的模板。主题 [模板][产品线]发信标题 指定产品线;[模板]发信标题 为默认模板。回复、转发、无效范围及超 10 MB 邮件不导入。按邮箱、UIDVALIDITY 和 UID 去重,首次及 UID 变化只查近 7 天;只读访问,不标记已读、移动或删除。

解析正文、HTML、CID 图片、附件和原 EML;模板必须在 Web 预览并确认后生效。保留版本和来源,多人确认冲突不覆盖新版本。HTML 预览隔离、清理脚本并阻断外链图片,内嵌资源限制展开大小。

变量只替换 {{产品线}}、{{订单号}}、{{日期}}、{{订单列表}},不执行代码。原邮件 To/Cc 不修改业务收件群组。显式测试只发到托管邮箱自身,记录任务;不确定发送结果不自动重发。

7. 日历、异常与后续执行

业务时间统一为 Asia/Shanghai。日历区分采集与发送,支持周规则、公司工作日、休息日、停发覆盖;每天两个发送时段必须不同。保存配置不会立即发送。

异常需包含连接或任务引用、失败步骤、负责人、状态、时间和流转记录,支持认领及转交。核验关闭保存操作人和核验依据;自动步骤的结果来自实际执行回执。产品页面只呈现必要的业务操作、状态、数据和结果。

后续执行链路必须持久化订单版本、导出、上传、待发、发送结果及批次;重启可恢复,同一版本不重复通知。缺少群组或发送结果不明时停在通知步骤;PDF 上传失败单独记录,不生成邮件任务。上线前明确历史补发、漏过时段补发、空批次和更改单策略。

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 适配由后续业务资料确定。通用功能默认关闭,参数通过工作台配置,不硬编码服务器、产业、接口人或实际流程名。