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 已建立主边界，继续补真实设备同步与生产化边界。
当前活跃主题 本轮推进 POS 桌台订单恢复与 QR persisted metadata admin wiring；任何 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 前台点单 稳定推进
90%
 plain item、modifier/combo、line facts、confirm/print、payment/discount/Close 多条路径已接 local-service async opt-in；打开桌台现在可恢复 service 当前未付款订单并清理 stale 本地重复单。 还没有真正 iPad push/WebSocket；继续减少 snapshot-only 写路径，避免 UI sidecar 与 service facts 重新分裂。
Admin / Catalog 后台资料源 主边界已建立
76%
 AdminData -> StoreData、catalog、modifier、combo、库存、printer settings、桌台 QR admin 都有结构化边界。 还需要版本/发布语义、asset 字段、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 近期活跃
83%
 QR entry/cart、partial acceptance、modifier/combo options、table placards、registry validation、print/export、signed-token hardening、durable metadata、rotation preview、只读 metadata adapter 与 admin persisted metadata 状态接入已完成。 QR 顾客页还需要图像优先的购物车体验；不存 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 开发节奏 已建立控制面
94%
 Spec/plan/TDD、full test/typecheck/build/db validate、controller-agent、subagent 并行、每功能独立 commit、批次计划与 `npm run dashboard:check` 已写入。 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 主题的产品范围扩大。

最新切片快照：单店可用性批次

桌台订单恢复
  • `order.get_current_table` 从 local-service 返回当前桌台未付款 POS 订单。
  • 员工打开桌台时优先恢复 service 订单，并移除同桌 stale 本地重复单。
  • 这为 iPad/主机/QR 共享桌台事实打基础；真 push 还没有实现。
QR metadata admin wiring
  • `createConfiguredQrTokenMetadataRuntime()` 可从 sender、global config 或 HTTP endpoint 创建。
  • 后台 `桌台 QR` 现在显示 persisted metadata、loading、error 或 generated fallback 状态。
  • 仍然只读：不写 token、不 rotate、不保存 secret、不改变顾客扫码提交路径。
批次计划与 dashboard 控制
  • 本轮先提交 batch spec/plan，再分别提交 POS 桌台恢复与 QR metadata 功能。
  • 用户目标已写入 handoff：单店员工/客人真实点单，不为写 code 而写 code。
  • dashboard 仍可有最新 spotlight，但必须保留整个 POS 模块地图。

最新切片验证矩阵

已完成聚焦验证
  • `npm test -w @gaima-pos/local-service -- orderService localServiceRuntime localServiceTransport`。
  • `npm test -w @gaima-pos/pos-ui -- localServiceAsyncOrderRuntime visiblePosAsyncTableOpenFlow visiblePosAsyncOrderFlow visiblePosAsyncConfirmPrintFlow visiblePosAsyncPaymentCloseFlow visiblePosAsyncLineFactsFlow visiblePosAsyncModifierComboAddFlow`。
  • `npm test -w @gaima-pos/pos-ui -- qrTokenMetadataRuntime qrAdminPlacards`。
  • `npm run typecheck -w @gaima-pos/local-service` 与 `npm run typecheck -w @gaima-pos/pos-ui`。
最终全量验证已通过
  • `npm test`：core 42、local-service 208、pos-ui 252、sample-data 51。
  • `npm run typecheck` 通过。
  • `npm run build` 通过。
  • `npm run db:validate` 通过。
  • `npm run dashboard:check` 通过。
  • `git diff --check` 通过，仅 Windows LF/CRLF 提示。
仪表盘渲染已通过
  • 本页已通过本地 HTTP server 打开，HTTP 200。
  • 桌面 1440px 与移动 390px 都能读到全局 10 个模块、最新批次和 handoff prompt。
  • 两种视口都读到 Staff iPad 下一轮方向和 `a32c867` 当前功能 commit。
  • 无 console warning/error、无水平溢出、无 authored sticky/fixed CSS。
  • 本轮 batch plan、POS table resume、QR metadata wiring 已独立 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 进度替换成单一模块视图。

近期主线

提交 / 模块 意义
`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 batch spec/plan，以及 2026-05-24 QR token spec/plan。
  • 运行 `git status --short` 和 `git log --oneline -6`，确认 root `main` 是最新交接基线。
  • 运行 `npm run dashboard:check`，确认全局 POS 模块表仍在。
  • 先看本页的全局 POS 模块进度表，再选择当前主题；不要只按最新 QR spotlight 判断整个系统进度。
  • 记住用户目标：让单店员工和客人能真实完成点单、打印、付款、QR 或运营恢复，不为写代码而写代码。
  • 作为 controller-agent 制定一个同主题批次计划；可在较长 session 内并行推进多个互不依赖的合格功能。
  • 每个功能都要独立测试、独立 commit，commit 后检查 `git status --short`，再整合下一个功能。
  • 默认候选是 Staff iPad Table Live Status + QR Image-first Cart Readiness Batch；也可以按全局模块表切换到 Printing、Payments 或 Production/Ops，但必须先守住范围。
  • 停止前刷新 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`, and the 2026-05-24 QR token specs/plans, then run `git status --short`, `git log --oneline -6`, 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: `ef1264f docs: add single-store readiness batch plan`, `1a8040b feat: add service-backed table order resume`, and `a32c867 feat: wire qr metadata into admin placards`. Local-service now supports `order.get_current_table`; POS UI table opening can restore the current unpaid service-backed dine-in order and remove stale same-table local duplicates before fallback. Admin `桌台 QR` can read persisted QR token metadata through a configured browser-safe runtime and shows loading/error/generated-fallback states without writing tokens, rotating tokens, saving secrets, or changing QR customer submission. User product direction for upcoming batches: staff iPad should see table/order state update from guest QR orders and host/POS orders through shared local-service truth, and QR scan should become an image-first shopping-cart ordering page. Default next candidate should be Staff iPad Table Live Status + QR Image-first Cart Readiness Batch: decide a narrow polling/status-feed slice versus true WebSocket push later, and a narrow image-led QR cart UI slice, while keeping local-service validation authoritative. Keep hardware printing, payment providers, platform adapters, split-bill UI, WebSocket push claims, outbox replay, cloud sync, production SQLite packaging, new public deployment choices, and hosting architecture changes out of scope unless explicitly asked. 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.