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、Workflow/QA 已建立主边界，继续补剩余 adapter 和生产化边界。
当前活跃主题 本轮同时推进 Printing、QR Ordering/Admin 与 Workflow/QA；任何 spotlight 都不能替代全局 POS 模块地图。
待用户确认 真实硬件打印、支付 provider、生产 key policy、平台 adapter、hosting 架构变化和范围扩大仍需你拍板。

全局 POS 模块进度

模块 状态 进度 说明 风险边界
Local Runtime / DB 本地运行与 SQLite 当前主线
95%
 SQLite schema/repository、command log、sessions/locks、long-lived runtime、transport/API、HTTP harness、async POS sender、QR token metadata storage 与只读 metadata transport 已落地。 catalog 仍有 in-memory delegate，生产 SQLite packaging / Electron-Docker driver policy 仍需确认；UI/QR/iPad 不得直接写 DB。
POS Order Entry 前台点单 稳定推进
88%
 plain item、modifier/combo、line facts、confirm/print、payment/discount/Close 多条可见路径已接 local-service async opt-in，并保留 snapshot fallback。 继续减少 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 近期活跃
80%
 QR entry/cart、partial acceptance、modifier/combo options、table placards、registry validation、print/export、signed-token hardening、durable metadata、rotation preview、只读 metadata adapter 已完成。 下一步才是 explicit key input 或 rotation semantics；不存 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 开发节奏 已建立控制面
92%
 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 主题的产品范围扩大。

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

员工打印队列闭环
  • `adminPrintQueue` 对 `pending` 和 `reprint_requested` 任务开放 `mark_printing`。
  • 后台打印队列按钮显示 `标为打印中`，之后继续用已打印、失败、重新排队。
  • 这是无硬件 worker 阶段的人工处理桥，不代表真实打印机 transport 已接入。
QR metadata 只读 adapter
  • `qr_table_tokens.list` 从 local-service 只读返回 persisted QR token metadata。
  • `createQrTokenMetadataRuntime()` 在 POS UI 浏览器安全层恢复 `Date` 字段并拒绝畸形 metadata。
  • 不写 token、不 rotate、不保存 signing secret、不改变顾客扫码提交路径。
dashboard 防漂移
  • `npm run dashboard:check` 检查全局 POS 模块表、NEXT_AGENT 与 MEMORY 的 dashboard 规则。
  • 这个 guard 是为了让每轮开发继续对齐单店可用系统，而不是滑成单一模块页面。
  • dashboard 仍可有最新 spotlight，但必须保留整个 POS 模块地图。

最新切片验证矩阵

已完成聚焦验证
  • `npm test -w @gaima-pos/pos-ui -- adminPrintQueue printQueueCommandRuntime`。
  • `npm test -w @gaima-pos/local-service -- localServiceTransport`。
  • `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 207、pos-ui 244、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。
  • 无 console warning/error、无水平溢出、无 authored sticky/fixed CSS。
  • 本轮三个合格功能已独立 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 进度替换成单一模块视图。

近期主线

提交 / 模块 意义
`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-24 三组 QR 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`，再整合下一个功能。
  • 默认候选仍可从 QR Admin Persisted Metadata Adapter 开始；也可以按全局模块表切换到 POS Order、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-24-qr-token-signing-rotation-persistence-hardening.md`, `docs/superpowers/plans/2026-05-24-qr-token-signing-rotation-persistence-hardening.md`, `docs/superpowers/specs/2026-05-24-qr-token-durable-storage-admin-ux.md`, `docs/superpowers/plans/2026-05-24-qr-token-durable-storage-admin-ux.md`, `docs/superpowers/specs/2026-05-24-qr-admin-rotation-readonly-preview.md`, and `docs/superpowers/plans/2026-05-24-qr-admin-rotation-readonly-preview.md`, 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: `87dc9cd feat: add manual print queue claim action`, `433fac0 feat: add qr token metadata read adapter`, and `176692d test: guard global dashboard module map`. Printing now supports a manual `mark_printing` bridge for pending/reprint jobs; QR metadata has read-only `qr_table_tokens.list` plus browser-safe parser; dashboard drift is guarded by `npm run dashboard:check`. POS UI generated placards and QR customer entry still use legacy deterministic tokens unless explicit signing config is supplied; QR customer cart option selection, `runQrCustomerCartSubmit()`, `order.append_qr_batch_to_table`, and local-service partial validation remain unchanged. Default next candidate should be chosen from the global POS module table according to real-store usefulness: POS Order, Printing, Payments/Close, QR Admin persisted metadata UI, or Production/Ops health/status are all valid narrow themes. Keep AI-assisted ordering, hardware printing, payment providers, platform adapters, split-bill UI, WebSocket push, 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.