GAIMA POS 全局项目控制台 / 2026-05-25
单店 POS 可用系统进度看板
本页必须始终展示整个 POS 系统的进度,而不是只展示最新 QR 或单一模块。当前产品目标是让单店员工和客人真实完成点单、厨房出单、付款关单、QR 下单和运营恢复;每轮开发都要推进这个闭环,并把需要用户确认的事项放在这里。
单店闭环主线
后台资料、前台点单、local-service/SQLite、打印队列、付款关单和 QR 下单必须继续在同一张系统图里推进。
本轮真实推进
后台 Print Queue 现在按恢复优先级分诊 failed、stuck printing、due reprint 与 due pending,员工 overview 仍保留只读队列压力提示。
当前仍不是 push
桌台和员工活动仍是 polling/read refresh 加本地投影,不是 WebSocket/subscription。不要在交付说明里误称实时推送。
待用户确认
真 push/WebSocket、QR checkout/payment、真实硬件打印、支付 provider、平台 adapter、hosting 架构变化仍需要确认。
全局 POS 模块进度
| 模块 | 状态 | 进度 | 说明 | 风险边界 |
|---|---|---|---|---|
| Local Runtime / DB 本地运行与 SQLite | 当前主线 | 96% |
SQLite schema/repository、command log、sessions/locks、long-lived runtime、transport/API、HTTP harness、async POS sender、`order.get_current_table` 与 QR token metadata read transport 已落地。 | catalog 仍有 in-memory delegate;生产 SQLite packaging、Electron/Docker driver policy 仍需确认;UI/QR/iPad 不得直接写 DB。 |
| POS Order Entry 前台点单 | 稳定推进 | 95% |
plain item、modifier/combo、line facts、confirm/print、payment/discount/Close 多条路径已接 local-service async opt-in;打开桌台可恢复 service 当前未付款订单;本轮增加员工 Table Activity panel。 | 仍是 polling/read refresh,不是真 push/WebSocket;继续减少 snapshot-only 写路径,避免 UI sidecar 与 service facts 重新分裂。 |
| Admin/Catalog 后台资料源 | 主边界已建立 | 79% |
AdminData -> StoreData、catalog、modifier、combo、库存、printer settings、桌台 QR admin 都有结构化边界;后台产品详情可预览 QR 图片/占位图。 | 还需要版本发布语义、真实图片资产管理/上传、catalog 持久化收口;`drive:*` 仍不是可渲染 QR 图片源。 |
| Printing Queue / Kitchen 打印与厨房票 | 队列可人工闭环,硬件待确认 | 82% |
PrintJob queue、status machine、routing、worker、retry/backoff、stuck recovery、adapter registry、后台队列页、手动 `mark_printing` claim、员工 overview 只读队列压力提示,以及后台恢复分诊/提示列已完成。 | 真实 LAN ESC/POS、Windows printer、USB ESC/POS transport、自动 stuck recovery 执行和多 worker lease 仍需用户确认后单独做。 |
| Payments / Close 支付与关单 | 本地语义可用 | 68% |
payment rows、Paid/Balance、manager discount、positive balance block Close、explicit Close 已落地并可 async opt-in。 | split bill、历史 settlement 细节、Square/Clover/Stripe provider adapter 仍是后续模块。 |
| QR Ordering / Admin 扫码点单与桌台 QR | 近期活跃 | 90% |
QR entry/cart、partial acceptance、modifier/combo options、image-first cards、admin asset preview、table placards、registry validation、print/export、signed-token hardening、durable metadata、rotation preview、只读 metadata adapter、桌台上下文 summary 已完成。 | 还需要真实菜单图片资产管线、顾客 UX 店内 QA、checkout/payment 决策;不存 secret、不写 rotation、不引入默认 signing key。 |
| Online / Platform Orders 平台订单 | 后续阶段 | 15% |
source/channel、price level、future adapter/inbox 方向已确认;本轮 Pickup Queue 可显示 active unpaid kanban order pressure,但不是平台 adapter。 | Uber/DoorDash/Fantuan adapter 不得直接写 SQLite;单店闭环稳定前不要扩大到真实平台接入。 |
| Multi-store Publishing 多店发布 | 后续阶段 | 22% |
master data / store-local DB 边界已确认,发布到门店的概念入口存在。 | publish/version、差异对比、审批语义未做;多店发布不能主导单店订单生命周期。 |
| Production / Ops 生产化与部署 | 待生产策略 | 38% |
开发 harness、Cloudflare dashboard、Docker/SQLite volume 兼容方向已确认。 | Electron/Docker packaging、service hosting shape、public deployment/hosting architecture 变化需要用户确认。 |
| Workflow / QA 开发节奏 | 已建立控制面 | 98% |
Spec/plan/TDD、controller-agent、subagent 并行、每功能独立 commit、`npm run dashboard:check` 已写入。本轮按 RED/GREEN、domain triage、Admin UI integration、dashboard docs 拆分。 | dashboard 每次必须保留全局模块表;`dashboard:check` 失败时先修复全局模块表再继续。 |
最新切片快照:打印队列恢复分诊
Admin Print Queue Triage
- `buildAdminPrintQueueTriage()` 把现有 `PrintJob[]` 分成 failed、stuck printing、reprint ready、pending due、scheduled 和 resolved。
- 后台 Print Queue 表格现在把需要处理的票据排在前面,并显示恢复摘要与恢复提示列。
- 推荐动作只复用已有 `mark_printing`、`mark_failed`、`request_reprint` 等 admin-safe action。
POS Overview 仍只读
- dine-in Table Activity 和 kanban Pickup Queue 侧栏保留 Print Queue attention 区块。
- 员工可以在 operational overview 里看到失败票、重印请求、到期待打票和打印中票。
- 队列状态操作仍只在后台 Print Queue 页完成,POS overview 不新增 action surface。
边界与工作流
- 本轮不做真实硬件打印、不做自动 stuck recovery 执行、不做 lease-safe worker、不做 WebSocket/push。
- controller 负责 plan、TDD、实现、浏览器验证、独立 commit、handoff docs 和 dashboard 更新。
- 下一轮可以继续做 POS order lifecycle consolidation 或 Staff print queue recovery/admin polish。
本轮验证矩阵
已完成聚焦验证
- RED `npm test -w @gaima-pos/pos-ui -- adminPrintQueue` 先失败于缺少 `buildAdminPrintQueueTriage()`。
- GREEN `npm test -w @gaima-pos/pos-ui -- adminPrintQueue` 通过,覆盖 recovery triage 排序和 input immutability。
- `npm test -w @gaima-pos/pos-ui -- adminPrintQueue staffPrintQueueAttention printQueueCommandRuntime`。
- `npm run typecheck -w @gaima-pos/pos-ui`。
- `npm run build -w @gaima-pos/pos-ui`。
- `git diff --check` 仅保留既有 Windows LF/CRLF working-copy warnings。
浏览器验证
- in-app Browser 登录 `http://127.0.0.1:5197/`,进入 Admin -> Print Queue,桌面能看到恢复摘要和“恢复提示”列。
- 390x844 mobile viewport 能滚动到 Admin Print Queue 恢复摘要,无 console warning/error、无 document horizontal overflow。
- POS overview Print Queue attention 仍为只读投影;本轮没有加入队列 action surface、push 或硬件打印。
最终门禁已通过
- Full `npm test` 覆盖 core、local-service、pos-ui、sample-data workspaces。
- `npm run typecheck`、`npm run build`、`npm run db:validate`、`npm run dashboard:check` 均通过。
- `git diff --check` 只允许既有 Windows LF/CRLF working-copy warnings。
- 本 dashboard 已通过 desktop/mobile render QA,无 console warning/error、无 authored sticky/fixed CSS、无 document horizontal overflow。
- 既有公开目标 `https://gaima-pos-dashboard.pages.dev/` 已同步并返回 HTTP 200,未改变 hosting 架构。
并行执行与确认队列
Controller 负责
- 先把一个产品主题拆成 2-4 个可验证 feature slice。
- 给 subagent 自包含 prompt:范围、文件归属、测试命令、禁止事项、输出格式。
- 逐个整合已验收 feature,复核 diff,跑 targeted verification,再单独 commit。
Subagent 可并行
- 适合 read-only audit、review、verification,或文件范围不重叠的实现任务。
- 不得并行改 shared handoff docs、dashboard、同一源码文件或同一生成产物。
- 不得回滚别人或用户的改动;遇到重叠范围要向 controller 汇报。
需要用户确认
- 公开部署/托管架构变化、支付或硬件供应商、生产 key policy。
- 平台 adapter、AI provider/model、cloud sync、WebSocket push、outbox replay。
- QR checkout/payment、图片上传/存储管线、任何越过当前 local-service/QR/table 主题的范围扩大。
架构护栏
local-service owns durable writes
SQLite 与 repository 写入仍属于 computer-side local-service。POS UI 只消费浏览器安全 helper、类型和明确 adapter,不直接触碰 DB。
活动流不是最终 origin schema
QR signal 仍使用现有 `qr-` line id convention。未来如果要审计、报表或支付归因,需要专门设计 line-origin metadata。
不是实时 push
员工 iPad/桌台图当前是 local-service read refresh 加本地投影。真 push/WebSocket 需要单独设计 transport、断线恢复、重复事件和 UI 状态。
commit 与 dashboard 纪律
每个通过验证的独立功能必须单独 commit,commit 后 worktree 必须干净。每次 feature commit、handoff 或 prompt 更新都同步本 HTML。
全局模块表不可删除
dashboard 是整个 POS 系统控制面。最新 feature 只能更新对应模块行和 spotlight 区域,不能把全局 POS 进度替换成单一模块视图。
近期主线
| 提交 / 模块 | 意义 |
|---|---|
| `bc9b380 feat: add print queue recovery triage` | 后台 Print Queue 增加恢复分诊,把 failed、stuck printing、due reprint、due pending 排到前面,并显示恢复摘要和只读恢复提示列。 |
| `3903d93 feat: surface print queue attention` | 员工 POS overview 的 Table Activity 与 Pickup Queue 侧栏显示只读 Print Queue attention,让失败、重印、到期待打和打印中票据进入运营视野。 |
| `7062dba feat: add staff print queue attention` | 新增 domain projection,把现有 `PrintJob[]` 转成 staff-facing summary 和 priority rows,不改变打印队列状态机。 |
| `9e15655 docs: add staff print queue attention plan` | 记录本轮 controller-agent/TDD 批次边界,明确不做硬件打印、队列 action surface 或真 push。 |
| `ab3a7af feat: surface staff activity and pickup queue` | 员工 POS overview 显示 Table Activity 和 Pickup Queue,工作人员可以从概览直接进入桌台或订单。 |
| `b8cfac5 fix: show local table drafts in staff activity` | 服务端 feed 未加载时,本地未结桌台草稿仍会出现在员工活动流,避免面板误显空白。 |
| `ad39751 feat: add takeout order queue projection` | 为 active unpaid pickup/takeout orders 提供 UI-ready queue rows 和 overdue/due-soon/ready/waiting 汇总。 |
| `b948b46 feat: add staff order activity feed` | 建立员工活动流 domain 边界,覆盖 QR table、service table、sync failed 和 local table draft。 |
| `05084f9 docs: add staff activity takeout batch plan` | 记录本轮平衡并行批次,继续要求 TDD、功能独立提交和全局 POS dashboard。 |
| `b82cc43 feat: flag qr orders in staff table feed` | 员工桌台 feed 能标出 QR-origin line count 和 staff alert。 |
| `176692d test: guard global dashboard module map` | 新增 `npm run dashboard:check`,把全局 POS 模块表从文档约定升级为可校验 guard。 |