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 下单必须继续在同一张系统图里推进。
本轮真实推进 员工 iPad/POS overview 现在有 Table Activity 和 Pickup Queue，两块都可直接打开桌台或订单。
当前仍不是 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 打印与厨房票 队列可人工闭环，硬件待确认
78%
 PrintJob queue、status machine、routing、worker、retry/backoff、stuck recovery、adapter registry、后台队列页与手动 `mark_printing` claim 已完成。 真实 LAN ESC/POS、Windows printer、USB ESC/POS transport 仍需用户确认后单独做。
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` 已写入。本轮按 plan、staff activity、takeout queue、fallback fix、UI integration、dashboard docs 拆分。 dashboard 每次必须保留全局模块表；`dashboard:check` 失败时先修复全局模块表再继续。

最新切片快照：员工活动 + 取餐队列

员工 Table Activity
  • `staffOrderActivityFeed` 聚合 QR table activity、service table activity、sync failed 和 local table draft。
  • service feed 未回来时也能显示本地未结 dine-in 桌台草稿，避免员工面板空白。
  • POS dine-in overview 左侧新增活动面板，行可点击进入对应桌台。
Pickup Queue
  • `takeoutOrderQueue` 输出 active unpaid kanban orders，并按 overdue、due soon、ready、waiting 汇总。
  • Kanban overview 左侧新增取餐队列，行可点击进入订单。
  • 列表不再硬截断 6 条，忙时可滚动查看全部可处理订单。
并行批次控制
  • controller 创建 worktree 和 batch plan，subagents 分别实现 staff feed、takeout queue、review UI。
  • controller 负责修类型、整合、浏览器验证、独立 commit、dashboard 更新。
  • 最新 spotlight 只描述当前切片，全局 10 模块表必须保留。

本轮验证矩阵

已完成聚焦验证
  • `npm test -w @gaima-pos/pos-ui -- staffOrderActivityFeed takeoutOrderQueue visiblePosTableStatusFeed visiblePosTableStatusRefreshFlow`。
  • `npm run typecheck -w @gaima-pos/pos-ui`。
  • Playwright: 1024x768 和 1366x900 POS overview layout。
布局风险已处理
  • Table Activity 和 Pickup Queue 都是可滚动列表，不隐藏忙时后续条目。
  • table-map 改为自身滚动，旧布局里 x=950 的远端桌子在 1024 宽视口可滚入可见区。
  • 页面 document 没有横向 overflow。
最终门禁已通过
  • Full `npm test`：core 42、local-service 208、pos-ui 270、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。
  • 本 dashboard 已通过 desktop/mobile render QA，无 console warning/error、无 authored sticky/fixed CSS、无 document horizontal overflow。

并行执行与确认队列

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 进度替换成单一模块视图。

近期主线

提交 / 模块 意义
`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、本轮 spec/plan 与最近 2026-05-25 批次 spec/plan。
  • 运行 `git status --short`、`git log --oneline -10`、`npm run dashboard:check`。
  • 先看全局 POS 模块进度表，再选择当前主题；不要只按最新 spotlight 判断整个系统进度。
  • 默认下一个候选：Staff real-time transport design spike 或 POS order lifecycle consolidation，继续强化真实店内操作。
  • 不要直接开始真 push、checkout/payment、图片上传/存储、平台 adapter 或硬件打印，除非先设计并获得确认。
  • 每个功能独立测试、独立 commit，commit 后检查 `git status --short`，再整合下一个功能。
  • 停止前刷新 handoff docs、本 dashboard、全局模块表和用户确认项，并验证桌面/移动滚动。

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

Continue the POS Local DB + SQLite repository adapter mainline. Reply in Chinese. Start from root `D:\AI_Projects\POS System`, read `NEXT_AGENT.md`, `docs/STATUS.md`, `docs/MEMORY.md`, `docs/CHANGELOG.md`, `docs/project-overview-infographic.html`, `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-25-qr-table-checkout-staff-batch.md`, and `docs/superpowers/plans/2026-05-25-qr-table-checkout-staff-batch.md`, then run `git status --short`, `git log --oneline -10`, and `npm run dashboard:check` to confirm the handoff baseline and global dashboard guard are current. Treat `docs/project-overview-infographic.html` as a whole-POS control surface first: preserve and update the global module progress table for Local Runtime/DB, POS Order Entry, Admin/Catalog, Printing, Payments/Close, QR Ordering/Admin, Online/Platform Orders, Multi-store Publishing, Production/Ops, and Workflow/QA; latest staff/QR work may update spotlight sections but must not replace the global POS map. Run as controller-agent: controller owns scope, subagent prompts, integration, verification, docs/dashboard updates, and commits; use parallel subagents only for read-only work, review, verification, or disjoint implementation areas. A longer session may complete multiple independent qualified feature slices, but each feature must be independently tested, committed in its own focused commit, followed by `git status --short`, and mirrored in `NEXT_AGENT.md`, docs, and the dashboard with user-confirmation items called out. Current completed batch: `05084f9 docs: add staff activity takeout batch plan`, `b948b46 feat: add staff order activity feed`, `ad39751 feat: add takeout order queue projection`, `b8cfac5 fix: show local table drafts in staff activity`, and `ab3a7af feat: surface staff activity and pickup queue`. POS overview now shows actionable Table Activity and Pickup Queue side panels; this is still polling/read refresh plus local projection, not true WebSocket/push. Default next candidate: Staff real-time transport design spike or POS order lifecycle consolidation, keeping scope on real single-store staff/guest ordering without starting payment providers, hardware printing, or platform adapters unless confirmed. Ask before true WebSocket/push implementation, QR checkout/payment, real printer hardware, payment providers, platform adapters, split-bill UI, outbox replay, cloud sync, production SQLite packaging, new public deployment choices, or hosting architecture changes. Dashboard must remain Chinese-first. Every feature commit, handoff, or new-session prompt update must also update `docs/project-overview-infographic.html`, keep the dashboard prompt synchronized with `NEXT_AGENT.md`, preserve the global POS module table, run `npm run dashboard:check`, and verify desktop/mobile scroll rendering with no sticky/fixed overlay blocking content. Existing dashboard sync target is `https://gaima-pos-dashboard.pages.dev/`; sync it after local verification when the dashboard is meant to be user-visible. Before context exhaustion or stopping, refresh the handoff docs, update the dashboard, and include a copy-paste next-session prompt.