11 KiB
11 KiB
按业务模块组织代码:重构设计
日期:2026-10-19。状态:已实施并验收;最终全量 222 项,221 通过、0 失败、1 跳过。详见 本轮验证。
目标与范围
将当前平铺在 src、web、tests 的代码整理为按业务边界组织的模块,并拆开承担多项职责的入口、路由、通知队列与浏览器登录代码。采用单进程模块化架构,保持 CommonJS、Node.js >=22.13、当前 HTTP 地址、启动命令、SQLite 格式、加密身份及业务规则。
本次交付为目录与职责重构,同时修复上一轮审查的全部七项问题。用户已明确要求一起完成。每项修复与所属模块一起实施并增加针对真实故障边界的回归测试。不得启动或重启正式服务、访问正式 BPM/SMB/邮箱或修改实际运行数据。
方案比较
- 推荐:按业务模块纵向组织,模块内包含 API、服务、存储、策略或客户端;启动编排与底层平台单独组织。源码、页面和测试使用一致模块名,迁移后独立验证各模块。
- 只移动文件到文件夹:改动较小,但保留入口和混合类中的职责耦合,未充分满足本次“目录和职责”调整。
- 拆成多个 npm 包或微服务:增加发布、进程和依赖维护成本,当前单机工作台没有这类隔离需求。
目录结构
src/
server.cjs # 保留正式启动与 main/createServer/startService 导出入口
app/
application.cjs # 初始化、依赖装配、启动与关闭编排
bridge.cjs # 扩展桥接 HTTP、配对与导出任务接受
dashboard.cjs # 工作台 HTTP 编排、业务路由分发
assets.cjs # 固定公开 URL 到页面和第三方资源的映射
request.cjs # 请求解析、同源与安全响应公共处理
modules/
dashboard/
api.cjs # 账号、设置、概览、任务记录、PDF 下载路由
auth.cjs # 登录、bootstrap、预览登录、Cookie 和失败限流
store.cjs
sessions.cjs
workspace/ # 日历、连接登记、异常流转、监管配置
api.cjs
store.cjs
bpm/
api.cjs
session-manager.cjs # 会话、租约、串行控制与认证流程编排
login-form.cjs # 已识别表单与安全填入/提交的浏览器侧交互
custodian.cjs
list-client.cjs
scan-api.cjs
scan-store.cjs
scanner.cjs
mail/ # 邮箱、模板收取与审核、测试发信
api.cjs
store.cjs
service.cjs
parser.cjs
storage/ # SMB、文件边界、归档、预览
api.cjs
store.cjs
service.cjs
files.cjs
order.cjs
preview.cjs
preview-assets.cjs
smb-native.cjs
smb-probe.cjs
smb-probe-worker.cjs
notifications/
api.cjs
store.cjs # 队列、批次、去重、事务及状态持久化
service.cjs # 时段调度、SMTP 执行与人工核验编排
mapping.cjs # 来源字段路径、映射校验及事件构造
assistant/
api.cjs
store.cjs
service.cjs
policy.cjs
zcode-runtime.cjs
health/
runtime-health.cjs
platform/
browser.cjs # Playwright/Chrome 依赖和路径发现
service/
instance-lock.cjs # 业务状态目录独占权,恢复业务数据前获得
supervisor.cjs
control.cjs
ping.cjs
store.cjs
windows-startup.cjs
security/
vault.cjs # 已有 AES-GCM/DPAPI 加密与存储实现
shared/
paths.cjs # 源码根、web、extension、scripts 等固定资源根
schedule.cjs
redact.cjs # 助手和健康均使用的脱敏函数
modules/pdf/
exporter.cjs
web/
index.html
app.js # 工作台启动、导航、公共壳层
app.css
modules/
workspace/view.js
bpm/view.js
bpm/arrivals.js
mail/view.js
storage/view.js
storage/preview.html
storage/preview.js
storage/preview.css
storage/preview-office.js
storage/preview-host.js
notifications/view.js
assistant/view.js
health/view.js
tests/
app/ # 工作台 HTTP、导航、启动、资源与预览集成
dashboard/
workspace/
bpm/
mail/
storage/
notifications/
assistant/
service/
pdf/
shared/
fixtures/ # 保留统一的隔离夹具目录
职责和依赖规则
- application 负责创建并注入模块实例;模块文件导入本身不启动定时器、监听网络或执行外部操作。
- HTTP 壳层负责请求基础约束、公共认证和路由顺序;业务 API 负责本模块权限与业务参数,并调用服务;服务负责业务编排;store 负责数据库事务。
- notifications.cjs 拆为 store、service、mapping,避免队列事务、来源解析和 SMTP 调度集中在同一文件。保持原 NotificationStore、NotificationService 可调用接口,内部消费者使用新路径。
- dashboard.cjs 拆出资源映射、认证、业务路由和请求基础处理,保持 bootstrap、预览与生产 Cookie 分离、同源检查和安全头的原执行顺序。
- server.cjs 的扩展桥接与依赖装配分离。保留原入口导出,已有启动脚本和显式工具仍可调用。
- BPM 会话管理器提取明确可隔离的登录表单交互,租约、串行锁、账号状态及续登次序继续由 manager 编排。
- 把通用加密实现从 BPM 命名空间移到 platform/security。保持 BpmVault 导出接口、密钥命名、AAD、数据库表及状态目录完全一致,避免凭据失效。健康模块使用 shared/redact,避免依赖助手业务模块。
- 其他模块按现有 api/service/store/client 边界迁移;模块间通过既有构造参数和公开方法连接,不新增服务容器或全局单例。
- web/app.js 保留启动和公共壳层;已有独立功能页面移到对应模块。公开脚本和预览 URL 由 assets 映射保持兼容,浏览器脚本顺序保持一致。
- tests 按同名模块分组。统一维护资源根和显式导入路径,更新 npm test 的递归测试发现模式,核对测试文件与测试数量,避免迁移时漏跑。
七项问题的修复要求
- 通知重复发送:在 application 打开/恢复业务数据库前取得状态目录独占运行权,前台和守护启动使用同一约束;失败启动必须释放本次资源。通知恢复从构造函数移到显式启动恢复阶段,进入 sending 时用事务核实批次及预留仍有效。回归覆盖第二实例启动失败不改活动通知,以及失效预留不能发信。
- 正式 SMB 操作:已保存服务器的检查、目录、文件、预览和归档统一通过有期限、可终止的工作进程;复用路径与权限检查,凭据只经 IPC,结果验证和大小上限保持约束。停止服务主动取消当前操作并结束排队任务;不以单纯 Promise.race 冒充底层 I/O 已结束。覆盖超时、取消、队列恢复、正常停止和归档完整性。
- BPM 浏览器断开:断开时清理对应浏览器缓存与失效租约,后续请求可在并发控制下重建;迟到的旧浏览器事件不能清理新的实例。真实无头浏览器测试覆盖关闭后重建,并保留租约和登录安全限制。
- 通知次数耗尽:增加明确的次数耗尽状态及显示,停止误报下一时段会重试;提供管理员填写依据、记录审计后单项重新入队的 API 和 UI。保留未知发送结果的人工核验要求,不自动重发未知批次。覆盖到达上限、修复 SMTP 后人工恢复、权限和重复提交。
- 助手脱敏:处理 JSON 中带引号的敏感键、嵌套字段和完整 Cookie/Authorization 头;统一用于模型输入、历史和诊断摘要。虚构凭据回归必须验证实际传给 runtime 和写入 store 的内容均已脱敏。
- 服务端口变化:每次启动业务子进程前重新读取并校验监听端口,守护探测与新实例保持一致;未知端口占用继续拒绝接管。真实子进程回归覆盖端口 A 改 B 后正常重启、不出现误杀循环。
- 中文自启动:替换 WScript.Shell 可能使用系统 ANSI 代码页的快捷方式路径处理,采用 Unicode 的创建及读取接口。当前用户权限、隐藏启动、外来快捷方式保护与安装状态验证保持原有约束。既有中文路径测试在本机代码页 1252 下必须通过。
路径与兼容性
- 集中计算项目资源根,逐项核对 __dirname 的引用。重点包括 Chrome 扩展复制、默认 PDF 输出、web 静态资源、SMB PowerShell 脚本、SMB worker、守护子进程入口与 cwd。
- scripts、启动工具.cmd 及 service 管理命令保持当前位置;只更新其内部导入。保留 src/server.cjs 的正式入口。
- Node/CJS、依赖版本、HTTP 路由、响应字段、Cookie 名称、SQLite 架构、运行状态位置及加密格式保持当前约定。
- 不为全部旧内部文件建立长期兼容包装,项目内代码和测试直接迁往新路径;已文档化的 CLI/正式启动入口保留。
实施和验证
- 先建立 shared/paths 和平台层,迁移加密、浏览器、服务守护及共享函数;验证加密兼容、真实子进程恢复及脚本定位。
- 迁移业务模块及其测试,拆分 notifications;逐模块跑既有隔离回归。
- 拆分 HTTP/启动职责与 BPM 登录表单交互,更新脚本、页面资源映射和前端文件位置;验证鉴权、生产/预览、实际本地 PDF 和浏览器页面。
- 将七项修复分别纳入对应模块;对实际故障边界先复现再修复,验证失败状态、重启、并发、取消和人工恢复出口。
- 整理 tests 目录、测试发现模式、README 与开发入口;全量测试并检查所有旧路径引用、工作区差异和模块依赖方向。
最新已运行基线:182 项,180 通过、1 失败、1 跳过。失败为本机代码页 1252 下中文快捷方式路径转换,本次必须修复;跳过为未配置真实官方 CLI 路径的 ZCode 协议夹具,保留明确说明。缺失的五项依赖在临时目录补齐,通过测试子进程 NODE_PATH 使用,不改实际运行依赖。
验收要求:项目已按上述模块组织;混合职责已实际拆开;启动、资源路径、原公开 API、持久数据和加密身份兼容;七项问题均有针对性验证,中文路径基线失败已修复;全量测试无失败;源码中不残留悬空的旧内部导入。正式服务与业务数据保持未操作。