Jesssullivan/acuity-middleware

# scheduling-bridge 与后端无关的调度适配器中心。 Currently bridges Acuity Scheduling via Playwright 浏览器自动化，架构设计用于支持额外的调度后端。 ## 架构 一个封装 Playwright 向导流程的 HTTP 服务器，用于自动化 Acuity 预订 UI。该桥接器使用 Effect TS 进行资源生命周期管理（浏览器/页面获取与释放）。 ``` HTTP Request -> server/handler.ts (route matching, auth, JSON serialization) -> acuity-service-catalog.ts (static env catalog -> BUSINESS -> scraper fallback) -> steps/ (Effect TS programs for each wizard stage) -> browser-service.ts (Playwright lifecycle via Effect Layer) -> selectors.ts (CSS selector registry with fallback chains) ``` ### 关键组件 - **server/handler.ts** — 独立的 Node.js HTTP 服务器，支持 Bearer 令牌认证 - **acuity-service-catalog.ts** — 服务来源顺序与缓存，用于静态配置、业务数据提取和抓取降级 - **browser-service.ts** — Effect TS 层，用于共享的预热浏览器进程以及请求作用域的页面会话 - **acuity-wizard.ts** — 完整的 `SchedulingAdapter` 实现（本地 Playwright 或远程 HTTP 代理） - **remote-adapter.ts** — 用于代理到远程中间件实例的 HTTP 客户端适配器 - **selectors.ts** — 所有 Acuity DOM 选择器的单一事实来源 - **steps/** — 独立的向导步骤程序以及业务数据提取助手 - **acuity-scraper.ts** — 已废弃的读降级方案，用于服务、日期与时段 ## 端点 | 方法 | 路径 | 描述 | |------|------|------| | GET | `/health` | 健康检查（无需认证） | | GET | `/services` | 通过 `SERVICES_JSON` -> 业务数据 -> 抓取降级 列出预约类型 | | GET | `/services/:id` | 获取特定服务 | | POST | `/availability/dates` | 服务的可用日期 | | POST | `/availability/slots` | 指定日期的时间段 | | POST | `/availability/check` | 检查时段是否可用 | | POST | `/booking/create` | 创建预订（标准流程） | | POST | `/booking/create-with-payment` | 创建带支付的预订（优惠券绕过） | ### 健康协议 `GET /health` 是稳定的下游运行时真实反馈接口。 除了基础运行时数据外，现在还发布： - 发布元组： - `releaseSha` - `releaseRef` - `releaseVersion` - `releaseBuiltAt` - 嵌套 `release.{ sha, ref, version, builtAt, modalEnvironment }` - 协议元组： - `protocolVersion` - 嵌套 `protocol.version` - `protocol.flowOwner = "scheduling-bridge"` - `protocol.backend = "acuity"` - `protocol.transport = "http-json"` - `protocol.endpoints` - `protocol.capabilities` 下游应用应使用该元组在测试验证和发布声明期间断言所交互的桥接器版本与协议表面。 ## 环境变量 | 变量 | 是否必需 | 默认值 | 描述 | |------|----------|--------|------| | `PORT` | 否 | `3001` | 服务器端口 | | `ACUITY_BASE_URL` | 否 | `https://MassageIthaca.as.me` | Acuity 调度页面 URL | | `AUTH_TOKEN` | 推荐 | — | 所有端点的 Bearer 令牌（/health 除外） | | `ACUITY_BYPASS_COUPON` | 用于支付绕过 | — | 100% 礼品卡代码 | | `PLAYWRIGHT_HEADLESS` | 否 | `true` | 无头模式运行浏览器 | | `PLAYWRIGHT_TIMEOUT` | 否 | `30000` | 页面操作超时（毫秒） | | `CHROMIUM_EXECUTABLE_PATH` | 否 | — | 自定义 Chromium 路径（用于 Lambda/Serverless） | | `CHROMIUM_LAUNCH_ARGS` | 否 | — | 逗号分隔的 Chromium 参数 | | `SERVICES_JSON` | 否 | — | 可选的静态服务目录，用于绕过实时 Acuity 读取 | | `ACUITY_SERVICE_CACHE_TTL_MS` | 否 | `300000` | 缓存实时服务目录的 TTL，之后触发 BUSINESS/抓取刷新 | | `MIDDLEWARE_RELEASE_SHA` | 否 | — | 通过 `/health` 暴露的发布提交 SHA | | `MIDDLEWARE_RELEASE_REF` | 否 | — | 通过 `/health` 暴露的发布引用/标签 | | `MIDDLEWARE_RELEASE_VERSION` | 否 | — | 通过 `/health` 暴露的发布版本 | | `MIDDLEWARE_RELEASE_BUILT_AT` | 否 | — | 通过 `/health` 暴露的构建时间戳 | | `MIDDLEWARE_BUILD_TIMESTAMP` | 否 | — | 用于 `/health` 的遗留构建时间戳降级 | ## 部署 ### 独立 Node.js ``` pnpm install pnpm dev # Development with tsx against src/server/handler.ts # 或 pnpm build && pnpm start # Production via dist/server/handler.js ``` ### Docker ``` docker build -t scheduling-bridge . docker run -p 3001:3001 \ -e AUTH_TOKEN=your-secret-token \ -e ACUITY_BASE_URL=https://YourBusiness.as.me \ -e ACUITY_BYPASS_COUPON=your-coupon-code \ scheduling-bridge ``` ### Modal Labs ``` # 首先在 Modal 仪表板中设置密钥： # AUTH_TOKEN, ACUITY_BASE_URL, ACUITY_BYPASS_COUPON # Modal 镜像构建与 pnpm start 相同的 dist/server/handler.js 工件。 modal deploy modal-app.py ``` ### Nix ``` nix develop # Enter dev shell with Node.js + Playwright pnpm install pnpm dev ``` ## 发布权限 当前实际情况： - 功能发布仓库为 `Jesssullivan/acuity-middleware` - npm 发布目标为 `@tummycrypt/scheduling-bridge` - GitHub Packages 发布目标为 `@jesssullivan/scheduling-bridge` 当前收敛工作： - 本地分支 `fix/bridge-kit-070` - 包元数据升级至 `0.4.1` - 依赖对齐至 `@tummycrypt/scheduling-kit ^0.7.0` 从长远来看，预期的发布形态为： 1. 发布元组声明一次 2. Bazel 验证/构建可发布的构件 3. GitHub Actions 发布该构件 4. 下游应用仅消费发布的包 目前尚未完全实现。今天发布通道仍以 pnpm/npm 优先。 ## 开发 ``` pnpm install # Install dependencies pnpm dev # Start dev server with tsx pnpm typecheck # Run TypeScript type checking pnpm build # Compile TypeScript to dist/ pnpm test # Run tests ``` ## 许可证 MIT

标签：Acuity迁移, API迁移, Bearer令牌认证, CSS选择器, Effect TS, HTTP服务器, MITM代理, Node.js后端, Playwright自动化, Scheduling Adapter, SEO关键词, TypeScript, UI自动化, 中间件, 健康检查, 可用性查询, 安全插件, 服务编排, 浏览器自动化, 特征检测, 自动化攻击, 调度迁移, 资源生命周期管理, 零停机迁移