GAIMA POS 全局项目控制台
单店 POS 可用系统进度看板
本页必须始终展示整个 POS 系统的进度,而不是只展示最新 QR 切片。当前主线目标是把单店可用闭环打稳:后台资料、前台点单、本地 DB/local-service、厨房打印队列、付款关单、QR 下单、开发验证与待用户确认事项。
单店闭环主线
后台资料、点单、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 导出。 |