我的小店工作台 · 项目文档

一款面向小摊贩的轻量化经营工具，基于 WorkBuddy 资料库 + 单文件 HTML 部署。

一、项目概述

1.1 背景

菜摊、早餐摊、水果摊等个体小店的经营场景有一个共同特点：老板不记流水。他们每天的常规操作是「盘货」——开摊时看一眼货架有多少、收摊时看一眼剩多少，中间偶尔补补货。让他们一笔笔记销售既不现实也没必要。

1.2 核心思路：盘存法

把传统「流水记账」改为「库存倒推」：

期初库存 + 期间进货 − 期末盘点 − 损耗 = 本期销量

老板只需要：

  1. 首次：把开摊时的库存录进来（初始库存）
  2. 进货时：记一笔进货单（系统自动加库存）
  3. 收摊时：记一次剩余量 + 当天损耗

系统自动算出：本期卖了多少、销售额、毛利。

1.3 目标用户

1.4 部署形态

二、资料库设计

2.1 表结构总览

表名 用途 字段数 初始数据条数
我的小店·商品库存 商品字典 + 当前库存 + 预警 10 5
我的小店·熟客账本 客户档案 + 赊欠账 5 2
我的小店·进货单 进货流水 + 自动累加库存 8 3
我的小店·盘点记录 收摊盘点快照（每日历史） 12 5

2.2 字段设计

我的小店·商品库存

字段 类型 说明
商品名称 text 唯一标识
单位 select 斤/份/个/把（固定选项）
今日进价 currency ¥ 进货时更新
售价 currency ¥ 长期不变
库存数量 number 当前库存（只能盘点更新）
预警线 number 低于此值显示红色警告
损耗 number 本期损耗累计
备注 text 选填
期初库存 number 上次盘点时的库存（推算用）
上次盘点日期 date 上次盘点时间

我的小店·熟客账本

字段 类型 说明
姓名 text 主键
手机号 phone_number 默认脱敏显示（138****5678）
赊欠金额 currency ¥ 当前欠款（赊账+、还款−）
加入日期 date
备注 text

我的小店·进货单

字段 类型 说明
商品名称 text
数量 number decimalPlaces=0
单位 select 斤/份/个/把
进价 currency ¥ 单位进价
金额 currency ¥ 数量 × 进价（自动算）
供应商 text
日期 date 默认今天
备注 text

我的小店·盘点记录

字段 类型 说明
商品名称 text
单位 text
期初 number
进货 number 期间进货
期末 number 盘点剩余
损耗 number
销量 number = 期初+进货−期末−损耗
售价/进价 currency ¥ 快照
销售额/毛利 currency ¥ 快照
日期 date

2.3 表关系

进货单 ──自动累加──> 商品库存.库存数量
商品库存 ──盘点时──> 盘点记录（快照）
熟客账本 ──赊账/还款──> 自更新赊欠金额

无外键，靠「商品名称」字符串关联。简单可靠，不依赖外键配置。

三、功能模块（6 大 Tab + 主页）

3.1 主页（大图标导航）

v11 改造：原本是 Tab 平铺，改为大图标卡片式主页。

布局：

6 个图标入口：

图标 名称 副文案 配色
📊 销售估算 本期卖了多少 绿
📥 进货管理 进货记单库存自动加 蓝
📦 商品库存 登记商品 / 收摊盘点 橙
👥 熟客账本 赊账还款随手记 粉
📋 盘点记录 回看每天卖了多少 紫
💰 今日营收 看利润、看热销 黄

返回机制：每个功能面板顶部都有「← 返回主页」通栏大按钮（54px 高），Tab 栏最前面也有「主页」入口。

3.2 商品库存（3 个子 Tab）

v7 改造：原本是 3 个表单 + 列表堆在一屏，改为分段控制器切换：

3.3 进货管理

操作流程：

  1. 输入商品名 + 数量 + 进价（金额自动算）
  2. 选供应商 + 日期
  3. 保存

自动行为：保存时检查商品字典，若该商品不存在则自动建一个新商品（单位继承进货单的单位，期初库存=0，价格从进货单带入）。

3.4 熟客账本（卡片式列表）

v13 改造：原本是单行 flex，挤爆移动端 → 改为独立卡片式布局：

┌─────────────────────────────┐
│  李叔  [无欠款]     ¥0.00   │  ← 上行
│                       欠款   │
│                             │
│  [136****5432 查看]         │  ← 中行
│  2026-06-20 · 爱买鱼和青菜  │
│                             │
│              [赊账][还款][删]│  ← 底行
└─────────────────────────────┘

隐私保护：手机号默认打码 138****5678，点击 → 已登录看完整号 + 一键复制，未登录访客无法看。

3.5 盘点记录（每日快照）

