Pinned clarification frame

AI 待你拍板的问题

请按编号一次回复
  1. 锁过期：iPad 断线或关屏后，锁自动释放的 TTL/heartbeat 要多长？例如 30 秒、60 秒、120 秒。
  2. SQLite 实现栈：已确认 SQLite 可作为门店本地 DB，并可兼容 Docker 与未来平台 adapter；具体 driver/library、迁移工具和打包方式仍需拍板。
  3. 命令队列持久化：第一轮只做 local-service 内部快速串行 queue，还是同时落一张 durable command log？
  4. 本轮 DB 范围：先迁移 orders/printJobs/admin settings，还是也加入 table/session/lock tables？
  5. 语音输入：经理备注、关单原因和折扣原因要接 Typeless 还是先做系统内置语音输入？需要支持哪些语言？
  6. 付款详情展示：现场 POS 只显示付款方式+金额；历史订单详情里要展开哪些字段：tip/change、时间、员工、备注、分组 ID、经理原因？
  7. 扫码整批提交：一个 QR cart 里部分菜品校验失败时，要整批拒绝并提示客人，还是接受可下单项目并返回失败项目？
  8. 真实打印首个目标：LAN ESC/POS、Windows printer、USB ESC/POS，还是继续保留 manual/simulator adapter？
  9. 支付与平台订单：Square/Clover/Stripe、Uber/DoorDash/Fantuan 是否继续保持 P2，只预留 adapter/inbox 边界？
  10. 旧中文文档编码：部分历史 docs 在终端显示乱码；要不要另开 docs-only 编码清理模块？

已确认的内容会同步到下方“已确认决策”；未回答的问题不会被当成默认答案，也不会被偷偷扩大成新 scope。

已确认决策

这些是当前开发继续前进时可以当作约束的事实；没有列在这里的内容仍然需要你拍板。

Confirmed

本地运行边界

  • 每家店应该有自己的本地 DB。
  • 总部/总店 master data 可以在云端。
  • 电脑端 local-service 是本地订单、打印队列和本地 DB 的入口。
Confirmed

SQLite 兼容性

  • SQLite 可以作为门店本地轻量 DB；这是兼容性确认，不是否定 SQLite。
  • Docker 可以兼容：SQLite 文件放在 durable volume，local-service 仍是唯一 writer。
  • Uber/DoorDash/Fantuan adapter 可以兼容：平台订单通过 local-service command/inbox API 进入本地订单流。
  • SQLite 留在 local-service/repository 边界后面；UI、iPad、QR 和平台 adapter 都不直接写 DB 文件。
  • 第一版本地 DB 要保留可替换 adapter 边界，并使用事务、WAL、foreign keys、busy timeout、明确 migrations 和关键索引。
  • SQLite schema foundation 已在 local-service 落地：表、索引、PRAGMA 和 migration SQL 已可测试。
  • SQLite 不承担总部/多店云端 source of truth；总部数据和跨店同步仍是独立后续模块。
Confirmed

iPad 角色

  • iPad 不需要自己的 DB。
  • iPad 是电脑端 APP/local-service 的镜像或网页窗口。
  • iPad 下单命令传回电脑 local-service，再进入本地订单流。
Confirmed

多端协作

  • iPad 和电脑可以同时处理不同订单，互相不打扰。
  • 同一桌或同一订单需要锁定/占用显示，避免双端同时改同一份事实。
  • 第一轮锁定策略保持简单：另一端只读提示，不做经理强制接管；员工可直接提醒对方退出编辑。
  • 空桌被点开进入编辑时就锁定；已有订单的桌台可以两端查看，不应因为查看而锁住。
  • 同一桌加菜和多人扫码点菜允许并发 append-only；如果桌单不存在，local-service 原子创建/取得当前桌单再追加行。
  • 锁主要用于改已有菜、作废、折扣、换桌、并桌、付款等会改同一份事实的动作。
  • local-service 需要快速监听并串行处理写入任务。
