3d-filament-tracker

# 3D Filament Tracker 把散落在淘宝/京东/拼多多订单截图里的 3D 打印耗材，整理成一张可交互的库存表。 ## 触发方式 - 用户说「统计一下我的 3D 打印耗材」/「3D 耗材库存」/「filament tracker」 - 用户给一堆订单截图说「帮我看看买了哪些料」 - 用户问「我还剩多少卷 PLA」/「哪些颜色已经在用了」 - `/3d-filament-tracker` ## 它解决什么 3D 打印耗材一买就是几十卷，散在多个店铺多个订单里。**靠脑子记不住**：哪个颜色买了几卷？哪些已经塞进打印机了？哪些用光了？哪些还在库存？ 传统方案： - **Excel** —— 每改一次状态都要手动算合计，没颜色提示 - **拍照堆桌上** —— 不知道总数也不知道库存 - **Bambu Studio 内置料盘** —— 只管插上去那一卷，不管库房 这个 skill 给你一份**单文件 HTML 跟踪器**：浏览器打开就能用，状态存在 localStorage，可导出 JSON 备份。 ## 核心交互模式：双步进器 + 现有数联动 每行耗材有两个状态： ``` 原始购买数 = 现有 + 已用光 现有 = 在用 + 库存 ``` UI 上每行两个步进器： ``` [在用 − N/总 +] [已用 − N/总 +] 绿色背景 灰色背景 ``` 约束：`在用 + 已用 ≤ 总卷数`（步进器自动 disable） 「已用」+1 时全部联动重算： - 该行「现有」列减 1 - 该颜色合计减 1 - 该材料小计减 1 - 顶部 pill：现有合计 −1 / 已用光 +1 - 「库存」pill：减 1 「在用」+1 时不影响现有数（耗材还在你手上），只是把它从库存挪到在用。 ## 流程 ### Phase 1：读图整理 1. 用 Read 工具读用户给的所有订单截图（一次可读多张） 2. 提取每条订单的：**材料**（PLA / PETG / ASA / PA / TPU / PC...）+ **品牌/系列**（拓竹 PLA Basic / POLYMAKER 高速 PETG / 三绿 PLA Matte...）+ **颜色** + **卷数** + **来源标记**（散装 / 套装 / 赠品 / 赔付） 3. 用一个 Markdown 表先给用户对一遍。**不要一上来就生成 HTML**，先确认数据，往返几轮把数字校准 4. 同色不同来源（散装+套装+赔付）拆成多行，每行带「来源」标签，便于追踪到底是哪一卷在用 5. 套装也按颜色拆开统计，**不要按套装维度计数**（套装是采购概念，颜色是使用概念） ### Phase 2：生成 HTML 用 `templates/template.html` 作为骨架，填充用户的实际数据。每行 `<tr>` 必须有 `data-id`（kebab-case，例 `pla-black-散装`），唯一即可。 关键 CSS class： - `material-pla` / `material-petg` / `material-asa` —— 左侧色条 - `tag-pla` / `tag-petg` / `tag-asa` —— 行内标签 - `color-total` —— 同色合计行 - `total-row` —— 材料小计行 - `group` —— 材料分组标题行 - `badge-set` / `badge-gift` —— 套装/赠品标记 每个色组结束插一个 `<tr class="color-total">` 显示合计；每个材料块结束插一个 `<tr class="total-row">`。这两个的「卷数」单元格内容由 JS 自动重算，初始填什么数字都行。 ### Phase 3：交付 - HTML 文件放到 `<workspace>/3d-printing/耗材/耗材统计.html` - 截图也放在同目录 - 提示用户：**第一次点完后立刻点「📥 导出状态」存一份 JSON**，搬目录或换浏览器就靠这份恢复 ## 关键工程点（不要踩坑） ### 1. localStorage 按文件路径隔离 - `file:///Users/.../耗材统计.html` 和 `file:///Users/.../moved/耗材统计.html` **是两个独立 origin**，状态不会自动迁移 - 所以必须提供 JSON 导出/导入 - 搬目录前先让用户导出一份；移完再让用户重新导入 ### 2. 「现有」≠ 「原始」 - 「卷数」列显示的是**现有**（= 总数 − 已用），会随交互变化 - 步进器分母固定显示**原始购买数**，所以用 `data-total` 锁住，不能从 `.qty` 单元格读 - 初始化时把 HTML 里写死的初始 `.qty` 值 snapshot 到 `tr.dataset.total`，之后所有读数走 `getTotal(tr)` 而不是 `parseInt(qty.textContent)` ### 3. 合计行不能 hardcode - 颜色合计 / 材料小计 / 总计**全部由 JS 重算** - HTML 里写的初始数字只是占位，加载时 `recomputeAggregates()` 立刻覆盖 - 重算逻辑：从上往下遍历 `tbody`，遇到 `.group` 行重置 colorAcc/materialAcc，遇到 `[data-id]` 行累加 (total − consumed)，遇到 `.color-total` 写 colorAcc 并清零，遇到 `.total-row` 写 materialAcc 并清零 ### 4. 双步进器互相约束 - `在用 + 已用 ≤ 总数` - 单步进器自身能减到 0 - 任何一个 +1 之前先检查 `next + other > total ? return : commit` - disable 状态算 `(using + consumed) >= total` 时 + 按钮全部 disable ### 5. JSON 兼容旧版本（v3 → v4） - 早期版本只有「在用」一个值，state 是 `{id: number}` - 现在 state 是 `{id: {using: N, consumed: M}}` - importState 时检测 `typeof v === 'number'` → 自动迁移成 `{using: v, consumed: 0}` ## 视觉规范 整行底色根据状态： - 浅**绿** = 该批次全在用 - 浅**黄** = 部分在用 - 浅**灰 + 删除线** = 全部用光 - 白 = 全在库存 色卡（`.swatch`）尽量贴近实物颜色： - 拓竹 PLA Basic 系列用商品页配色 - Silk 系列用 `linear-gradient` 模拟丝绸渐变 - 透明色用半透明 - 实在拿不准就用 `#7f8c8d` 灰 ## 不要做的事 - ❌ 不要用复杂前端框架（React/Vue）—— 单文件 HTML + 原生 JS，用户双击就能用 - ❌ 不要把状态存到外部数据库 —— localStorage + JSON 文件就够了 - ❌ 不要按套装维度统计 —— 用户关心的是颜色，不是 SKU - ❌ 不要改步进器分母 —— 分母永远是原始购买数，让用户能看到"我之前总共买过几卷" - ❌ 不要在 HTML 里硬编码合计数字让它和 JS 不同步 —— 合计永远 JS 算 ## 同步发布 跟着 [[feedback_skill_publishing_flow]] 走：公网 GitHub + ClawHub。这个 skill 不涉及 SAP 业务，**不推 SAP 内网**。