docs: record approved modular refactor execution plan
This commit is contained in:
1 parent
2aed328774
commit
5fe42b478c
2 files changed
+250
No files matched your search
@@ -0,0 +1,82 @@
|
||||
# Modular refactor and seven robustness fixes Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox syntax for tracking.
|
||||
|
||||
**Goal:** Deliver the approved business-module architecture and close all seven reproduced failure paths.
|
||||
|
||||
**Architecture:** CommonJS modular monolith. Application owns lifecycle and dependency injection; business modules own API/service/store boundaries; platform and shared code own OS and cross-cutting facilities.
|
||||
|
||||
**Tech Stack:** Node >=22.13, existing SQLite/Playwright/SMTP dependencies, Windows PowerShell.
|
||||
|
||||
**Spec:** docs/superpowers/specs/2026-10-19-modular-refactor-design.md
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- Preserve public URLs, response fields, cookies and CLI entrypoints.
|
||||
- Preserve state paths, SQLite data, DPAPI identity, AAD and key names.
|
||||
- Keep dependencies unchanged; tests use NODE_PATH with original checkout and temporary review dependencies.
|
||||
- No real provider access, production process control or production data writes.
|
||||
- Worktree: C:/Users/ABS/.codex/worktrees/modular-refactor/Order Notification Automation.
|
||||
- No push, merge or deployment. Keep working result reviewable in this attached worktree.
|
||||
|
||||
## Task 1: Mechanical module migration and path foundations
|
||||
|
||||
**Files:** all existing src business files, web feature files, tests; scripts and package.json imports; new src/shared/paths.cjs.
|
||||
**Interfaces:** preserve exports, except notifications.cjs remains temporarily under modules/notifications until Task 3 splits it. PROJECT_ROOT/WEB_ROOT/SCRIPTS_ROOT/EXTENSION_ROOT exported by shared/paths.
|
||||
|
||||
- [ ] Inventory current tests and relative/resource path uses with rg.
|
||||
- [ ] Move files to approved directories; rewrite imports from resolved original absolute targets, including fixture paths. Keep src/server.cjs as current entry until Task 5. Move dashboard.cjs to app/dashboard.cjs. Temporarily place notifications.cjs at modules/notifications/notifications.cjs.
|
||||
- [ ] Centralize static roots. Preserve sibling worker lookup and server entry location; map old public web URLs to new physical files.
|
||||
- [ ] Change test discovery to recursive node --test pattern; verify all original 49 test files remain discovered.
|
||||
- [ ] Run module import checks and baseline suite. Expected only known Unicode shortcut failure and official CLI skip. Commit isolated migration.
|
||||
|
||||
## Task 2: Saved SMB bounded execution
|
||||
|
||||
**Files:** src/modules/storage/*, tests/storage/* and owned fixtures.
|
||||
**Interfaces:** StorageService public methods remain compatible. Worker runner accepts AbortSignal and deadline; SmbClient exposes cancellable bounded operations without passing secrets in command arguments.
|
||||
|
||||
- [ ] Add failure-first tests: hung saved list/check terminates; stop cancels active and queued operations; queue works after timeout; archive result preserves bytes; oversized/invalid IPC fails.
|
||||
- [ ] Execute targeted tests and capture failure before implementation.
|
||||
- [ ] Route saved operations through isolated worker, reuse FileArea guards, observe process exit on cancel/timeout, enforce binary response limits. Stop rejects queued tasks promptly.
|
||||
- [ ] Run storage suites including local fake-worker and archive integrity regressions; commit and report commands/results.
|
||||
|
||||
## Task 3: Notifications transaction boundary and manual recovery
|
||||
|
||||
**Files:** src/modules/notifications/{store,service,mapping,api}.cjs, web/modules/notifications/view.js, tests/notifications/*.
|
||||
**Interfaces:** NotificationStore.recover() explicit, NotificationStore.beginSending(batchId) transactional CAS; NotificationService retains existing API and adds retryItem(id,input,actor). API retains routes and adds admin retry with evidence/audit.
|
||||
|
||||
- [ ] Test constructing second store leaves active prepared batch/items unchanged; cancelled reservation fails beginSending and cannot reach SMTP.
|
||||
- [ ] Test final allowed SMTP failure becomes exhausted; next tick does not send; manual retry requires admin and evidence, audits, resets one item, rejects repeated submission.
|
||||
- [ ] Split mapping, transactions and SMTP orchestration into separate files. Recovery runs only explicitly after application ownership. Preserve unknown-result manual resolution rules.
|
||||
- [ ] Implement accurate exhausted display/action; test API and UI with local fixtures. Commit/report targeted results.
|
||||
|
||||
## Task 4: BPM/browser, shared redaction and Windows supervisor
|
||||
|
||||
**Files:** modules/bpm/session-manager.cjs and login-form.cjs; shared/redact.cjs; assistant/policy/service and health imports; platform/service/supervisor.cjs and windows-startup.cjs; scripts/service.cjs; relevant tests and fixtures.
|
||||
**Interfaces:** preserve manager.browser(), extract form helpers with unchanged login security; redact exported centrally; supervisor accepts validated fresh ports provider each launch; Unicode shortcut create/read retain ownership metadata.
|
||||
|
||||
- [ ] Test browser close then concurrent reconstruction launches exactly once, invalidates dead leases and ignores stale disconnect events; use real headless Chrome fixture.
|
||||
- [ ] Test nested quoted JSON password/cookie and complete Cookie/Authorization values are absent from actual runtime input and persisted history.
|
||||
- [ ] Test real managed child port A to B restart remains healthy, unknown occupants rejected.
|
||||
- [ ] Retain failing Chinese startup-path regression on codepage1252; replace shortcut COM ANSI path handling using Unicode IShellLinkW/IPersistFile, test readback and foreign ownership.
|
||||
- [ ] Implement minimal fixes and form responsibility extraction. Run owned suites, commit/report.
|
||||
|
||||
## Task 5: Application/HTTP responsibility split and ownership
|
||||
|
||||
**Files:** src/app/{application,bridge,dashboard,assets,request}.cjs; modules/dashboard/{api,auth}.cjs; platform/service/instance-lock.cjs; src/server.cjs; tests/app and tests/service.
|
||||
**Interfaces:** server exports main/createServer/startService; application acquires acquireInstanceLock(stateDir) before any business store construction and releases on all failure/shutdown paths. notificationStore.recover() called only with ownership acquired.
|
||||
|
||||
- [ ] Test second main on same temporary state fails before business recovery while first owns batch; first can send once and item becomes sent. Test startup failure releases ownership.
|
||||
- [ ] Split existing bridge/createServer from lifecycle, retain thin formal entry. Extract dashboard auth/business routes, request/security helpers and asset mapping with routing/auth order preserved.
|
||||
- [ ] Implement named-pipe ownership lock keyed by canonical state directory; avoid unsafe stale PID lockfiles. Make cleanup robust after partial initialization.
|
||||
- [ ] Run auth, HTTP, resources, browser navigation, startup and integration regressions; verify unchanged cookie/URL behavior. Commit/report.
|
||||
|
||||
## Task 6: Review and acceptance
|
||||
|
||||
**Files:** README/development docs/HANDOFF as relevant, all changed modules and tests.
|
||||
|
||||
- [ ] Independent task reviews and final whole-change review; route meaningful findings back to implementers and verify fixes.
|
||||
- [ ] Check no dangling old imports/resource paths; verify test discovery and encrypted persistence compatibility using temporary state.
|
||||
- [ ] Run full npm test with review NODE_PATH; require zero failures, document official CLI skip honestly.
|
||||
- [ ] Update design/plan progress and architecture documentation. Report exact results and untested real-provider limits; retain reviewable attached checkout.
|
||||
|
||||
@@ -0,0 +1,168 @@
|
||||
# 按业务模块组织代码:重构设计
|
||||
|
||||
日期:2026-10-19。状态:用户已批准实施。
|
||||
|
||||
## 目标与范围
|
||||
|
||||
将当前平铺在 src、web、tests 的代码整理为按业务边界组织的模块,并拆开承担多项职责的入口、路由、通知队列与浏览器登录代码。采用单进程模块化架构,保持 CommonJS、Node.js >=22.13、当前 HTTP 地址、启动命令、SQLite 格式、加密身份及业务规则。
|
||||
|
||||
本次交付为目录与职责重构,同时修复上一轮审查的全部七项问题。用户已明确要求一起完成。每项修复与所属模块一起实施并增加针对真实故障边界的回归测试。不得启动或重启正式服务、访问正式 BPM/SMB/邮箱或修改实际运行数据。
|
||||
|
||||
## 方案比较
|
||||
|
||||
1. 推荐:按业务模块纵向组织,模块内包含 API、服务、存储、策略或客户端;启动编排与底层平台单独组织。源码、页面和测试使用一致模块名,迁移后独立验证各模块。
|
||||
2. 只移动文件到文件夹:改动较小,但保留入口和混合类中的职责耦合,未充分满足本次“目录和职责”调整。
|
||||
3. 拆成多个 npm 包或微服务:增加发布、进程和依赖维护成本,当前单机工作台没有这类隔离需求。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```text
|
||||
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 的递归测试发现模式,核对测试文件与测试数量,避免迁移时漏跑。
|
||||
|
||||
## 七项问题的修复要求
|
||||
|
||||
1. 通知重复发送:在 application 打开/恢复业务数据库前取得状态目录独占运行权,前台和守护启动使用同一约束;失败启动必须释放本次资源。通知恢复从构造函数移到显式启动恢复阶段,进入 sending 时用事务核实批次及预留仍有效。回归覆盖第二实例启动失败不改活动通知,以及失效预留不能发信。
|
||||
2. 正式 SMB 操作:已保存服务器的检查、目录、文件、预览和归档统一通过有期限、可终止的工作进程;复用路径与权限检查,凭据只经 IPC,结果验证和大小上限保持约束。停止服务主动取消当前操作并结束排队任务;不以单纯 Promise.race 冒充底层 I/O 已结束。覆盖超时、取消、队列恢复、正常停止和归档完整性。
|
||||
3. BPM 浏览器断开:断开时清理对应浏览器缓存与失效租约,后续请求可在并发控制下重建;迟到的旧浏览器事件不能清理新的实例。真实无头浏览器测试覆盖关闭后重建,并保留租约和登录安全限制。
|
||||
4. 通知次数耗尽:增加明确的次数耗尽状态及显示,停止误报下一时段会重试;提供管理员填写依据、记录审计后单项重新入队的 API 和 UI。保留未知发送结果的人工核验要求,不自动重发未知批次。覆盖到达上限、修复 SMTP 后人工恢复、权限和重复提交。
|
||||
5. 助手脱敏:处理 JSON 中带引号的敏感键、嵌套字段和完整 Cookie/Authorization 头;统一用于模型输入、历史和诊断摘要。虚构凭据回归必须验证实际传给 runtime 和写入 store 的内容均已脱敏。
|
||||
6. 服务端口变化:每次启动业务子进程前重新读取并校验监听端口,守护探测与新实例保持一致;未知端口占用继续拒绝接管。真实子进程回归覆盖端口 A 改 B 后正常重启、不出现误杀循环。
|
||||
7. 中文自启动:替换 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/正式启动入口保留。
|
||||
|
||||
## 实施和验证
|
||||
|
||||
1. 先建立 shared/paths 和平台层,迁移加密、浏览器、服务守护及共享函数;验证加密兼容、真实子进程恢复及脚本定位。
|
||||
2. 迁移业务模块及其测试,拆分 notifications;逐模块跑既有隔离回归。
|
||||
3. 拆分 HTTP/启动职责与 BPM 登录表单交互,更新脚本、页面资源映射和前端文件位置;验证鉴权、生产/预览、实际本地 PDF 和浏览器页面。
|
||||
4. 将七项修复分别纳入对应模块;对实际故障边界先复现再修复,验证失败状态、重启、并发、取消和人工恢复出口。
|
||||
5. 整理 tests 目录、测试发现模式、README 与开发入口;全量测试并检查所有旧路径引用、工作区差异和模块依赖方向。
|
||||
|
||||
最新已运行基线:182 项,180 通过、1 失败、1 跳过。失败为本机代码页 1252 下中文快捷方式路径转换,本次必须修复;跳过为未配置真实官方 CLI 路径的 ZCode 协议夹具,保留明确说明。缺失的五项依赖在临时目录补齐,通过测试子进程 NODE_PATH 使用,不改实际运行依赖。
|
||||
|
||||
验收要求:项目已按上述模块组织;混合职责已实际拆开;启动、资源路径、原公开 API、持久数据和加密身份兼容;七项问题均有针对性验证,中文路径基线失败已修复;全量测试无失败;源码中不残留悬空的旧内部导入。正式服务与业务数据保持未操作。
|
||||
|
||||
Reference in new issue
Block a user