Files
order-notification-automation/docs/HANDOFF.md
T

13 KiB
Raw Blame History

开发交接(2026-10-23)

当前规则与本机测试状态

本节为当前交接基准,下文旧日期内容仅保留历史。源码位于 Z 盘项目目录(同一 UNC 共享目录),分支为 codex/smb-storage。当前业务代码提交1848a6c,已经推送;本机运行已切到经过逐文件核对的本地副本,原工作树代码保持不动。

  • 业务范围严格取原 Excel 的15类精确流程与节点;海外四流程仅允许“订单专员(订单通知书)”。“生效”和BOM固化不作为通知节点。产品线、模板由分类明确配置,测试产品线标签取规则名称。
  • 处理身份为 source + portalSource + taskId;上游未提供业务修订时保持缺失,真实0保留。到达库沿用唯一旧键及首见来源;多个旧键冲突须人工核验,整批回滚,不挑选或删除历史记录。
  • 当前新鲜待办只有经服务器读取、精确范围及版本检查后才可纳入不可变允许清单;原 receivedAt 不改,admittedAt 单独保存。冻结与发送前重新确认已纳入任务仍存在、内容一致。
  • 只启动一套原生 OrderExecutionCoordinator / OrderRuleDispatcher;根目录旧工作流不启动。只读详情限制已核验路径、字段及表单版本,listVersion 与 formVersion 分开。BPM 不已阅、不审批、不保存、不办理。
  • PDF归档及读回校验成功后才能通知;To固定隔离QQ邮箱,Cc与附件为空,归档限定原桌面测试目录。普通与惠州模式均保留模板问候、说明、签名,订单区一单一行且从订单号开始;日期变量使用原始 event.receivedAt 的北京时间日期,跨日按出现顺序去重,不采用发送、纳入或创建日期。
  • 按分类、模板及窗口冻结,既有冻结正文不重渲染;sent/unknown不自动重发。每天北京时间11:00/17:00遵循原业务日历,空批次不发送,不自动补发历史窗口。明确纳入的待办可进入下一合法窗口;冻结prepared队列宽限30分钟。

实际运行与恢复

本机测试地址:http://127.0.0.1:18766/#notification-orders 。运行副本为 %LOCALAPPDATA%/OrderNotificationAutomationReleases/test-native-20261023-76bbac02 。请从该副本的 scripts/service.cjs start 启动当前测试版本;源码目录用于开发,旧modular-refactor目录仅保留原代码与原PDF输出,不作为新测试版本启动入口。登录自启原为关闭,保持关闭;正式服务机未操作。

状态目录仍为原 %LOCALAPPDATA%/OrderNotificationAutomation。原账号、连接、邮箱、31个字段适配器、32份样本、旧归档及规则快照保留;原PDF输出路径继续使用旧工作树的output/pdf。完整备份位于 %LOCALAPPDATA%/OrderNotificationAutomationBackups/strict-excel-before-20261023-2026-10-23T04-05-17-523Z,已通过官方创建、验证和应用前恢复性检查。

15类受限快照已应用,自动处理及11:00/17:00计划意图已启用。此前已收件测试任务的原身份、批次和证据导入防重;旧运行的一条已归档待发记录保持待核验,不自动重排或发送。惠州附加通知原来未启用,本次保持未启用。

第一次实际切换发现历史对账微任务连续执行阻塞心跳,以及监听层仍拒绝缺失revision。已修复为扫描窗口一次取值、历史线索间让出事件循环及重检暂停/停止,并修正真实待办身份。最终全量990项:989通过、0失败、1项可选ZCode测试跳过。409个运行及测试文件与本地副本逐字节核对一致。

更新后观察同一业务进程持续运行超过十分钟,未新增重启;295份对账线索已完成,17条真实待办读取成功,原82条到达记录的键、首见时间及来源保留。新建业务批次0,本轮没有新增真实邮件。数字是交接时快照,后台后续对账会继续更新。

13:03/13:09 的17条实时待办均未命中Excel通知节点,这是当时待办快照,不能据此判断今天没有应通知订单。随后根据用户提供的当天邮件,在已办列表及只读流程步骤中找到三笔:两笔试产类订单已于11:24/11:25提交Excel的确切通知节点;一笔海外返工订单于11:26结束名为“订单通知书”的节点,与Excel的“订单专员(订单通知书)”不一致,等待业务确认,不擅自增加别名。严格测试运行基线为12:12,三笔都已离开通知待办。

