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 下单必须继续在同一张系统图里推进。
本轮真实推进 POS 付款关单与账单预览现在更清楚地区分已付款账单、客人副本和收款动作，员工能知道 `Close + customer copy` 只是给客人收据，不会再记一次付款。
当前仍不是 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 打印与厨房票 队列可人工闭环，硬件待确认
84%
 PrintJob queue、status machine、routing、worker、retry/backoff、stuck recovery、adapter registry、后台队列页、手动 `mark_printing` claim、员工 overview 只读队列压力提示、后台恢复分诊、恢复 timing/detail copy，以及 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、POS paid bill/customer copy wording polish、浏览器 QA、dashboard docs 拆分。 dashboard 每次必须保留全局模块表；`dashboard:check` 失败时先修复全局模块表再继续。

最新切片快照：POS paid bill/customer copy wording polish

Ready-to-close Guidance
  • `buildOrderLifecycleReadiness().paymentCloseGuidance` 在零余额时明确提示 `Ready to close`。
  • Detail 现在说明：Close 会把订单标记为已付款；客人需要收据时使用 `Close + customer copy`。
  • 这沿用现有 Total/Paid/Balance 与 lifecycle facts，不新增支付动作或订单命令。
Bill Copy Guidance
  • `buildBillCopyGuidance(order, kind)` 从 `OrderDraft.printEvents` 与付款事实派生 unpaid bill、paid bill、customer-copy record 和 explicit customer copy 说明。
  • PrintDrawer 现在显示 `Payment is not recorded yet`、`Store receipt after Close`、`Customer copy recorded` 等用途文案。
  • customer copy 明确写明 `does not record another payment`，避免员工把收据副本误认为收款。
边界与工作流
  • 本轮只是 POS wording/readability polish，不改 receipt rows、print preview kind、Close handlers、print queue commands、真实硬件打印或 SQLite schema。
  • controller 负责 worktree、plan、TDD、实现、浏览器验证、独立 commit、handoff docs 和 dashboard 更新。
  • 下一轮默认转向 Admin Print Queue filter/action-confirm polish，或继续更窄的 POS receipt preview/customer-copy tab polish。

本轮验证矩阵

已完成聚焦验证
  • RED `npm test -w @gaima-pos/pos-ui -- orderLifecycleReadiness printing` 先失败于缺少 customer-copy wording/guidance。
  • GREEN `npm test -w @gaima-pos/pos-ui -- orderLifecycleReadiness printing` 通过，共 19 tests。
  • `npm test -w @gaima-pos/pos-ui -- orderLifecycleReadiness printing visiblePosAsyncPaymentCloseFlow visiblePosAsyncConfirmPrintFlow` 通过，共 29 tests。
  • `npm run typecheck -w @gaima-pos/pos-ui` 通过。
  • Feature commit `cb87d79 feat: clarify paid bill customer copy wording` 后 `git status --short` 为 clean。
  • Feature commit 后继续刷新 handoff docs 与 dashboard。
浏览器验证
  • 浏览器 QA：本地 Vite `http://127.0.0.1:5206`，登录 -> Dine In -> 加 item -> Confirm -> Payment Drawer。
  • 付款前显示 `Collect $31.62 before closing`；记录付款后显示 `Ready to close` 与 `Close + customer copy` guidance。
  • 点击 `Close + customer copy` 后，PrintDrawer 显示 `Customer copy recorded` 与不重复收款说明。
  • 桌面 viewport 无业务 console/page error、无 document horizontal overflow；截图保存到 `C:\Users\ROG\AppData\Local\Temp\gaima-pos-paid-copy-wording.png`。
最终门禁已通过
  • Full `npm test` 通过：core 42、local-service 208、pos-ui 288、sample-data 51。
  • `npm run typecheck`、`npm run build`、`npm run db:validate`、`npm run dashboard:check` 均通过。
  • `git diff --check` 通过，仅有预期 Windows LF/CRLF working-copy warnings；Node SQLite experimental warning 与 Vite large chunk warning 仍为既有噪音。
  • 本 dashboard 通过 desktop 1280x720 与 mobile 390x844 render QA：10-row global module table、spotlight、commits、bottom prompt 可达，无 authored sticky/fixed CSS、无 document horizontal overflow。
  • 既有 Cloudflare Pages dashboard `https://gaima-pos-dashboard.pages.dev/` 已同步并通过 HTTP/content check，未改变 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；停止前必须同步既有 Cloudflare Pages dashboard。

全局模块表不可删除

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

最终回复必须带 prompt

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

近期主线

提交 / 模块 意义
`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、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 判断整个系统进度。
  • 默认下一个候选：Admin Print Queue filter/action-confirm polish，或更窄的 POS receipt preview/customer-copy tab 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-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，明确列出需要用户确认的事项。本轮新增完成：`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`。POS ready-to-close guidance 现在明确提示全额付款后可关单，并在客人需要收据时使用 `Close + customer copy`；`PrintDrawer` 现在通过 `buildBillCopyGuidance()` 显示 unpaid bill、paid bill、paid bill with customer-copy record、explicit customer copy 的只读用途说明，例如 `Customer copy recorded` 与 `it does not record another payment`。这只是 wording/readability polish，不改变 payment rows、manager discount、Close / Close + customer copy handler、`recordSnapshotPrintEvent`、runtime/service command guard、print queue commands、真实硬件打印或 SQLite schema。默认下一候选：Admin Print Queue filter/action-confirm polish，或更窄的 POS receipt preview/customer-copy tab 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。