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.