当前执行器只读当前待办,历史采样只用于字段配置,缺少已办通知任务的补偿发现。已验证的 ProcessStep 只返回节点名称和办理完成时间,没有通知任务ID或节点到达时间;不能用流程实例ID、行号、完成时间构造通知任务。下一步需核实可获取原通知任务ID/到达时间的只读来源,再设计受控历史对账与持久通知快照;历史纳入和补发范围须明确,原已发送/结果不明任务仍禁止自动重演。人工邮件跨类别合并不覆盖Excel分类:这两类仍分别使用分类模板。详见本轮整合验证。

运行能力中的PDF导出及自动归档仍待首笔合格真实任务验证,页面显示“自动通知受阻”;不伪造就绪状态,也不处理“生效”订单来补证据。15类真实闭环未完成;零售国内返工订单更改评审仍缺字段适配器,继续阻断。逐类真实节点、PDF视觉核对、计划邮件实收和正式210/SMB另行验收。本次三笔调查未更改代码、规则、测试基线或发送范围,未补发邮件,也未办理BPM。

你提供的两笔历史邮件样本已与BPM历史摘要逐字段核对一致,两流程均属海外类别;未取得当时通知节点证据,不以邮件正文证明触发时点合规。详细证据、已知边界见本轮整合验证。业务PDF、数据库、Cookie、密钥、原始采样、截图和本地设计草稿不提交Git。

2026-10-18 历史接续分支与运行记录

本节及以下早期能力、命令、路径和测试计数是当时快照,不是本次合并切换回执;继续工作以前述 2026-10-23 权威边界为准。

仓库:https://git.simgreek.com/simgreek/order-notification-automation.git。

当前开发分支是 codex/smb-storage,包含 SMB、预览、ZCode 和守护的全部工作;旧 main 不代表最新能力。最近实现提交:9a23197 服务守护和健康面板、e2bd8c3 BPM 请求异常导致进程退出的修复、3363a88 ZCode 接入、fff2a29 按真实订单号归档、607b240 BPM 会话 SQLite 持久化。

git fetch origin
git switch codex/smb-storage
git pull --ff-only origin codex/smb-storage
npm ci
npm start

新克隆尚无本地分支时用 git switch --track origin/codex/smb-storage。本机源码在 F:\Sync Tool Skyworth\Work Maps\order,依赖已安装,无须为继续开发重复安装。

本机交接时守护正常,Windows 当前用户登录自启已启用。工作台 http://127.0.0.1:18766,健康页 /#health,助手 /#assistant。

命令 用途
npm start 后台守护启动;重复打开复用实例
npm run service:status 查看守护实际响应与持久状态
npm run service:restart 正常重启并检查两个端口
npm run service:stop 显式停止,不自动拉起;保留自启设置
npm run service:install / service:uninstall 安装/移除当前用户登录自启
npm run start:foreground 前台排错,需先停守护以免端口冲突

自启在当前 Windows 用户登录后执行,沿用其 DPAPI 和 SMB 权限,不是未登录运行的系统服务。移动源码或更换 Node 路径后重新安装自启。

已实现

  • 工作台账号/角色/持久登录、日历、异常、BPM 远程登录与加密托管续登、只读分页扫描、按到达日查询。
  • SMB 主机共享浏览、免填或独立凭据、可取消的有界检查、读取成功后添加、PDF 手动/新文件自动归档。按可见 BPM OrderNum 的完整 6/7 位订单号建目录,保留前导零、复用已有目录,不默认截取或从文件名猜号。
  • 本机内嵌 PDF、图片、文本、DOCX/XLSX 预览;旧 DOC/XLS 下载,Office 排版不保证与桌面软件一致。
  • 邮箱与模板审核,以及独立业务通知队列:来源字段映射、样本预览、产业群组、两个北京时间时段、去重及结果不明核验。
  • ZCode 个人对话、加密历史、权限、固定操作卡片、取消及额度。官方桌面包 3.14.3 附带 CLI 实际为 0.16.9,已用官方 CLI + 本机测试模型验证;真实模型 API 参数尚未配置/认证,后台自主监管未实现。换机器用 7-Zip 和 node scripts/setup-zcode.cjs 校验解包,管理员在页面配置模型,运行包不在 Git。
  • 独立守护、双端口实例心跳、退出/持续无响应恢复、退避/冷却、日志轮转、Windows 登录自启、只读历史健康面板与断线恢复。