Confirmed

付款与分单

  • 付款是多笔 payment records，不会自动清桌或归档订单。
  • 桌子/订单持续显示 balance owing；付款金额可以和当前欠额不完全匹配。
  • 付款过程中新增菜品会增加总额和欠额；Close 之前订单继续留在桌上。
  • Close 之后如果又有扫码下单，local-service 应创建新的当前桌单承载新单品。
  • balance owing 大于 0 时不允许 Close；必须先补付款或做明确的 Custom Discount/免单/坏账处理。
  • Custom Discount/免单/坏账需要经理权限，并记录原因和审计轨迹。
  • 卡机超收默认算小费；现金超收默认算找零。客人把现金找零留下来时，第一版不需要另行记录。
  • 付款记录在数据库里完整保存；现场 POS 付款页可以只显示付款方式和金额。
  • 历史订单详情按订单查看，并可以看到当时的付款与分单情况。
  • 备注和关单/折扣原因预留 Typeless-style 语音输入按钮，减少触控屏键盘输入。
  • 分单通过 A/B/C/D 等分组进行，菜品可以拖拽到不同分组。
  • 单个菜可以 split in half 或 split in N ways。
  • A/B/C/D 各自拥有独立 balance、payment records 和 Close。
  • A/B/C/D 组内允许多笔和混合付款，例如先现金再刷卡。
  • 未付或半付的分组也可以通过选中合并或合并全部，让另一个分组代付剩余金额。
  • 拆菜只影响付款分摊；原订单仍记录为一个菜，modifier、折扣、税、厨房票和作废记录不拆开重算。
  • 顶部 A 区域预留给未来客人自助拖拽分单。
Workflow

交接方式

  • 下一位 agent 先读 NEXT_AGENT.md。
  • dashboard 同步“已确认/未确认/进度”。
  • STATUS、MEMORY、CHANGELOG 继续作为长期状态来源。
Frozen

当前不扩张

  • 不直接进入真实 Uber/DoorDash/Fantuan API。
  • 不直接绑定支付供应商。
  • 不把真实打印硬件混进 Local DB 模块。
Needs Answer

下一拍板点

  • 锁 TTL 与断线恢复规则。
  • SQLite driver/library、migration、打包方式和第一轮 DB 表范围。
  • 付款历史字段、Typeless-style 语音输入和 QR cart 部分失败语义。

POS 总控开发看板 / 2026-05-18

单店 POS 闭环进入本地 DB 与多端协作阶段

当前主线仍然是把真实可用的单店流程打通：点单、厨房票、买单、后台配置、打印队列。最新稳定点已经补上 print queue retry/backoff、adapter registry 和队列管理页；同桌 QR/iPad/电脑 append-only 加菜 runtime 已先落在 local-service，下一步继续围绕本地 DB、session/lock 和 durable queue 拍板。

Catalog/Admin72%
POS Order76%
Printing72%
Local DB46%
Payments48%
Online Orders12%
Multi-store22%
Workflow/QA85%

架构漂移审计

基于初始 backend design、模块路线图、当前 package scripts、local-service/repository 和 Prisma schema 的快速取证。

Aligned

没有发现致命跑偏

  • 初始目标就是 shared catalog + 每店独立本地运行。
  • 打印队列、adapter、retry/admin 页面都服务单店闭环。
  • 真实支付、平台订单和多店发布仍未被抢先实现。
Drift Risk

最大风险是过渡层固化

  • POS UI 仍用 localStorage 保存 orders/printJobs。
  • local-service repository 目前仍是 in-memory。
  • Prisma/PostgreSQL 是 schema-only，不等于门店本地运行 DB。
Correction

下一步纠偏动作

  • 把本地 DB 明确归到电脑 local-service。
  • iPad 只作为 client，不复制 DB 或写文件。
  • 所有多端写入走 lock + command queue + repository。

总体雷达

