GAIMA POS 全局项目控制台 / 2026-05-25

单店 POS 可用系统进度看板

本页必须始终展示整个 POS 系统的进度，而不是只展示最新 QR 或单一模块。当前产品目标是让单店员工和客人真实完成点单、厨房出单、付款关单、QR 下单和运营恢复；每轮开发都要推进这个闭环，并把需要用户确认的事项放在这里。

中文优先 whole-POS control surface global module table 单店闭环 Local DB POS Order Printing Payments QR/Admin controller-agent

单店闭环主线 后台资料、前台点单、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。

下一轮交接

下一位 Agent 先做

从 root `D:\AI_Projects\POS System` 进入项目，确认最新 main 或指定 worktree。
读取 `NEXT_AGENT.md`、三份 docs、dashboard、Staff Print Queue Attention、Staff Activity + Takeout，以及 Print Queue Admin/Reliability 既有 spec/plan。
运行 `git status --short`、`git log --oneline -10`、`npm run dashboard:check`。
先看全局 POS 模块进度表，再选择当前主题；不要只按最新 spotlight 判断整个系统进度。
默认下一个候选：POS order lifecycle consolidation，或继续做一个很窄的 Staff/Admin print queue recovery polish。
不要直接开始真 push、checkout/payment、自动 stuck recovery 执行、平台 adapter、硬件打印或生产 hosting 变化，除非先设计并获得确认。
每个功能独立测试、独立 commit，commit 后检查 `git status --short`，再整合下一个功能。
停止前刷新 handoff docs、本 dashboard、全局模块表和用户确认项，并验证桌面/移动滚动。

不要把 `.deploy/pos-dashboard-cloudflare/index.html` 当作项目状态提交；它只是本地部署/导出产物。

继续 POS Local DB + SQLite repository adapter 主线。请用中文回复。先从 root `D:\AI_Projects\POS System` 开始，读取 `NEXT_AGENT.md`、`docs/STATUS.md`、`docs/MEMORY.md`、`docs/CHANGELOG.md`、`docs/project-overview-infographic.html`、`docs/superpowers/specs/2026-05-25-staff-print-queue-attention-batch.md`、`docs/superpowers/plans/2026-05-25-staff-print-queue-attention-batch.md`、`docs/superpowers/specs/2026-05-25-staff-activity-takeout-batch.md`、`docs/superpowers/plans/2026-05-25-staff-activity-takeout-batch.md`、`docs/superpowers/specs/2026-05-18-print-queue-admin-page.md`、`docs/superpowers/plans/2026-05-18-print-queue-admin-page.md`、`docs/superpowers/specs/2026-05-18-print-queue-reliability.md`、`docs/superpowers/plans/2026-05-18-print-queue-reliability.md`，然后运行 `git status --short`、`git log --oneline -10`、`npm run dashboard:check`，确认交接基线和全局 dashboard guard 是当前状态。把 `docs/project-overview-infographic.html` 当作 whole-POS 控制面板：必须保留并更新 Local Runtime/DB、POS Order Entry、Admin/Catalog、Printing、Payments/Close、QR Ordering/Admin、Online/Platform Orders、Multi-store Publishing、Production/Ops、Workflow/QA 的全局模块进度表；最新 staff/printing/admin 切片只能更新 spotlight，不能替代全局 POS 地图。继续按 controller-agent 工作流推进：controller 负责范围、subagent prompt、集成、验证、docs/dashboard 更新和提交；只有在只读调研、复核、验证或文件范围不重叠的实现任务中使用并行 subagents。每个 feature 必须单独测试、单独提交，提交后运行 `git status --short`，并同步 `NEXT_AGENT.md`、docs 和 dashboard，明确列出需要用户确认的事项。本轮新增完成：`bc9b380 feat: add print queue recovery triage`；此前已完成：`9e15655 docs: add staff print queue attention plan`、`7062dba feat: add staff print queue attention`、`3903d93 feat: surface print queue attention`。Admin Print Queue 现在用 `buildAdminPrintQueueTriage()` 把 failed、stuck printing、due reprint、due pending 排到 scheduled/resolved 前面，并显示恢复摘要和只读恢复提示列；POS overview 仍只显示只读 Print Queue attention。这个工作不是真实硬件打印、不是自动 stuck recovery/lease-safe worker、不是 POS overview 队列 action surface，也不是 WebSocket/push。默认下一候选：POS order lifecycle consolidation，或继续做一个很窄的 Staff/Admin print queue recovery polish；不要未经确认开始真实 WebSocket/push、QR checkout/payment、真实打印硬件、支付 provider、平台 adapter、split-bill UI、outbox replay、cloud sync、production SQLite packaging、新公开部署或 hosting 架构变化。Dashboard 必须中文优先；每次 feature commit、handoff 或新 session prompt 更新都要同步 `docs/project-overview-infographic.html`，保持 dashboard prompt 与 `NEXT_AGENT.md` 一致，保留全局 POS 模块表，运行 `npm run dashboard:check`，并验证桌面/移动 dashboard 滚动没有 sticky/fixed overlay 阻挡内容。现有 dashboard 同步目标仍是 `https://gaima-pos-dashboard.pages.dev/`；仅在本地验证后、且 dashboard 应对用户可见时同步这个既有目标。停止前刷新 handoff docs、dashboard、全局模块表和用户确认项，并附上可复制的下一轮中文 prompt。