Gaima POS 项目控制台 / 2026-05-22

本地 DB + SQLite repository adapter 主线正在推进

当前稳定点：Visible POS 的行备注、常用要求、takeout flag 已经可以在配置 async local-service 后走 durable `order.update_line_facts`，同时保留未配置时的 snapshot fallback。下一步默认继续收窄 modifier / combo 写路径。

最新稳定提交 codex/pos-async-line-facts（基线 80b8176）

当前主线 fresh worktree `codex/pos-async-line-facts`

验证状态 测试、类型检查、构建、DB validate、POS UI QA、dashboard 滚动检查均通过

下个默认模块 Visible POS Async Modifier/Combo Add Migration Slice

Visible POS Async Line Facts Migration

已确认，不再是待拍板问题

Local-service

durable `order.update_line_facts`

新增 `runUpdateLineFactsCommand()`，通过 command log 保持幂等。
line note、common requirements、takeout flag 通过同一窄命令更新。
`LocalServiceRuntime.updateLineFacts()` 暴露统一 runtime 入口。

Transport

浏览器安全协议边界

新增 `{ type: "order.update_line_facts" }` request。
POS UI 只使用协议/root 类型和 sender，不导入 SQLite 或 Node-only runtime。
sync gateway 与 async runtime 复用同一 browser-safe DTO。

Visible POS

行事实编辑

未配置 async 时仍走 snapshot fallback。
配置 async 时通过 helper 发起 pending/success/error 状态。
失败时保留原 visible order，不清空当前编辑上下文。

还需要用户拍板

仅保留 3 个未来范围决策

这些不是当前开发阻塞项

生产 SQLite packaging/linking

生产部署时继续使用 Node 内置 `node:sqlite`，还是改为随 Docker/Electron 打包的 native package。

语音输入 provider

未来经理备注、Close 原因、折扣原因要接入哪一个系统级或浏览器级语音输入方案。

第一种真实打印 transport

真实硬件打印先接 LAN ESC/POS、Windows network printer、USB ESC/POS，还是继续保留手动模拟。

已确认约束

后续 agent 不应重新提问的事实

这些内容已经从“待拍板”降级为开发约束，dashboard 顶部不再把它们列为问题。

本地运行

每店本地 DB

每家店有自己的本地 DB。
电脑端 local-service 是订单、print queue、本地 DB 的唯一写入口。
iPad / QR / POS UI 不直接写 SQLite 文件。

锁与会话

30 秒 TTL

heartbeat 间隔 10 秒。
session / lock TTL 30 秒。
查看旧订单不拿锁，同桌加菜 append-only 不需要长编辑锁。

订单语义

Close 才是截点

付款记录不会清空或归档订单。
正余额阻止 Close。
QR cart partial validation 应接受有效行，并返回失败项。

模块进度估计

当前核心闭环

百分比是用于排优先级的工程估计，不是发布承诺。

Local Runtime / DB

SQLite repository adapter、command log、session/lock、async runtime 主线稳定。

POS Order Entry

plain item、session/lock display、payment/Close、confirm/print、line facts 已可 async opt-in。

Printing Queue

队列事实、路由、retry/admin 基础已稳定；真实硬件 transport 未开始。

Payments

本地 payment rows / Close lifecycle 已落地；真实 provider adapters 仍是 P2。

Online Orders

平台订单 adapter / inbox 边界保留，不能抢在本地订单闭环前扩大。

模块地图

下一步只能选一个主模块

继续保持小切片：每轮只迁移一条可见写路径，并更新 handoff。

模块	状态	完成事实	下一步	风险边界
Local Runtime / DB本地离线可靠性	92%	SQLite schema/repository、command log、session/lock、transport、HTTP harness、async order/session runtime 已稳定。	继续迁移剩余 visible POS 写路径，默认从 modifier/combo add 开始。	catalog 仍部分委托 in-memory；UI 不得直接写 SQLite。
POS Order Entry前台点单	86%	plain item、payment/Close、confirm/print、line facts 可 async opt-in，未配置时保留 snapshot fallback。	把 modifier/combo add-line 迁移到 async command boundary。	不要混入 QR batch、split bill、provider adapter 或硬件打印。
Printing System打印系统	72%	PrintJob queue、routing、retry/admin、worker 状态机基础已完成。	真实硬件 transport 等用户拍板后单独做。	不要把真实 ESC/POS 与当前 visible POS async 迁移混在一起。
Payments支付与结账	62%	本地 payment rows、manager discount、Close + customer copy 语义已落地。	保持 provider adapters 为 P2，先稳定本地订单事实。	Square/Clover/Stripe 不要提前影响 local-service 核心模型。
Platform Orders平台订单	12%	已确认 Uber/DoorDash/Fantuan 未来应通过 local-service adapter/inbox 进入。	本地订单闭环稳定后再做平台 inbox。	平台 adapter 不得直接写 SQLite。

推荐队列

下一轮开发建议

默认继续 Local DB + local-service 主线，不扩大到硬件、支付 provider 或平台订单。

Visible POS Async Modifier/Combo Add Migration

迁移 modifier add-line。
迁移 combo add-line。
保留 snapshot fallback 和 browser-safe import 边界。

Docs-only 编码清理

历史中文文档存在乱码。
应单独模块处理，不混入业务迁移。
dashboard 必须保持中文主界面。

QR partial-acceptance batch

语义已确认：接受有效项，返回失败项。
实现 batch command 仍是独立优先级。
不要抢在 modifier/combo 迁移前扩大。

开发护栏

不要重新分裂事实源

每轮结束必须更新 dashboard、状态文档，并给出可复制的新 session prompt。

必须保持

浏览器安全边界

POS UI 不导入 `node:sqlite`。
POS UI 不导入 runtime-bound local-service modules。
UI/iPad/QR 只通过 local-service command/API 写入。

不要扩大

真实硬件与 provider

真实打印机、支付 provider、平台订单 adapter 都是后续模块。
不要在 modifier/combo slice 中引入这些范围。
生产 SQLite packaging 也保持待拍板。

交接纪律

结束时必须给 prompt

写清路径、分支、最新 commit、dashboard 链接。
列出 read-first 文件和验证命令。
上下文快满前先停新开发并更新 handoff。

验证记录

每轮结束都要提供这一类交接 prompt

继续 POS Local DB + SQLite repository adapter 主线。请用中文回复。先从根目录 `D:\AI_Projects\POS System` 开始，按顺序读取 `NEXT_AGENT.md`、`docs/STATUS.md`、`docs/MEMORY.md`、`docs/CHANGELOG.md`、`docs/project-overview-infographic.html`，不要用根目录之外的旧 worktree 状态判断当前开发状态。当前完成模块是 Visible POS Async Line Facts Migration Slice：local-service 已有 durable `order.update_line_facts`，POS sync/async runtimes 支持 selected-line facts，visible POS 行备注、常用要求、takeout flag 可 async opt-in 并保留 snapshot fallback。dashboard 线上地址是 `https://gaima-pos-dashboard.pages.dev/`，dashboard 必须保持中文并验证滚动渲染。下一默认模块是 Visible POS Async Modifier/Combo Add Migration Slice：只迁移 modifier/combo add-line 可见 POS 写路径到 async local-service，保留 snapshot fallback。保持硬件打印、支付 provider、平台 adapter、split bill、WebSocket push、outbox replay、生产 SQLite packaging 在 scope 外，除非我明确改优先级。请新建 fresh ignored worktree 开发，结束前更新 dashboard/status/memory/changelog/NEXT_AGENT，并给我下一轮可复制的新 session prompt。