百分比是基于当前文档与代码 checkpoint 的工程估算，用于总控取舍，不代表商业完工率。

单店闭环

68%

点单、确认、厨房 queue、付款、账单 queue 与后台队列管理已成主链路；还缺本地 DB、真实硬件和更完整的异常运营面。

后台 Source of Truth

72%

AdminData 到 StoreData 桥接稳定；catalog、printer settings 已进入结构化 action 路线。

打印系统

72%

queue、render、worker、routing、retry/backoff、失败原因、stuck recovery、adapter registry 和后台队列页已完成；ESC/POS 与 LAN/USB/Windows transport adapter 尚未完成。

本地运行可靠性

40%

service/repository 边界清楚，但长期持久化仍在 localStorage / in-memory 过渡层。

单店运营链路

当前最应该守住的是这条闭环，后续所有模块都应服务它。

1

点单录入

POS UI 已走 service command runtime，modifier/combo/discount/void 等关键路径逐步归位。

2

订单事实

Order facts 从 UI sidecar 迁入 core/local-service，付款金额和行状态由 service 计算。

3

厨房与账单队列

confirm/payment 会生成结构化 PrintJob，kitchen ticket 支持 lineIds 范围。

4

worker 渲染

due job 被标记 printing，render 后交给 adapter，成功或失败推进状态机。

5

设备路由

bill、customer copy、kitchen department 已按后台 printer routing 选择 device。

6

真实硬件

尚未接 ESC/POS、USB、LAN、Windows printer，也没有 discovery；adapter registry 边界已建立。

项目进度推进表

用筛选框快速看哪些模块可以继续开工。状态是面向开发总控的归类。

模块 进度 状态 已经完成 下一步 主要风险
Catalog / Admin Data后台资料源 72%
 已建立主边界 AdminData -> StoreData，catalog、modifier、combo、库存、printer settings 结构化命令。 改善 modifier UX、图片/二维码 asset 字段、发布版本语义。 不要回到 JSON/text config；AI action 也必须走结构化命令。
POS Order Entry前台点单 76%
 已建立主边界 点单、modifier/combo、确认、付款、折扣、行备注、下厨、作废请求多条路径已接 service runtime。 继续收束 non-POS fallback，补强桌台地图和异常状态处理。 UI sidecar 与 service facts 不能重新分裂。
Printing System打印系统 72%
 已建立主边界 PrintJob queue、status machine、consumer、render adapter、printer settings、worker routing、retry/backoff、stuck recovery、adapter registry 和队列管理页已完成。 先做 Local DB + Multi-client Runtime，把 orders、queue、admin settings 和 table/order lock 迁出 localStorage；真实硬件/ESC/POS 另开模块并先确认。 硬件失败不能阻塞 confirm/payment；routing error 要可见，retry metadata 要可追踪。
Local Runtime / DB本地离线可靠性 46%
 当前主线 core/local-service 边界清楚，已确认每店本地 DB、iPad 无 DB、电脑 local-service 统一写入；SQLite 可作为本地轻量 DB，并兼容 Docker volume 与未来平台 adapter；SQLite schema foundation、PRAGMA、migration SQL 和关键索引已落地。 选择 SQLite runtime driver/packaging，再实现 local-service repository adapter，把 orders/queue/admin settings 迁入本地 DB；QR cart 批量失败语义仍需拍板。 in-memory snapshot runtime 和 browser localStorage 不能成为最终架构；UI/iPad/QR 也不能直接写 SQLite；driver 选择不要渗透到业务服务。
Payments支付 48%
 Service slice done Service totals, legacy full-payment path, payment-record service entry, balance owing helper, manager discount guard, and explicit Close command now exist in local-service. Next user-visible slice: migrate POS UI payment screen to payment rows, balance owing, manager discount, and Close. Split groups, Typeless, provider adapters, and SQLite stay separate. Do not treat payment record as table clearing. Legacy POS UI payment button still needs migration.
