GAIMA POS 全局项目控制台

单店 POS 可用系统进度看板

本页必须始终展示整个 POS 系统的进度，而不是只展示最新 QR 切片。当前主线目标是把单店可用闭环打稳：后台资料、前台点单、本地 DB/local-service、厨房打印队列、付款关单、QR 下单、开发验证与待用户确认事项。

中文优先 root main handoff 全局模块进度 单店闭环 Local DB POS Order Printing Payments QR/Admin controller agent
单店闭环主线 后台资料、点单、local-service、SQLite、打印队列、付款关单和 QR 下单都必须在同一张系统图里可见。
当前最强区域 Local Runtime / DB、POS Order Entry、QR Ordering/Admin、Workflow/QA 已建立主边界，继续补真实设备同步与生产化边界。
当前活跃主题 本轮推进员工 iPad/POS 桌台状态读取刷新与 QR 图片优先购物车；任何 spotlight 都不能替代全局 POS 模块地图。
待用户确认 真 push/WebSocket、真实硬件打印、支付 provider、生产 key policy、平台 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 storage/read transport 已落地。 catalog 仍有 in-memory delegate，生产 SQLite packaging / Electron-Docker driver policy 仍需确认；UI/QR/iPad 不得直接写 DB。
POS Order Entry 前台点单 稳定推进
92%
 plain item、modifier/combo、line facts、confirm/print、payment/discount/Close 多条路径已接 local-service async opt-in；打开桌台可恢复 service 当前未付款订单，桌台图现在可周期读取 visible table 当前 service 订单并合并到状态。 本轮是 polling/read refresh，不是真 push/WebSocket；继续减少 snapshot-only 写路径，避免 UI sidecar 与 service facts 重新分裂。
Admin / Catalog 后台资料源 主边界已建立
77%
 AdminData -> StoreData、catalog、modifier、combo、库存、printer settings、桌台 QR admin 都有结构化边界；QR 顾客页已能读取 catalog item 的 `imageAssetId`。 还需要版本/发布语义、真实图片资产管理/上传、catalog 持久化收口；不要退回 JSON/text config。
Printing Queue / Kitchen 打印与厨房票 队列可人工闭环，硬件待拍板
78%
 PrintJob queue、status machine、routing、worker、retry/backoff、stuck recovery、adapter registry、后台队列页与手动 `标为打印中` 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 近期活跃
87%
 QR entry/cart、partial acceptance、modifier/combo options、image-first cards、table placards、registry validation、print/export、signed-token hardening、durable metadata、rotation preview、只读 metadata adapter 与 admin persisted metadata 状态接入已完成。 还需要真实菜单图片资产管线、顾客 UX 细节与店内 QA；不存 secret、不写 rotation、不引入默认 signing key。
Online / Platform Orders 平台订单 后续阶段
12%
 source/channel、price level、future adapter/inbox 方向已确认；平台订单应通过 local-service command/inbox 进入。 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 开发节奏 已建立控制面
95%
 Spec/plan/TDD、full test/typecheck/build/db validate、controller-agent、subagent 并行、每功能独立 commit、批次计划与 `npm run dashboard:check` 已写入；本轮按功能拆成 plan、staff、QR、dashboard commits。 dashboard 每次必须保留全局模块表；`dashboard:check` 失败时先修复全局模块表再继续。

并行执行与确认队列

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/local-service 主题的产品范围扩大。

最新切片快照：员工桌台刷新 + QR 图片购物车

员工 iPad/POS 桌台状态
  • 桌台图打开时会读取 visible table 的 `order.get_current_table`。
  • 返回的 service 订单会合并进本机 table status，并清理同桌 stale 本地重复单。
  • 这是 polling/read refresh，不是真 push/WebSocket；不能把它宣传成实时推送。
QR 图片优先购物车
  • QR 商品卡读取 nested catalog item 的 `imageAssetId`。
  • 只渲染安全图片源：`http(s)`、`/assets/...`、`data:image/...`。
  • `drive:*`、空值或 unsafe value 显示占位图，不输出坏 `<img>`。
并行批次控制
  • 本轮先提交 batch spec/plan，再分别提交 staff table refresh 与 QR image cart 功能。
  • QR 实现由 subagent 并行完成，controller review、验证后独立 commit。
  • 用户目标已写入 handoff：单店员工/客人真实点单，不为写 code 而写 code。
  • dashboard 仍可有最新 spotlight，但必须保留整个 POS 模块地图。

最新切片验证矩阵

已完成聚焦验证
  • `npm test -w @gaima-pos/pos-ui -- visiblePosTableStatusRefreshFlow visiblePosAsyncTableOpenFlow localServiceAsyncOrderRuntime`。
  • `npm test -w @gaima-pos/pos-ui -- qrMenuItemImages qrCustomerCartPage qrCustomerEntry qrCustomerOrderFlow`。
  • `npm run typecheck -w @gaima-pos/pos-ui`。
  • `git diff --check` 通过，仅 Windows LF/CRLF 提示。
最终全量验证已通过
  • `npm test`：core 42、local-service 208、pos-ui 260、sample-data 51。
  • `npm run typecheck` 通过。
  • `npm run build` 通过。
  • `npm run db:validate` 通过。
  • `npm run dashboard:check` 通过。
  • Node SQLite experimental warning 仍是既有运行时提示。
仪表盘渲染已通过
  • 本页通过本地 HTTP server 打开，HTTP 200。
  • 桌面 1440px 与移动 390px 都读到全局 10 个模块、最新批次和 handoff prompt。
  • 两种视口都读到 Staff table refresh、QR image cart 和 `f7c75d6` 当前功能 commit。
  • 无 console warning/error、无水平溢出、dashboard 源码无 authored sticky/fixed CSS。
  • 本轮 batch plan、staff table refresh、QR image cart 已独立 commit；handoff docs/dashboard 刷新作为独立 docs commit 收口。

