docs: add development handoff and update deployment baseline

This commit is contained in:
阿白叔 committed 2026-10-18 22:36:25 +08:00
1 parent 9a23197ecf
commit 9854d2d5c2
4 files changed
+96 -6

No files matched your search

+1
View File
@@ -6,6 +6,7 @@
## 设计与部署入口
- [开发交接(2026-10-18)](docs/HANDOFF.md):接续分支、当前进度、启动命令、验证边界及下一步建议。
- [设计要求(当前基准)](docs/design-requirements.md):功能范围、架构、数据存储、权限、验收和实施顺序。
- [部署说明](docs/deployment.md):安装、HTTPS、状态目录及备份。
- [后续业务资料整理表](docs/business-configuration.md):SMB 参数、来源字段和产业接口人需要整理的信息。
+83
View File
@@ -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)。早期阶段文档的“尚未实现”以最新基准及代码为准。
+4 -2
View File
@@ -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
+8 -4
View File
@@ -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. 验收与实施顺序