v6 新增：每次收摊盘点时，自动写入一条快照到「盘点记录」表，包含：

按日期分组回看，支持按日期筛选，统计累计销售额/毛利/天数。

3.6 今日营收（报表）

汇总数据：销售额、利润、进货支出、销量、损耗、利润率 + 热销 TOP3 + 商品毛利明细。

3.7 销售估算（核心计算）

每样商品一行明细：

西红柿  期初 10 + 进货 30 − 盘点 15 = 销量 25斤   销售额 ¥75   毛利 ¥30

销量 < 0 会标红（说明漏记进货或盘点错误）。

四、关键设计决策

4.1 为什么用盘存法不用流水？

模式 流水记账 盘存法（采用）
操作次数 每笔销售都要记 收摊盘点 1 次
数据准确性 高（但容易漏） 中（盘点误差）
用户负担 重 轻
适用场景 超市/餐饮 小摊贩 ✅

结论：对小摊贩而言，准确性够用 + 操作负担低 > 完美数据。

4.2 为什么用单文件 HTML？

4.3 为什么用云端资料库而不是纯 localStorage？

4.4 为什么是 4 张表而不是 1 张？

五、适老化改造（v10）

5.1 改造目标

菜摊老板普遍 50+ 岁，手机屏幕看小字、点小按钮费劲。

5.2 改造清单

项 改造前 改造后
基础字号 15px 17px
数字大字 18px 24px
主按钮高度 44px 48px
Tab 高度 44px 50px
小按钮高度 34px 44px（达触控标准）
输入框高度 44px 50px
次要文字 11.5~13px ≥14px
删除按钮 普通样式 灰色弱化（防误触）

5.3 交互简化

5.4 大图标主页（v11）

解决「Tab 文字太小看不清入口」问题。每个图标 138px 高、62px 圆形图标，6 色区分功能。

六、隐私保护

6.1 手机号打码

熟客账本里所有手机号显示为 138****5678，完整号不写入 DOM。

解锁机制：点击 pill → 已登录可查看完整号 + 一键复制；未登录访客提示「未登录，无法查看完整号码」。

6.2 公开链接的安全提示

链接 https://workbuddy.link/p/dAdmF5knBlKA1wHPUn3dsB 是公开可访问的，任何人拿到都能打开。所以提醒用户：不要录入过多敏感信息。

未来可选方案：

七、技术架构

7.1 文件结构

我的小店工作台.html（约 80KB）
├─ <head> CSS（~15KB）
│  ├─ :root CSS 变量（颜色/圆角/阴影）
│  ├─ 字体/排版
│  ├─ 6 大 Tab 布局
│  ├─ 卡片式组件
│  └─ 媒体查询（移动端适配）
├─ <body> HTML（~10KB）
│  ├─ header（顶部 logo）
│  ├─ #tabBar（Tab 导航）
│  ├─ #panel-home（主页大图标）
│  ├─ 6 个功能面板
│  ├─ .dlg-mask（弹窗）
│  └─ .toast（提示）
└─ <script> JS（~55KB）
   ├─ CACHE 常量（localStorage 键）
   ├─ DATABASE ID 常量
   ├─ SDK 封装层（sdkQueryStock/Member/Purchase/Checkin/Add/Update/Delete）
   ├─ 渲染函数（renderStock/Member/Purchase/Checkin/Estimate/Today/Report/Records）
   ├─ 事件处理（表单提交、弹窗、Tab 切换）
   └─ 工具函数（money/shortDate/maskPhone/showPhone/esc/emptyHTML）

7.2 关键 SDK 调用

// 查询
db.query({ databaseId: 'xxx', pageSize: 500, sorts: [{property:'日期',direction:'descending'}] })
// 添加
db.addRecord({ databaseId: 'xxx', properties: { 字段名: {类型: 值} } })
// 更新
db.updateRecord({ databaseId: 'xxx', recordId: 'yyy', properties: {...} })
// 删除
db.deleteRecord({ databaseId: 'xxx', recordId: 'yyy' })

属性结构示例：

{ '商品名称': { text: '西红柿' },
  '单位':     { select: 'NHz4sCoJFOQj' },
  '今日进价': { currency: 1.8 },
  '库存数量': { number: 15 },
  '上次盘点日期': { date: '2026-08-19' } }

7.3 离线降级

loadStock()
  .then(rows => { stockData = rows; cacheSet(CACHE.STOCK, rows); render() })
  .catch(() => { stockData = cacheGet(CACHE.STOCK) || []; render() })

网络正常时同步云端，断网时降级到 localStorage。

7.4 lint 校验

发布前用 lint_database_sdk_usage.py 校验：

八、版本演进（v1 → v16）

v1-v3：基础三件套

搭建库存/进货/熟客三个基础功能，最初用「流水记账」模式。

