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

单店 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 下单必须继续在同一张系统图里推进。

本轮真实推进 Admin Print Queue 现在能按 All、Needs attention、Failed、Stuck、Claimable、Active、Resolved 筛选，并在执行既有队列动作前显示确认说明。

当前仍不是 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 前台点单	稳定推进	98%	plain item、modifier/combo、line facts、confirm/print、payment/discount/Close 多条路径已接 local-service async opt-in；打开桌台可恢复 service 当前未付款订单；当前订单栏有 lifecycle readiness、action guards，Payment Drawer 现在显示 read-only payment/close guidance 与 customer-copy 下一步说明。	仍是 polling/read refresh，不是真 push/WebSocket；readiness/action guards/guidance 只是可见投影和按钮/文案 polish，不是新的订单写命令、payment provider、split bill、checkout 或第二次收款。
Admin/Catalog 后台资料源	主边界已建立	79%	AdminData -> StoreData、catalog、modifier、combo、库存、printer settings、桌台 QR admin 都有结构化边界；后台产品详情可预览 QR 图片/占位图。	还需要版本发布语义、真实图片资产管理/上传、catalog 持久化收口；`drive:*` 仍不是可渲染 QR 图片源。
Printing Queue / Kitchen 打印与厨房票	队列可人工闭环，硬件待确认	85%	PrintJob queue、status machine、routing、worker、retry/backoff、stuck recovery、adapter registry、后台队列页、手动 `mark_printing` claim、员工 overview 只读队列压力提示、后台恢复分诊、恢复 timing/detail copy、Admin Print Queue 筛选/动作确认，以及 POS bill/customer-copy 预览用途说明已完成。	真实 LAN ESC/POS、Windows printer、USB ESC/POS transport、自动 stuck recovery 执行和多 worker lease 仍需用户确认后单独做。
Payments / Close 支付与关单	本地语义可用	69%	payment rows、Paid/Balance、manager discount、positive balance block Close、explicit Close 已落地并可 async opt-in；Payment Drawer 会说明 collect balance、collect remaining、ready to close、already closed，并提示需要收据时使用 `Close + customer copy`。	split bill、历史 settlement/refund 细节、Square/Clover/Stripe provider adapter、QR checkout/payment 仍是后续模块；customer copy 文案不是第二次付款、不是支付 provider。
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` 已写入。本轮按 docs plan、RED/GREEN、Admin Print Queue filter/action-confirm polish、浏览器 QA、dashboard docs 拆分。	dashboard 每次必须保留全局模块表；`dashboard:check` 失败时先修复全局模块表再继续。

最新切片快照：Admin Print Queue filter/action-confirm polish

Queue Filter Projection

`buildAdminPrintQueueFilterOptions(triage)` 现在生成 All、Needs attention、Failed、Stuck、Claimable、Active、Resolved 的固定顺序筛选与计数。
`filterAdminPrintQueueTriageRows(rows, filter)` 返回不可变拷贝，保留已有 triage 排序，不改变 `PrintJob` 状态。
Admin Print Queue 默认聚焦 Needs attention，仍允许员工切回全部队列或查看 resolved 记录。

Action Confirmation Copy

`buildAdminPrintQueueActionConfirmation(job, action)` 为 `mark_printing`、`mark_printed`、`mark_failed`、`request_reprint` 生成确认标题和说明。
按钮在调用既有 `onAction(job.id, action)` 前先显示 `window.confirm()`，让员工知道动作影响。
`mark_printing` 文案明确这只是把票据标记为正在打印，不会自动触发真实硬件打印。

边界与工作流

本轮只是 Admin Print Queue 筛选/确认文案 polish，不改 `getAdminPrintQueueActions()`、`applyAdminPrintQueueAction()`、runtime command、worker/retry 或 SQLite schema。
controller 负责 worktree、plan、TDD、实现、浏览器验证、独立 commit、handoff docs 和 dashboard 更新。
下一轮默认转向更窄的 POS receipt preview/customer-copy tab polish，或 Admin Print Queue seeded-row browser/action-confirm QA polish。

本轮验证矩阵

已完成聚焦验证

RED `npm test -w @gaima-pos/pos-ui -- adminPrintQueue` 先失败于缺少 filter/action-confirm helpers。
GREEN `npm test -w @gaima-pos/pos-ui -- adminPrintQueue` 通过，共 10 tests。
`npm test -w @gaima-pos/pos-ui -- adminPrintQueue staffPrintQueueAttention printQueueCommandRuntime` 通过，共 20 tests。
`npm run typecheck -w @gaima-pos/pos-ui` 通过。
Feature commit `cce302d feat: clarify admin print queue filters and actions` 后 `git status --short` 为 clean。
Feature commit 后继续刷新 handoff docs 与 dashboard。

浏览器验证

浏览器 QA：本地 Vite `http://127.0.0.1:5208`，Admin login -> System -> Print Queue。
Print Queue tab 渲染 7 个 filter chips：All、Needs attention、Failed、Stuck、Claimable、Active、Resolved。
桌面 viewport 无业务 console/page error、无 document horizontal overflow；截图保存到 `C:\Users\ROG\AppData\Local\Temp\gaima-admin-print-queue-filter-action.png`。
当前 smoke 使用空队列验证筛选控件和页面稳定性；下一候选可做 seeded-row action-confirm browser QA。

