From 5fe42b478c94455b2eabb91dda76a8f46cd894c4 Mon Sep 17 00:00:00 2001 From: abaishu0730 Date: Mon, 19 Oct 2026 08:48:45 +0800 Subject: [PATCH] docs: record approved modular refactor execution plan --- .../plans/2026-10-19-modular-refactor.md | 82 +++++++++ .../2026-10-19-modular-refactor-design.md | 168 ++++++++++++++++++ 2 files changed, 250 insertions(+) create mode 100644 docs/superpowers/plans/2026-10-19-modular-refactor.md create mode 100644 docs/superpowers/specs/2026-10-19-modular-refactor-design.md diff --git a/docs/superpowers/plans/2026-10-19-modular-refactor.md b/docs/superpowers/plans/2026-10-19-modular-refactor.md new file mode 100644 index 0000000..d3c063f --- /dev/null +++ b/docs/superpowers/plans/2026-10-19-modular-refactor.md @@ -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. + diff --git a/docs/superpowers/specs/2026-10-19-modular-refactor-design.md b/docs/superpowers/specs/2026-10-19-modular-refactor-design.md new file mode 100644 index 0000000..9e52baf --- /dev/null +++ b/docs/superpowers/specs/2026-10-19-modular-refactor-design.md @@ -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、持久数据和加密身份兼容;七项问题均有针对性验证,中文路径基线失败已修复;全量测试无失败;源码中不残留悬空的旧内部导入。正式服务与业务数据保持未操作。 +