v4：修复小问题

商品库存表单按钮文案改「保存进货」→「保存 / 登记商品」。

v5：业务模式大改（盘存法）

最关键的转折——从「逐笔流水」改为「盘存推算」。

v6：盘点历史记录

新增「盘点记录」表（12 字段快照）+ 第 6 个 Tab「盘点记录」。

v7：商品库存子 Tab

原本 3 个表单堆一屏 → 改分段控制器（登记商品/收摊盘点/库存清单）。

v8：熟客手机号隐私保护

默认打码 138****5678，点击解锁（未登录访客不可看）。

v9：代码审查修复 5 个 bug

# 严重度 问题 修复
1 P0 goodsList datalist 元素缺失，setInterval 每 1.5s 抛 TypeError 补回 <datalist id="goodsList">
2 P0 editStock 后 done() 没恢复 stockQty.disabled done() 加 disabled=false
3 P0 进货单自动建库存时期初库存=qty 导致销量推算翻倍 改期初=0
4 P1 编辑模式无取消机制 加「取消编辑，新建商品」按钮
5 P1 离线降级和盘点保存错误处理不全 补 catch

v10：适老化改造

字号全面加大、按钮触控 ≥44px、数字键盘、toast 加时、删除按钮弱化。

v11：大图标主页

新增 #panel-home，6 个大图标入口；6 个功能面板加返回主页大按钮。

v12-v13：熟客列表移动端布局修复

v12 改两行布局（仍拥挤）→ v13 彻底改为独立卡片式（每张熟客一张卡片，三层信息）。

v14：改名「我的小店」

从「菜市库存 / 菜摊工作台」→「我的小店·」统一前缀。

v15：本地文件改名

菜摊工作台.html → 我的小店工作台.html。

v16：资料库改名 + 数据迁移

agent API 集无 update-database 接口 → 重建 4 张新表 + 迁移 15 条数据 + 清空旧表。

九、部署与发布

9.1 工作流

编辑 我的小店工作台.html
  ↓
合并 4 表 schema
  ↓
跑 lint（MINDX_DBSDK_LINT_OK）
  ↓
import_html → publish → list_artifacts
  ↓
curl 验证产物（ID 数量、关键 class 出现）

9.2 关键命令

# 导出 4 张表 schema（用于 lint）
for db_id in "1itM3JNw..." "UQQHhsgWP..." "jXlaDltP5A..." "nK3gxBrLjT..."; do
  printf '%s' "$TOKEN" | python3 get_database_schema.py \
    --token-stdin --database-id "$db_id" > "schema.json"
done

# 合并并 lint
python3 -c "import json; ..."
python3 lint_database_sdk_usage.py --schema-file merged.json --html 我的小店工作台.html

# 导入并发布
printf '%s' "$TOKEN" | python3 import_html.py "我的小店工作台.html" \
  --file-name "我的小店工作台.html" \
  --node-block-id "dAdmF5knBlKA1wHPUn3dsB" \
  --databases '[{"id":"1itM3JNw..."},...]' \
  --token-stdin

printf '%s' "$TOKEN" | python3 publish_page.py \
  --token-stdin --node-id "dAdmF5knBlKA1wHPUn3dsB"

9.3 公开链接

https://workbuddy.link/p/dAdmF5knBlKA1wHPUn3dsB

发布版本号 v16（artifacts version 21）。

十、关键经验沉淀

10.1 业务认知比代码更重要

最关键的迭代是 v5——盘存法。整个项目从「不实用」变为「真正可用」，根本原因是理解了用户的真实工作流。技术只是工具，业务认知才是核心。

10.2 适老化不是装饰是刚需

对小摊贩这种核心用户群，移动端适老化不是「加分项」，而是「能不能用」的分水岭。字号/按钮/弹窗三个维度做扎实，老人才愿意用。

10.3 agent API 的能力边界

WorkBuddy 资料库 agent API 当前能力：

资源改名/删除需要走 UI 或后续接口支持。

10.4 Gmeek/WorkBuddy 单文件部署的坑

十一、后续优化方向

11.1 功能增强

11.2 用户体验

11.3 数据分析

11.4 工程优化

附录 A：资料库 ID 对照表（最新）

用途 数据库 ID
我的小店·商品库存 1itM3JNwNptPvOpy442Nkq
我的小店·熟客账本 UQQHhsgWP7amWzKniONVkR
我的小店·进货单 jXlaDltP5AOpqPqLVdtAL9
我的小店·盘点记录 nK3gxBrLjTgd2G9dBamXGP

工作台 node_block_id：dAdmF5knBlKA1wHPUn3dsB

附录 B：技术栈

文档生成于 2026-08-20，覆盖 v1~v16 完整迭代。

相关推荐

微信搜一搜 © 奇趣网站