架构护栏

local-service owns durable writes

SQLite 与 repository 写入仍属于 computer-side local-service。POS UI 只消费浏览器安全 helper、类型和未来明确 adapter，不直接触碰 DB。

secret 不进浏览器默认路径

signed token 需要显式 caller-provided signing keys。不要在 sample data、browser bundle 或 dashboard 里藏默认 signing secret。

controller-agent 边界

controller 负责拆分范围、分派子任务、审查结果和合并节奏；subagent 只处理已分配的窄功能，不跨模块改动。

commit 与 dashboard 纪律

每个通过验证的独立功能必须单独 commit；commit 后 worktree 必须干净。每次 feature commit、handoff 或 prompt 更新都同步本 HTML。

全局模块表不可删除

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

近期主线

提交 / 模块 意义
`f7c75d6 feat: make qr cart menu image first` QR 顾客菜单卡改成图片优先：安全图片源渲染 `<img>`，缺图或 unsafe asset 渲染占位，不改变购物车/提交路径。
`28e7301 feat: refresh table status from local-service` 员工桌台图可读取 local-service 当前桌单并合并到 table status，提供轮询/手动刷新，但不声称真 push。
`1d1f5ac docs: add staff ipad qr cart batch plan` 记录本轮平衡并行批次：员工 iPad 桌台状态刷新 + QR 图片购物车，并要求每功能独立 commit、dashboard 保持全局视角。
`a32c867 feat: wire qr metadata into admin placards` 后台 `桌台 QR` 接入 configured metadata runtime state，能显示 persisted/loading/error/generated fallback，仍保持只读安全边界。
`1a8040b feat: add service-backed table order resume` local-service 暴露 `order.get_current_table`，POS UI 打开桌台可恢复当前未付款 service 订单，减少员工 iPad/主机重复开单风险。
`ef1264f docs: add single-store readiness batch plan` 记录平衡并行模式、每功能独立 commit、全局 POS dashboard 更新，以及真实单店员工/客人点单目标。
`176692d test: guard global dashboard module map` 新增 `npm run dashboard:check`，把全局 POS 模块表从文档约定升级为可校验 guard。
`433fac0 feat: add qr token metadata read adapter` 通过 `qr_table_tokens.list` 和 browser-safe POS UI parser 只读获取 persisted QR token metadata。
`87dc9cd feat: add manual print queue claim action` 后台打印队列支持把待打印/重印待处理任务人工推进到打印中，补齐无硬件 worker 阶段的真实店内操作闭环。
`a8fbd58 feat: add qr admin rotation preview` 把只读 rotation metadata preview 与 operator key source boundary 接入后台。
`b91d403 feat: add qr token durable metadata storage` 把 QR token metadata 落到 local-service 与 SQLite repository 边界。
`a5af293 feat: add qr token signing hardening` 增加可选 signed token、rotation-aware registry 和 browser-safe snapshot helpers。
`a5988a3 feat: add qr admin print export polish` 后台 `桌台 QR` 增加浏览器打印、CSV 和 JSON 导出。

下一轮交接

下一位 Agent 先做
  • 从 root `D:\AI_Projects\POS System` 进入项目。
  • 读取 `NEXT_AGENT.md`、三份 docs、dashboard、2026-05-25 single-store 与 staff-ipad/QR image cart spec/plan。
  • 运行 `git status --short` 和 `git log --oneline -8`，确认 root `main` 是最新交接基线。
  • 运行 `npm run dashboard:check`，确认全局 POS 模块表仍在。
  • 先看本页的全局 POS 模块进度表，再选择当前主题；不要只按最新 QR spotlight 判断整个系统进度。
  • 记住用户目标：让单店员工和客人能真实完成点单、打印、付款、QR 或运营恢复，不为写代码而写代码。
  • 作为 controller-agent 制定一个同主题批次计划；可在较长 session 内并行推进多个互不依赖的合格功能。
  • 每个功能都要独立测试、独立 commit，commit 后检查 `git status --short`，再整合下一个功能。
  • 默认候选是 Staff Table Status Feed Hardening + QR Menu Asset Pipeline：继续强化“共享事实可见”和“真实顾客菜单图片”，但不要声称真 push/WebSocket，除非先做专门设计并获得确认。
  • 停止前刷新 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-single-store-readiness-batch.md`, `docs/superpowers/plans/2026-05-25-single-store-readiness-batch.md`, `docs/superpowers/specs/2026-05-25-staff-ipad-qr-image-cart-batch.md`, and `docs/superpowers/plans/2026-05-25-staff-ipad-qr-image-cart-batch.md`, then run `git status --short`, `git log --oneline -8`, and `npm run dashboard:check` to confirm root `main` and the 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 feature slices may update a spotlight section but must not replace the global module 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. User goal: prioritize real single-store staff/guest ordering usefulness, not code volume. Current completed batch: `1d1f5ac docs: add staff ipad qr cart batch plan`, `28e7301 feat: refresh table status from local-service`, and `f7c75d6 feat: make qr cart menu image first`. POS UI now reads local-service current table orders while the dine-in table map is visible, merges returned service orders into table status, and shows non-blocking sync/manual refresh state; this is polling/read refresh, not true push/WebSocket. QR customer menu cards are now image-first and use safe `item.item.imageAssetId` URLs with placeholders for missing, `drive:*`, or unsafe values; cart, modifier/combo, submit, and local-service partial validation are unchanged. Default next candidate: Staff Table Status Feed Hardening + QR Menu Asset Pipeline, keeping the work focused on shared table/order truth and real customer-facing menu photos. Ask before true WebSocket/push, 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.