交接门禁

Full `npm test` 通过：core 42、local-service 208、pos-ui 290、sample-data 51。
`npm run typecheck`、`npm run build`、`npm run db:validate` 均通过。
`npm run dashboard:check` 通过；本 dashboard 通过 desktop 1280x720 与 mobile 390x844 render QA：10-row global module table、spotlight、commits、bottom prompt 可达，无 console/page error、无 authored sticky/fixed CSS、无 document horizontal overflow。
`git diff --check` 通过，仅有预期 Windows LF/CRLF working-copy warnings；既有 Cloudflare Pages dashboard `https://gaima-pos-dashboard.pages.dev/` 已同步并通过 HTTP/content check，未改变 hosting 架构。
Node SQLite experimental warning 与 Vite large chunk warning 仍为既有噪音。

并行执行与确认队列

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；停止前必须同步既有 Cloudflare Pages dashboard。

全局模块表不可删除

dashboard 是整个 POS 系统控制面。最新 feature 只能更新对应模块行和 spotlight 区域，不能把全局 POS 进度替换成单一模块视图。

最终回复必须带 prompt

每次停下来或最终交接，都要附上可复制的下一轮中文 prompt，并保持它与 `NEXT_AGENT.md` 和本 dashboard 底部 prompt 完全一致。

近期主线

