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

84 lines
7.3 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.
# 开发交接(2026-10-19)
## 接续分支与运行
仓库:`https://git.simgreek.com/simgreek/order-notification-automation.git`。
本轮模块化重构位于本地分支 **`codex/modular-refactor`**,基于 `codex/smb-storage` 的 `9854d2d`。未推送、合并或部署。源码工作区为 `C:\Users\ABS\.codex\worktrees\modular-refactor\Order Notification Automation`;原 `Z:\Order Notification Automation` 工作区保持原源码。旧 `main` 不代表最新能力。
```powershell
git switch codex/modular-refactor
npm ci
npm test
```
新克隆仍以已发布分支为准;本地重构分支尚不可从远端检出。本轮验证复用原工作区和临时目录的依赖(通过 `NODE_PATH`),没有修改正式运行依赖或配置。模块职责及兼容约束见 [批准的重构方案](superpowers/specs/2026-10-19-modular-refactor-design.md)。
2026-10-18 的交接记录为守护正常、当前用户登录自启已启用;本轮没有操作或重新核实正式服务。默认工作台 `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 仅使用授权快照;固定动作须用户点选并重新检查权限,不执行模型任意命令、文件、审批或邮件操作。
- 健康卡片是上次保存/观测结果,不等同实时外网连通性;刷新不触发外部检查。邮件结果不明保持待核实,不自动重发。
## 下一步建议(尚未实施)
本轮授权范围为模块化重构与七项审查问题修复。以下业务功能仍属后续建议:
1. **批量导出/归档与持久任务记录**:从扫描列表人工勾选,自动打开详情、采集可见字段、生成 PDF、按真实订单号归档;显示进度、支持取消及失败步骤重试。
2. **统一订单任务中心**:按订单号和业务版本关联扫描、导出、归档及独立通知状态,保持 PDF 和通知两条链路独立。
3. 健康异常跳转具体失败记录,复用已完成结果,只重试允许重试的步骤。
4. 可配置业务规则和试运行预览;同事资料核实后再接自动来源。
5. 自动备份与恢复演练;跨机或跨 Windows 用户需验证 DPAPI 恢复条件或重新授权。
## 验证与容易重复踩的问题
本轮模块化重构、七项修复及额外生命周期补修见 [2026-10-19 重构验证](modular-refactor-verification-2026-10-19.md)。以下守护实机/官方 CLI 记录来自此前阶段,本轮没有重复操作正式服务或真实提供方。
- 服务守护及受影响回归 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 上限,不能把它们当安全控制。
```powershell
npm test
node --test tests/bpm/bpm-vault.test.cjs
```
详细证据见 [验证记录](verification.md)。日志/截图位于本机忽略目录 `output/verification`,新克隆需要重新生成。
## 运行数据与阅读入口
状态位于 `%LOCALAPPDATA%\OrderNotificationAutomation`,含工作台、BPM、邮件、扫描、存储、通知、助手、健康与守护的 SQLite,以及加密主密钥和本机运行包。账号密码、Cookie、API Key、数据库、业务 PDF/原邮件、日志、截图不提交 Git。
**Git 推送不等于运行数据备份。** 备份先 `npm run service:stop`,保护整个本地状态及业务输出目录和 DPAPI 恢复条件,再 `npm start`。本机开发/测试连接不视为正式 210 等服务器端到端验收。
阅读顺序:[README](../README.md)、[当前设计要求](design-requirements.md)、[业务资料整理表](business-configuration.md),按任务查 [守护设计](superpowers/specs/2026-10-18-service-health-design.md)、[ZCode 接入记录](zcode-integration-2026-10-18.md)、[验证历史](verification.md)。早期阶段文档的“尚未实现”以最新基准及代码为准。