diff --git a/README.md b/README.md index f590530..84c6445 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ ## 设计与部署入口 +- [开发交接(2026-10-18)](docs/HANDOFF.md):接续分支、当前进度、启动命令、验证边界及下一步建议。 - [设计要求(当前基准)](docs/design-requirements.md):功能范围、架构、数据存储、权限、验收和实施顺序。 - [部署说明](docs/deployment.md):安装、HTTPS、状态目录及备份。 - [后续业务资料整理表](docs/business-configuration.md):SMB 参数、来源字段和产业接口人需要整理的信息。 diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md new file mode 100644 index 0000000..359009f --- /dev/null +++ b/docs/HANDOFF.md @@ -0,0 +1,83 @@ +# 开发交接(2026-10-18) + +## 接续分支与运行 + +仓库:`https://git.simgreek.com/simgreek/order-notification-automation.git`。 + +当前开发分支是 **`codex/smb-storage`**,包含 SMB、预览、ZCode 和守护的全部工作;旧 `main` 不代表最新能力。最近实现提交:`9a23197` 服务守护和健康面板、`e2bd8c3` BPM 请求异常导致进程退出的修复、`3363a88` ZCode 接入、`fff2a29` 按真实订单号归档、`607b240` BPM 会话 SQLite 持久化。 + +```powershell +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 仅使用授权快照;固定动作须用户点选并重新检查权限,不执行模型任意命令、文件、审批或邮件操作。 +- 健康卡片是上次保存/观测结果,不等同实时外网连通性;刷新不触发外部检查。邮件结果不明保持待核实,不自动重发。 + +## 下一步建议(尚未实施) + +用户本轮确认并完成的是“服务守护+健康面板”。以下只是后续建议: + +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 上限,不能把它们当安全控制。 + +```powershell +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 +``` + +详细证据见 [验证记录](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)。早期阶段文档的“尚未实现”以最新基准及代码为准。 diff --git a/docs/deployment.md b/docs/deployment.md index 0e5ab91..0671ae2 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -3,12 +3,14 @@ ## 安装启动 1. 准备常驻 Windows 机器、Node.js 22.13+(建议 24)及 Chrome,确认可访问新版 BPM、SSO 和公司邮箱。 -2. 克隆私有仓库,进入项目执行 `npm ci`。 +2. 克隆私有仓库并切换到交接分支 `codex/smb-storage`,进入项目执行 `npm ci`。后续开发见 [交接说明](HANDOFF.md)。 3. 按需复制 `config.example.json` 为 `config.json`,调整监听端口、PDF 输出目录与代理设置。实际配置不提交 Git。 4. 执行 `npm start` 或双击 `启动工具.cmd`。浏览器访问 `http://127.0.0.1:18766/`,首次自行创建管理员,无默认密码。 5. 管理员创建团队账号,配置 BPM 连接及邮箱。账号密码在 Web 中录入,不写源码、命令行或文档。 -服务进程需持续运行,网页可以关闭。当前启动入口不自动安装 Windows 服务或开机任务;常驻运行时使用固定 Windows 账号,另行配置并验证开机启动与失败重启。不要同时启动多个实例访问同一状态目录。 +`npm start` 通过独立守护后台启动,网页及启动窗口可以关闭;重复启动复用实例。业务进程退出或持续无响应时按退避/冷却恢复,不结束未知端口的占用进程。通过 `npm run service:status` 查看状态,`service:restart` 重启,`service:stop` 显式停止。 + +`npm run service:install` 安装当前 Windows 用户登录自启,移除用 `service:uninstall`。本机已安装并验证快捷方式;登录后沿用该账号的 DPAPI 和 SMB 权限,不是未登录运行的系统服务。移动项目或更换 Node 路径后重新安装自启。健康面板 `/#health` 展示守护与历史模块状态,不触发外部检查。 ## 多人访问与 HTTPS diff --git a/docs/design-requirements.md b/docs/design-requirements.md index 8253d1f..4c36ac6 100644 --- a/docs/design-requirements.md +++ b/docs/design-requirements.md @@ -1,6 +1,6 @@ # 订单通知自动化:设计要求 -更新日期:2026-10-17。本文为当前设计要求入口;与早期调研或阶段计划冲突时,以本文及对应模块最新设计为准。业务规则的调整需要同步本文、实现与验收记录。 +更新日期:2026-10-18。本文为当前设计要求入口;与早期调研或阶段计划冲突时,以本文及对应模块最新设计为准。业务规则的调整需要同步本文、实现与验收记录。继续开发先读 [交接说明](HANDOFF.md)。 ## 1. 产品目标与运行方式 @@ -24,7 +24,8 @@ | PDF | Chrome 扩展手动采集、离线生成、四字段命名、重名保留 | 按业务表单适配无人值守详情与导出 | | SMB 存储服务器 | 独立凭据加密、地址管理、读写检查、目录浏览、PDF 手动与新文件自动归档 | 录入服务器与权限,完成实机验收 | | 自动业务邮件 | 通用来源字段映射、样本预览、持久队列、两时段调度、去重与人工核验 | 核实 BPM 简要说明来源和产业接口人映射后接通来源 | -| ZCode 监管 | 方向预留,未接入 | 确认 GLM ZCode 接口、诊断范围及通知渠道 | +| ZCode 助手 | 个人对话、加密历史、固定操作卡片、权限/工具约束,官方 CLI 与本机测试模型联调 | 配置并验证真实供应商模型,后台自主监管未实现 | +| 服务守护与健康 | 独立进程、双端口心跳、异常恢复、退避冷却、Windows 登录自启、历史健康面板 | 异机部署与备份恢复演练 | | 青龙 | 保留部署准备及 CLI | 暂停部署,不作为当前服务启动依赖 | ## 3. 架构与模块职责 @@ -100,7 +101,7 @@ flowchart LR 后续执行链路必须持久化订单版本、导出、上传、待发、发送结果及批次;重启可恢复,同一版本不重复通知。缺少群组或发送结果不明时停在通知步骤;PDF 上传失败单独记录,不生成邮件任务。上线前明确历史补发、漏过时段补发、空批次和更改单策略。 -ZCode 后续用于有限诊断与修复建议;任务状态、重试上限和外部结果判定由确定性程序维护。接入前明确接口人及通知渠道,不向模型发送密码、Cookie 或完整业务表单。 +ZCode 已接入有限诊断与固定恢复建议;任务状态、重试上限和外部结果判定由确定性程序维护。操作须用户点选后校验权限;后台自主监管尚未实现,真实模型认证待管理员配置。不向模型发送密码、Cookie 或完整业务表单。 ## 8. 数据、保密与部署 @@ -116,12 +117,15 @@ ZCode 后续用于有限诊断与修复建议;任务状态、重试上限和 | `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`。开机常驻、防火墙、DNS、证书与备份由部署环境配置并验收。 +要求 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. 验收与实施顺序