必须延续的业务边界

  • PDF 仅归档,不附加到通知邮件,不因归档而触发邮件。 邮件正文只取 BPM 简要说明原文,按产业通知接口人。
  • 流程范围、简要说明字段、产业与接口人映射由同事整理后配置;不把全部待阅/知会当订单,不猜收件人,不自动已阅或审批。
  • “210”是可配置 SMB 能力,不硬编码服务器或目录。免填模式使用部署账号/现有 SMB 会话,不是网页访问者身份。
  • ZCode 仅使用授权快照;固定动作须用户点选并重新检查权限,不执行模型任意命令、文件、审批或邮件操作。
  • 健康卡片是上次保存/观测结果,不等同实时外网连通性;刷新不触发外部检查。邮件结果不明保持待核实,不自动重发。

2026-10-18 历史下一步建议

当时确认并完成的是“服务守护+健康面板”。以下建议仅保留历史,不作为当前业务身份或实施状态:

  1. 批量导出/归档与持久任务记录:从扫描列表人工勾选,自动打开详情、采集可见字段、生成 PDF、按真实订单号归档;显示进度、支持取消及失败步骤重试。
  2. 统一订单任务中心:按订单号和业务版本关联扫描、导出、归档及独立通知状态,保持 PDF 和通知两条链路独立。
  3. 健康异常跳转具体失败记录,复用已完成结果,只重试允许重试的步骤。
  4. 可配置业务规则和试运行预览;同事资料核实后再接自动来源。
  5. 自动备份与恢复演练;跨机或跨 Windows 用户需验证 DPAPI 恢复条件或重新授权。

验证与容易重复踩的问题

  • 服务守护及受影响回归 20/20、额外加密存储 7/7,共 27 项不同测试通过;19 个 JS 语法检查通过。覆盖实际子进程退出/无响应、冷却、手动重启/停止、鉴权及畸形消息、未知端口保护、中文启动器、安装失败/外来快捷方式、健康历史/权限、浏览器断线恢复。
  • 实机独立 CLI 重启后守护保持、两个端口恢复、登录会话保留,健康页无脚本错误。没有重启 Windows,也未验收公司真实邮件及正式全业务自动处理。
  • ZCode 官方 CLI 的真实请求已核对地址/模型/鉴权及空工具列表;返回未经请求的 Write 调用时没有写文件。供应商真实认证仍待配置。
  • 本环境曾拒绝文件 rename(EXDEV),会话已改 SQLite,不倒退为临时文件 rename。
  • BPM fulfill/abort 必须在 try 内 await,否则异步拒绝绕过 catch 导致服务退出。
  • Windows PowerShell 明确 UTF-8 输入/输出;VBS 用 UTF-16LE BOM,已执行验证中文及空格路径。
  • 管理令牌仅用于本机管道,HTTP 心跳每次启动独立随机。超时不能当停止成功,须通道关闭且同一实例的 stopped 状态落盘。
  • CLI 工具禁止名单按精确名称,* 不代表全部;旧 provider 导入忽略 tool_call:false 和输出 token 上限,不能把它们当安全控制。
node --test --test-concurrency=1 tests/service-supervisor.test.cjs tests/service-control.test.cjs tests/windows-startup.test.cjs tests/runtime-health.test.cjs tests/health-http-ui.test.cjs tests/server.test.cjs tests/workspace-http.test.cjs tests/bpm-runtime.test.cjs tests/dashboard-http.test.cjs
node --test tests/bpm-vault.test.cjs

详细证据见 验证记录。日志/截图位于本机忽略目录 output/verification,新克隆需要重新生成。

运行数据与阅读入口

状态位于 %LOCALAPPDATA%\OrderNotificationAutomation,含工作台、BPM、邮件、扫描、存储、通知、助手、健康与守护的 SQLite,以及加密主密钥和本机运行包。账号密码、Cookie、API Key、数据库、业务 PDF/原邮件、日志、截图不提交 Git。

Git 推送不等于运行数据备份。 备份先 npm run service:stop,保护整个本地状态及业务输出目录和 DPAPI 恢复条件,再 npm start。本机开发/测试连接不视为正式 210 等服务器端到端验收。

阅读顺序:README、当前设计要求、业务资料整理表,按任务查 守护设计、ZCode 接入记录、验证历史。早期阶段文档的“尚未实现”以最新基准及代码为准。