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

单店 POS 闭环已进入打印硬化阶段

当前主线是把真实可用的单店流程打通：点单、厨房票、买单、后台配置、打印队列。最新稳定点已经完成 worker 按后台 printer routing 选择设备；下一步应继续推进打印可靠性、硬件 adapter 和队列管理，而不是切去大范围多店或平台集成。

Catalog/Admin72%
POS Order76%
Printing58%
Local DB40%
Payments35%
Online Orders12%
Multi-store22%
Workflow/QA85%

总体雷达

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

单店闭环

68%

点单、确认、厨房 queue、付款、账单 queue 已成主链路；还缺队列管理、异常恢复和真实硬件。

后台 Source of Truth

72%

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

打印系统

58%

queue、render、worker、routing 已完成；ESC/POS、LAN/USB/Windows adapter 和 retry 尚未完成。

本地运行可靠性

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 与 retry/backoff。

项目进度推进表

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

模块 进度 状态 已经完成 下一步 主要风险
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打印系统 58%
 当前主线 PrintJob queue、status machine、consumer、render adapter、printer settings、worker routing 已完成。 做 retry/backoff、stuck printing recovery、adapter registry、队列管理页，然后接 LAN ESC/POS。 硬件失败不能阻塞 confirm/payment；routing error 要可见、可重试。
Local Runtime / DB本地离线可靠性 40%
 明显缺口 core/local-service 边界清楚，transitional localStorage 可恢复 orders/print jobs。 定义本地 DB schema 和 repository 生命周期，把 orders、queue、admin settings 迁出 localStorage。 in-memory snapshot runtime 不能成为最终架构。
Payments支付 35%
 明显缺口 service-calculated full payment、payment snapshot、paid bill queue、paid amount display 已完成。 设计 PaymentProviderAdapter，比较 Square Terminal / Clover API，加入失败与取消语义。 不要把业务逻辑绑死到某一家支付商。
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 模糊架构决策。

建议继续开发顺序

按目前状态，打印可靠性比新业务线更能推进真实单店可用闭环。

P0

Print Queue Reliability

  • retry/backoff 与 attempt count
  • failed routing error 可视化与可重试
  • stuck printing recovery / worker lease 决策
P0

Print Queue Admin Page

  • 列出 pending / printing / failed / printed
  • reprint、mark failed、routing error 详情
  • 后台表格操作，不做 JSON 配置
P1

Real Adapter Foundation

  • 定义 adapter registry / transport boundary
  • 先接 network host/port + ESC/POS text
  • Windows printer 与 USB 后续独立模块
P1

Local DB Repository

  • orders / printJobs / admin settings 落本地 DB
  • 减少 localStorage 过渡层
  • 为 outbox/sync 留结构
P2

Payment Provider Adapter

  • Square / Clover capability matrix
  • terminal cancel / timeout / approved / declined 语义
  • 不要直接写进 UI handler
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。

开发节奏

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

最近稳定提交

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

d80d0a2

route print worker jobs to configured printers

25c74f0

add admin printer settings UI

256f153

bridge admin printer settings to store data

362132d

add printer settings store boundary

4876300

add print job rendering adapter boundary