Online Orders线上订单 12%
 后续阶段 source/channel 与 price level 已预留，scheduled dispatch 语义已开始清晰。 先设计 direct online order API，再做平台 adapter。 不要在单店闭环未稳时引入平台分单复杂度。
Multi-store Publishing多店发布 22%
 后续阶段 master scope 和复制到门店入口已存在。 补 publish/version、差异对比、发布到门店的审批语义。 多店只是配置发布方式，不能主导单店订单生命周期。
Workflow / QA开发节奏 85%
 已建立主边界 Superpowers spec/plan/TDD/docs/commit 流程稳定，全量 qa 最近通过。 保持每轮一个主模块，完成前跑全量验证并回写 STATUS/CHANGELOG/MEMORY。 不要用大杂烩 commit 模糊架构决策。

建议继续开发顺序

按目前状态，Local DB 与多端协作锁比新业务线更能推进真实单店可用闭环。

Done

Adapter Registry

  • 按 PrinterDevice.connection.type 分发 adapter
  • 缺少 registry 是永久配置失败
  • 已注册 adapter 的运行错误继续走 retry/backoff
Done

Print Queue Reliability

  • retry/backoff 与 attempt count 已接入
  • lastError 持久化，routing error 立即 failed
  • stuck printing recovery 已有单进程策略
Done

Print Queue Admin Page

  • 列出 pending / printing / failed / printed 等状态
  • 展示 retry metadata、lastError 和任务范围
  • 后台动作通过 runtime，不做 JSON 配置
P1

Local DB + Multi-client Runtime

  • 电脑 local-service 持有本地 DB
  • 同桌 append-only 加菜 runtime 第一片已完成
  • orders / printJobs / admin settings 迁出 localStorage
  • 补 client session、table/order lock 和快速命令 queue
P1

Real Transport Adapters

  • 基于现有 registry 接入 transport implementation
  • 硬件和 ESC/POS 需独立确认后再做
  • Windows printer 与 USB 后续独立模块
P0

Payment Records + Split Bill

  • local-service payment records, balance owing, manager discount, and Close guard are implemented.
  • Next: migrate POS UI payment screen off the legacy full-payment button.
  • payment records 和 balance owing 先行
  • A/B/C/D 分组、拖拽和按份拆菜
  • Close guard、经理审批、卡小费、现金找零、分组混合付款已确认；剩语音输入和历史详情字段
P2

Online / Multi-store

  • direct online API 再平台 adapter
  • publish/version 再做总部菜单规模化
  • 单店订单主线先稳定

架构边界提醒

这些是接下来开发时最容易被打破、也最值得反复检查的约束。

打印设置

  • Printer settings 是物理门店配置，不属于 master menu scope。
  • worker 必须读 repository routing，不能从 React state 推断。
  • 缺 route 可以 fallback；指向 disabled/missing device 要明确失败。

订单事实

  • 业务事实进入 core/local-service，UI sidecar 只保留显示与选择状态。
  • confirm/payment 不能重置已有 printing/printed/failed/reprint_requested job。
  • paid order 不再允许 confirm 生成 unpaid bill。

本地 DB / 多端

  • 每店一套本地 DB；iPad 不持有 DB。
  • local-service 是唯一写入入口，UI/iPad 只发命令。
  • 同一桌/同一订单要有锁；不同订单可以并行操作。
  • 同桌新增菜品按 append-only 处理；修改既有事实才进入锁/会话规则。

开发节奏

  • 先写 spec/plan，再 TDD 实现。
  • 每个模块完成前跑 test、typecheck、build、QA、db validate、diff check。
  • 完成后回写 docs 并做 focused checkpoint commit。

最近稳定提交

这条线说明当前项目正在沿打印系统闭环连续推进。

current

add table append plus payment records/close service slices

4e77683

add print adapter registry

8ed2e3b

add print queue reliability

d80d0a2

route print worker jobs to configured printers

25c74f0

add admin printer settings UI