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

162 lines
17 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.
# 订单通知自动化:设计要求
模板 `{{日期}}` 使用订单原始 `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类真实闭环未验收,零售国内返工订单更改评审仍缺适配器。详细证据和待确认项以[本轮整合验证](bpm-native-integration-verification-2026-10-23.md)为准。
## 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. 架构与模块职责
```mermaid
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-scan-verification-2026-10-16.md),其他阶段见 [验证历史](verification.md)。
相关模块设计:[框架](superpowers/specs/2026-10-16-application-framework-design.md)、[BPM 登录](superpowers/specs/2026-10-16-bpm-login-design.md)、[扫描](superpowers/specs/2026-10-16-bpm-scan-design.md)、[邮件](superpowers/specs/2026-10-16-mail-design.md)。
## 2026-10-17 通用配置补充
存储与通知的设计分别见 [SMB 存储设计](superpowers/specs/2026-10-17-storage-design.md) 与 [通用通知设计](superpowers/specs/2026-10-17-notification-design.md)。业务通知以简要说明原文为正文,不改写、不附加归档 PDF;来源字段未核实时不从标题推断。源数据由标准入队接口接收,实际 BPM 适配由后续业务资料确定。通用功能默认关闭,参数通过工作台配置,不硬编码服务器、产业、接口人或实际流程名。