POS Local DB + SQLite Repository Adapter

控制代理并行推进看板

本页是中文优先的项目控制台。后续开发默认由 controller agent 统一拆分、分派和收敛工作；互不依赖的功能可由 subagent 并行实现、测试和复查。每个合格功能必须形成独立 commit，停止前保持 worktree clean，并把待用户确认事项显式留在看板。

中文优先 root main handoff controller agent parallel subagents 每功能独立提交 worktree clean 待用户确认

总控代理 主 agent 负责范围、subagent prompt、整合、验证、docs/dashboard 与 commit，不把决策只留在聊天里。

并行子代理 只在 read-only、review、verification 或不重叠实现范围内并行；不得同时改同一文件或 dashboard。

每功能一提交 每个合格功能独立测试、独立 commit；commit 后运行 `git status --short`，保持相关 worktree clean。

待用户确认 公开部署变化、托管选择、支付/硬件供应商、生产 key policy、平台 adapter 与范围扩大必须显式列出。

模块进度

模块	状态	进度	说明	风险边界
Controller-Agent Workflow Discipline	本轮完成	100%	`NEXT_AGENT.md`、`MEMORY`、`STATUS`、`CHANGELOG` 与本 dashboard 已写入总控 + 并行 subagent + 每功能独立 commit 的工作方式。	并行只用于独立范围；controller 仍负责整合、验证、dashboard 和提交边界。
QR Admin Rotation Read-only Preview	本轮完成	100%	后台只读展示 current / previous / expired / inactive、format、version、key id、expiry、token。	不写 token、不旋转、不保存 secret；后续 adapter 或 key input 要另开窄切片。
QR Token Durable Metadata Foundation	已完成	100%	local-service 已有 `QrTableTokenMetadata`、SQLite `qr_table_tokens`、repository list/replace/get。	这是 metadata 存储，不代表签名 secret 或 rotation policy 已经上线。
QR Token Signing/Rotation Hardening	已完成	100%	可选 signed `qrt2.<payload>.<signature>` token 与 legacy token 共存，仍需显式 signing keys。	浏览器代码不能隐藏默认 secret；签名路径不能默默成为默认。
QR Admin Persisted Metadata Adapter / Key Input	推荐下一步	20%	优先做只读 adapter 或明确 operator-provided key source input，再考虑写入语义。	rotation write UX、远程 lookup、生产 key policy 仍需要单独 spec。

并行执行与确认队列

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

本轮边界

纯 domain helper

`buildQrAdminRotationPreview()` 是浏览器安全投影，不导入 SQLite、`node:sqlite`、local-service runtime adapter 或 server 模块。
persisted metadata 优先；没有 persisted rows 时才使用 generated registry rows。
status 推导顺序为 inactive、expired、previous/current。

后台只读 UI

`QrPlacardsAdminDetail` 增加可选 `tokenMetadata` 与 `previewNow`，服务测试和未来 adapter。
预览表展示 source、status、format、version、key id、expires、token。
Operator key source 文案只标记边界，不是 key management 实现。

不改变顾客路径

生成桌牌、CSV/JSON 导出、QR entry validation 保持原样。
QR customer cart option selection 与 `runQrCustomerCartSubmit()` 没有改动。
`order.append_qr_batch_to_table` 和 local-service partial validation 没有改动。

验证矩阵

已完成聚焦验证

fresh worktree `npm install`、baseline `npm run build`、baseline `npm test`。
RED/GREEN `npm test -w @gaima-pos/pos-ui -- qrAdminPlacards`。
`npm test -w @gaima-pos/pos-ui -- qrAdminPlacards qrTokenRegistry qrCustomerEntry qrCustomerCartPage qrCustomerOrderFlow`。
`npm run typecheck -w @gaima-pos/pos-ui` 与 `npm run build -w @gaima-pos/pos-ui`。

最终全量验证已通过

`npm test`：core 42、local-service 206、pos-ui 241、sample-data 51。
`npm run typecheck` 通过。
`npm run build` 通过。
`npm run db:validate` 通过。
`git diff --check` 通过，仅 Windows LF/CRLF 提示。

仪表盘渲染已通过

本页已通过本地 HTTP server 打开，HTTP 200。
桌面 1440px 与移动 390px 都能滚动到 handoff prompt。
无 console warning/error、无水平溢出、无 authored sticky/fixed CSS。

架构护栏

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。

近期主线

提交 / 模块	意义
`a8fbd58 feat: add qr admin rotation preview`	把只读 rotation metadata preview 与 operator key source boundary 接入后台。
本轮 docs workflow checkpoint	把 controller-agent、parallel subagents、每功能独立 commit、worktree clean 与用户确认队列写入项目记忆和 dashboard。
`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` 是最新交接基线。
作为 controller-agent 制定一个同主题批次计划；可在较长 session 内并行推进多个互不依赖的合格功能。
每个功能都要独立测试、独立 commit，commit 后检查 `git status --short`，再整合下一个功能。
优先 QR Admin Persisted Metadata Adapter / explicit operator key source input boundary；如批量推进，确保文件范围和测试路径不重叠。
停止前刷新 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` and `git log --oneline -6` to confirm root `main` is at the latest QR admin rotation read-only preview checkpoint after `b91d403 feat: add qr token durable metadata storage`. 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 slice is QR Admin Rotation Read-only Preview / Operator Key Source Boundary: `packages/pos-ui/src/domain/qrAdminRotationPreview.ts` builds browser-safe read-only preview rows from generated registry metadata or explicitly supplied persisted `QrTableTokenMetadata`; `packages/pos-ui/src/qrAdminPlacardsPanel.tsx` renders a read-only `Token rotation preview` and `Operator key source` note in the existing `桌台 QR` admin module. This is preview-only: no rotation writes, no signing secret persistence, no key vault, no remote lookup, no local-service runtime or SQLite import in browser UI, and no QR customer submit/default placard behavior change. 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. Recommended next module is a narrow QR Admin Persisted Metadata Adapter / explicit operator key source input boundary unless the user chooses another QR/admin polish slice first. 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`, 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.