62 lines
5.8 KiB
Markdown
62 lines
5.8 KiB
Markdown
# 架构说明
|
||
|
||
## 为什么选 Electron
|
||
|
||
本项目的主要复杂度不是绘制桌面窗口，而是长期维护多个非统一的微信小程序接口：不同签名方式、Cookie、请求头、代理、登录状态和多步骤预约流程。Electron 主进程可以直接复用 Node.js 网络生态，并与 Chromium 渲染层保持清晰隔离，能以最低的适配成本覆盖这些差异。
|
||
|
||
Tauri 的安装包更小、空闲内存通常更低，但它会把接口适配层拆成 Rust 命令或 sidecar。当前业务没有强约束要求最小包体，却明确要求持续定制多个 JavaScript/HTTP 流程，因此 Electron 的开发与排障成本更低。
|
||
|
||
## 运行边界
|
||
|
||
```text
|
||
React renderer
|
||
| typed window.tennisBook API
|
||
Preload allowlist
|
||
| ipcRenderer.invoke
|
||
Electron main process
|
||
| AdapterRegistry + CourtSettingsStore
|
||
CourtAdapter A / CourtAdapter B / ...
|
||
| HTTP, cookies, signatures, booking workflow
|
||
微信小程序后端 API
|
||
```
|
||
|
||
渲染层只知道统一的 `CourtSummary` 和 `AvailabilityDay`。某个球场的原始响应、鉴权和预约步骤不能穿过 IPC 边界。
|
||
|
||
`AvailabilityDay` 可包含界面明确需要展示的预约人昵称和手机号，但适配器必须从第三方原始响应中逐项提取，不能把原始预约对象整体穿过 IPC；这些信息只保留在当前查询的内存状态中，不记录、不缓存、不落盘。
|
||
|
||
preload 必须构建为 CommonJS `.js`。项目启用了 Electron renderer sandbox，而 sandboxed preload 没有 ESM 上下文；不能通过关闭沙箱来迁就 `.mjs` 构建产物。
|
||
|
||
## 每球场运行时配置
|
||
|
||
`PSPLVISITORID` 等运行时凭证按 `courtId` 独立存储在 Electron `userData` 目录。范思伯特福中福的场地 ID 固定为适配器私有常量，只在请求边界映射到第三方 `userId` 字段和 `STOREID` 请求头，不经过 IPC，也不在配置界面暴露。设置弹窗通过专用白名单 IPC 读取凭证原值并回填密码框，默认遮挡；关闭弹窗立即清除渲染层中的输入值和设置对象，其他查询及预约接口不返回凭证。
|
||
|
||
可订列表刷新链路不读取球场凭证，`CourtAdapter.getAvailability()` 也不接收运行时设置，从类型边界保证列表请求不能携带 `PSPLVISITORID`。只有下单和释放写操作在主进程互斥区内读取最新凭证。
|
||
|
||
配置文件使用临时文件加重命名的方式原子替换。共享层始终用字符串表达外部 ID，避免超出 JavaScript 安全整数范围；具体适配器负责校验接口是否接受该范围并转换为请求格式。
|
||
|
||
应用对外显示名称为 `Tennis Book`，但 Electron `userData` 固定为 `appData/tennis-book`。显示名称与持久化路径解耦，避免品牌名称或大小写变化后配置、待支付订单和监控任务看似丢失。
|
||
|
||
## 接入一个新球场
|
||
|
||
1. 在 `src/main/adapters/<court-id>/` 创建适配器。
|
||
2. 实现 `CourtAdapter` 的 `court` 与 `getAvailability()`。
|
||
3. 在适配器内部完成原始响应到共享模型的转换。
|
||
4. 将适配器加入 `src/main/adapters/registry.ts`。
|
||
5. 为登录失效、空数据和接口字段变化添加契约测试。
|
||
|
||
## 预约写操作
|
||
|
||
公共预约状态机为：`可订 -> 二次确认 -> 重新查询校验 -> 结果待确认记录 -> 下单锁场 -> 待支付 -> 取消释放/支付完成`。具体请求体、版本头、访客凭证和响应解析只存在于球场适配器中。所有写操作按球场在主进程串行化，待支付或结果不确定期间禁止修改该球场凭证。
|
||
|
||
下单前由主进程重新查询同一天的数据，并使用重新查询得到的场地 UID、时间和价格构造请求，拒绝已订、排课和活动报名时段。渲染层传入的价格只作为用户确认金额；如与最新价格不同则拒绝下单并要求重新确认。第三方 UID 不接受渲染层输入。
|
||
|
||
范思伯特福中福的 `SaveVenueAppointmentV2` 只创建待支付订单并锁场，不代表支付成功。支付脚本不经过 IPC、不记录日志、不落盘；待支付订单的非敏感摘要按球场持久化，以便应用重启后仍能恢复“取消释放”入口。POST 发送前先持久化结果待确认记录，网络超时或响应解析失败时保留“尝试释放”入口，避免生成不可恢复的孤儿锁场。
|
||
|
||
`CrmAutoReleaseVenueAppoint` 使用当前球场配置与空 JSON 请求体释放当前访客的锁场，并不能绑定订单号。发送释放请求前先持久化 `release-uncertain`；若响应超时或进程中断，系统禁止自动重试，用户必须在小程序核实后显式清理本机记录。远端确认释放后先持久化 `release-confirmed` 标记，再删除摘要，避免清理失败后重复调用全局释放接口。支付脚本的过期时间只用于展示，不作为场地锁已经释放的依据。
|
||
|
||
## 空场监控
|
||
|
||
监控任务由主进程持久化和调度，应用通过单实例锁避免重复调度。日期可指定为创建时的今日或明日，也可以留空。指定日期的任务到达当天结束时间后自动停用；未指定日期的任务持续滚动检查主界面当前支持的未来 7 天，跨日后自动向后滚动一天且不会过期。轮询间隔固定为 10 秒；今日已经结束的指定日期范围不能创建。相同球场和日期的请求在同一轮中复用，并分别过滤 `available/limited` 时段。
|
||
|
||
任务持久化上一次可订时段 ID 集合，只对新增 ID 通知；同一时段持续可订时不会重复通知，先消失再重新出现则再次通知。暂停和删除会让在途响应失效。提醒同时使用 Electron 系统通知和主进程待消费队列中的应用内提示，渲染器启动较晚或同轮出现多条提醒时也不会覆盖；提醒不自动下单。带 `enrollment` 报名活动的时段属于已订场地，即使上游同时返回可预约标记，也必须从可订统计和监控提醒中排除。
|