提交 / 模块	意义
`cce302d feat: clarify admin print queue filters and actions`	Admin Print Queue 现在显示 All / Needs attention / Failed / Stuck / Claimable / Active / Resolved 筛选，并在执行既有队列动作前显示确认说明。
`9a1eec9 docs: add admin print queue filter action plan`	记录 2026-05-26 Admin Print Queue filter/action-confirm polish 窄切片范围，明确不做硬件打印、自动恢复执行、worker lease、push 或 DB schema。
`cb87d79 feat: clarify paid bill customer copy wording`	POS ready-to-close guidance 与 PrintDrawer bill/customer-copy guidance 现在说明 `Close + customer copy` 是客人收据路径，不记录第二次付款。
`ddd048b docs: add paid bill customer copy wording plan`	记录 2026-05-26 POS paid bill/customer copy wording polish 窄切片范围，明确不做 payment provider、QR checkout/payment、split bill、硬件打印、push 或 DB schema。
`88df871 feat: clarify admin print queue recovery timing`	后台 Print Queue 恢复提示列现在显示失败原因、尝试次数、卡住时长、等待/逾期时间和稍后处理时间，不改变任何队列 action 或 worker 语义。
`aeaffd6 docs: add admin print queue recovery timing plan`	记录 2026-05-26 Admin Print Queue recovery timing polish 窄切片范围，明确不做真实硬件打印、自动恢复执行、worker lease、push 或 DB schema。
`d3c0a65 feat: add payment close guidance`	Payment Drawer 现在从 `buildOrderLifecycleReadiness().paymentCloseGuidance` 显示 collect balance、collect remaining、ready to close、already closed 等员工下一步文案。
`6ac668b docs: add payment close wording plan`	记录 2026-05-26 POS payment/close wording polish 窄切片范围，明确不做 provider、QR checkout/payment、split bill、refund/settlement、硬件、push 或 DB schema。
`cfa05a5 feat: add pos lifecycle action guards`	POS lifecycle readiness 现在返回只读 confirm/payment/close guard，OperationRail 和 PaymentDrawer 会禁用当前生命周期下不可用的动作。
`ba646dc docs: add pos lifecycle action guard plan`	记录 2026-05-26 POS Order Entry 窄切片范围，明确 action guards 只是按钮 polish，不是新订单命令、支付 provider、硬件、push 或 DB schema。
`29c53d1 feat: add pos order lifecycle readiness`	当前订单栏显示只读 lifecycle readiness，把 existing `OrderDraft` 阶段、下一步和 Total/Paid/Balance 聚合到员工视野。
`f33e6c0 docs: add pos order lifecycle readiness plan`	记录 2026-05-26 POS Order Entry 窄切片范围，明确不做支付 provider、QR checkout/payment、split bill、硬件、push 或 DB schema。
`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、Admin Print Queue filter/action-confirm、POS paid bill/customer copy wording、Admin Print Queue recovery timing、POS payment/close wording、POS lifecycle action guard/readiness、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 receipt preview/customer-copy tab polish，或 Admin Print Queue seeded-row browser/action-confirm QA polish。
不要直接开始真 push、checkout/payment、自动 stuck recovery 执行、平台 adapter、硬件打印或生产 hosting 变化，除非先设计并获得确认。
每个功能独立测试、独立 commit，commit 后检查 `git status --short`，再整合下一个功能。
停止前刷新 handoff docs、本 dashboard、全局模块表和用户确认项，验证桌面/移动滚动，部署既有 Cloudflare Pages dashboard，并在最终回复附上下一轮 prompt。

不要把 `.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-26-admin-print-queue-filter-action-confirm-polish.md`、`docs/superpowers/plans/2026-05-26-admin-print-queue-filter-action-confirm-polish.md`、`docs/superpowers/specs/2026-05-26-pos-paid-bill-customer-copy-wording-polish.md`、`docs/superpowers/plans/2026-05-26-pos-paid-bill-customer-copy-wording-polish.md`、`docs/superpowers/specs/2026-05-26-admin-print-queue-recovery-timing-polish.md`、`docs/superpowers/plans/2026-05-26-admin-print-queue-recovery-timing-polish.md`、`docs/superpowers/specs/2026-05-26-pos-payment-close-wording-polish.md`、`docs/superpowers/plans/2026-05-26-pos-payment-close-wording-polish.md`、`docs/superpowers/specs/2026-05-26-pos-order-lifecycle-action-guard.md`、`docs/superpowers/plans/2026-05-26-pos-order-lifecycle-action-guard.md`、`docs/superpowers/specs/2026-05-26-pos-order-lifecycle-readiness.md`、`docs/superpowers/plans/2026-05-26-pos-order-lifecycle-readiness.md`、`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 是当前状态。当前工作树是 `D:\AI_Projects\POS System\.worktrees\pos-order-lifecycle-action-guard` / branch `codex/pos-order-lifecycle-action-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 的全局模块进度表；最新 POS/staff/printing/admin 切片只能更新 spotlight，不能替代全局 POS 地图。继续按 controller-agent 工作流推进：controller 负责范围、subagent prompt、集成、验证、docs/dashboard 更新和提交；只有在只读调研、复核、验证或文件范围不重叠的实现任务中使用并行 subagents。每个 feature 必须单独测试、单独提交，提交后运行 `git status --short`，并同步 `NEXT_AGENT.md`、docs 和 dashboard，明确列出需要用户确认的事项。本轮新增完成：`9a1eec9 docs: add admin print queue filter action plan`、`cce302d feat: clarify admin print queue filters and actions`；此前已完成：`ddd048b docs: add paid bill customer copy wording plan`、`cb87d79 feat: clarify paid bill customer copy wording`、`aeaffd6 docs: add admin print queue recovery timing plan`、`88df871 feat: clarify admin print queue recovery timing`、`6ac668b docs: add payment close wording plan`、`d3c0a65 feat: add payment close guidance`、`ba646dc docs: add pos lifecycle action guard plan`、`cfa05a5 feat: add pos lifecycle action guards`、`f33e6c0 docs: add pos order lifecycle readiness plan`、`29c53d1 feat: add pos order lifecycle readiness`、`bc9b380 feat: add print queue recovery triage`。Admin Print Queue 现在通过 `buildAdminPrintQueueFilterOptions()` / `filterAdminPrintQueueTriageRows()` 显示 All、Needs attention、Failed、Stuck、Claimable、Active、Resolved 筛选，并通过 `buildAdminPrintQueueActionConfirmation()` 在执行既有 `mark_printing`、`mark_printed`、`mark_failed`、`request_reprint` 前说明动作影响；这只是后台筛选/确认文案 polish，不改变 `getAdminPrintQueueActions()`、`applyAdminPrintQueueAction()`、`PrintQueueCommandRuntime`、worker/retry 语义、POS overview queue attention、真实硬件打印或 SQLite schema。默认下一候选：更窄的 POS receipt preview/customer-copy tab polish，或 Admin Print Queue seeded-row browser/action-confirm QA polish；不要未经确认开始真实 WebSocket/push、QR checkout/payment、真实打印硬件、自动 stuck recovery 执行、支付 provider、平台 adapter、split-bill UI、outbox replay、cloud sync、production SQLite packaging、新公开部署或 hosting 架构变化。Dashboard 必须中文优先；每次 feature commit、handoff 或 new-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/`；停止/交接前必须在本地验证后同步这个既有 Cloudflare Pages 目标并做 HTTP/content check，除非用户明确说不要公开同步。停止前刷新 handoff docs、dashboard、全局模块表和用户确认项，同步 Cloudflare Pages，并在最终回复附上可复制的下一轮中文 prompt。