盤點單分析 · 合作操作手冊

每週一次，週一/週二做上一週的資料。

步驟	誰做	動作	大約時間
1	翠翠	從莫筆克匯 xlsx	3 分鐘
2	翠翠	append 到 Google Sheet 新分頁	5 分鐘
3	翠翠	Slack 傳 xlsx + sheet gid 給 @Tako	1 分鐘
4	Tako	灌 D1 + 產 dashboard + 產週報 + 上傳 R2 + push	3 分鐘
5	Tako	Slack 回你兩個 URL + 本週要點觀察	1 分鐘
6	翠翠	打開 dashboard/週報看內容，有問題回饋	依情況

本週要拿的資料 = 上一週的 ISO 週資料（週一 ~ 週日）。若匯出區間跨到下週一（例：W33 匯出 08/10~08/17），我會在 meta 註明。

2-1. 莫筆克匯出（Xsale 5.60.6）

1. 頂部選單 → 採購管理
2. 二級 tab → 盤點
3. 按 匯出報表 按鈕
4. 匯出設定：
   • 盤點狀態：只勾 已結案（未確認 / 已確認 不勾）
   • 日期類型：建立日期
   • 日期區間：該 ISO 週的週一 ~ 週日（例 W33 = 2026/08/10 ~ 2026/08/17）
   • 指定廠商：不分廠商
   • 目標倉庫：主倉
5. 拿到 xlsx

2-2. Google Sheet 維護

1. 開 Sheet：docs.google.com/spreadsheets/d/1VquDCNw6ACUgP09In6enQKCKLnBd4sVnCWcA80d7HfU/edit
2. 新增一個 tab（命名 W33、W34... 方便分辨）
3. 把 xlsx 內容貼進去
4. 複製這個 tab 的 URL（?gid=xxxxxx#gid=xxxxxx 那個），或直接複製 tab 名稱 + gid 傳給 @Tako

在 Slack thread 裡直接丟這兩樣：

[xlsx 檔案 attachment]
W33 sheet gid: 1644196388

如果你上傳 xlsx 時同步跟我說「這是 Wxx 資料」+ 「新的 sheet gid 是 XXXXX」，我就會照流程跑完。沒特別交代的話，我會用 ISO 週判定 batch code，然後直接動手。

1. 存 xlsx → ~/repo/notes/taco/stocktake/YYYY-Www.xlsx
2. 跑 loader：

   python3 loader.py 2026-Wxx.xlsx 2026-Wxx --range YYYY-MM-DD..YYYY-MM-DD
   

3. UPDATE D1 batches 的 sheet_gid（若翠翠有給）
4. 寫週報 YAML 2026-Wxx-report.yml（7 節結構）
5. 跑 html-gen 產週報 HTML → upload R2（timestamp URL）→ D1 taco_artifacts insert report-r2
6. 跑 build_dashboard.py → upload with --slug stocktake-dashboard.html
7. 跑 build_report_wrapper.py → upload with --slug stocktake-report.html
8. git commit + push
9. Slack 回翠翠：兩個 URL + 本週要點（3~5 個 bullet）

5-1. 這週資料要重跑

翠翠說：「W33 那份重跑，我改了 Google Sheet」

Tako 做：

1. 全清 W33（含備份，見「執行 W33 全清」memory 那組流程）
2. 拿翠翠新版 xlsx（若 xlsx 沒改，用備份的）
3. 重跑 loader → build → upload

重跑 dashboard/wrapper 因為固定 slug 覆蓋，URL 不變、翠翠 reload 就看到新內容。

5-2. 加/減 建立者

翠翠說：「新來的同事 mika 開始建盤點單，姓名林小花」

Tako 做：

INSERT INTO taco_stocktake_creator_roles (creator, role, display_name, added_by)
VALUES ('mika', 'staff', '林小花', 'tako');

重跑 dashboard/wrapper 就會顯示。

翠翠說：「PO015 也算採購」

Tako 做：

INSERT INTO taco_stocktake_creator_roles (creator, role, display_name, added_by)
VALUES ('PO015', 'purchasing', '<姓名>', 'tako');

下次分析自動排除。

5-3. Google Sheet 新分頁 gid

翠翠說：「W34 sheet gid 是 987654321」

Tako 做：

UPDATE taco_stocktake_batches SET sheet_gid='987654321' WHERE batch='2026-W34';

重跑 dashboard 就會連對分頁。

5-4. 分析規則要調整

翠翠說：「短少金額改用 vendor_price（廠商批價）算」

Tako 做：先跟你確認影響（會改 W32 W33 所有數字），確認後改 build_dashboard.py + 週報 YAML，重跑所有 batch。

翠翠說：「動作型態的關鍵字要加『補貨』」

Tako 做：這是分類 rule，加 keyword mapping。目前是原字串抽取，若要人工 taxonomy 需要你列 rule table。

• 決定「這週的異常是不是要追」— 我列 Top N 給你，追不追由你判斷
• 決定「短少金額用哪個成本欄」— 目前用 stock_cost，翠翠沒指定要改
• 決定「哪些 header_note 原因要合併」— 目前純機械抽取，taxonomy 要你定
• 決定「要不要通報主管」— 我不會主動 @ 任何人，通報由你自己判斷跟寫

• URL 打不開 / 404 → 通常是 R2 快取；等 1~2 分鐘 reload。真的還壞跟我說
• 切週看不到某週 → 可能 D1 資料沒灌成功，跟我說我查 batches 表
• 數字對不起來 → 拿具體單號來，我用 D1 raw 資料對給你看
• 想看 raw 原始行 → dashboard 底下「三、原始明細」有 65+ 行 table，可 filter / sort / search

• Slack 直接 @Tako 就好
• 所有備份留在 ~/repo/notes/taco/stocktake/backups/（含 D1 dump + R2 curl 回來的 HTML）
• 重大改動前我一定先備份、列範圍給你 review 再動手
• 產物版控走 GitHub Tako-Agent/workspace