retail-project-cockpit v1.0.0 · 零售采购项目驾驶舱

一句话：把飞书项目跟踪表，一键变成可发布的单文件 HTML 管理驾驶舱。

把一张「横向很宽、列会漂移」的飞书项目跟踪表，稳定地变成一份可以发给老板、可点选编辑、可原地刷新的单文件 HTML 管理驾驶舱。

与 retail-store-cockpit 的分工：本 skill 管「多项目并行跟踪」（几十个项目 × 里程碑 × 供应商）；那个管「单店从 0 到开业」（甘特图 + 开业日 + 提醒引擎）。两者构成零售拓展的双驾驶舱体系。

English

Turn a Feishu multi-project tracker sheet into a self-contained, publishable single-file HTML cockpit — drift-proof header mapping, six dashboard modules (KPI / filterable table / charts / milestone matrix / cycle metrics / 3-stage payment tracking), Owner-gated inline editing, blank-render guardrails, and in-place cloud deploy.

Input: one Feishu sheet — rows = projects, ~46 columns (basics / milestone dates / cost breakdown / 3-stage payments)
Output: index.html (~376 KB, Chart.js inlined, works offline) + data.json (30s polling hot refresh)
Reference build: Iberia & Switzerland retail board — 27 projects / PT·ES·CH / 9 suppliers
Why it exists: when a teammate inserts or deletes a column upstream, fixed-index parsing silently shifts every field; this pipeline maps by header text instead.

能力清单

| 环节 | 能力 | |---|---| | 数据接入 | lark-cli 拉取飞书单表（annotated_csv），行号剥离 + 三级表头解析 | | 抗列位移 | 表头子串模糊映射（中英双语），分组上下文区分同名子列，严禁固定索引兜底 | | 数据清洗 | 金额 €1,234.56 → float（空值 None 非 0）；兼容 2026年8月15日 / 2026-08-15；过滤 1899/1900 脏日期 | | 六大模块 | KPI 卡片 / 可筛选明细表（双行冻结）/ 国家×类型图表 / 项目×里程碑节点矩阵（双向冻结）/ 采购周期指标 / 付款三阶段跟踪 | | 权限与编辑 | 默认只读，Owner 密码解锁（sessionStorage），四类本地编辑存 localStorage（带项目前缀） | | 交付与运维 | 离线内置数据 + 联网 30s 轮询热刷新；node --check + vm 运行时模拟防空白；原地云部署 |

安装方式

解压后将 retail-project-cockpit/ 整个目录放入用户级技能目录：

Windows:  %USERPROFILE%\.workbuddy\skills\
macOS / Linux:  ~/.workbuddy/skills/

若安装到项目级（团队共享），放入 {workspace}/.workbuddy/skills/。

无需额外依赖：解析用 Python 标准库；图表用内联 chart.umd.min.js（随看板打包）。

快速开始

复制 scripts/sync_feishu_sheet.sh，改 4 个变量（TOPIC / TOKEN / SID / RANGE）并执行，拉到 <topic>_raw/all.csv。
复制 references/implementation_notes.md 里的骨架代码建 generate_<topic>_dashboard.py，按项目改四张配置表：
- SHEETS / SPREADSHEET_TOKEN —— 飞书定位
- FIELD_COLS + build_field_map —— 字段与表头关键词
- MILESTONES / STAGE_GROUPS / COST_FIELDS / PAYMENT_ITEMS —— 业务节点定义
- TABLE_COLS —— 明细表展示列
跑生成器 → <topic>_dashboard/index.html + data.json。
按 references/implementation_notes.md §7 做防空白校验，再部署。

目录结构

retail-project-cockpit/
├── SKILL.md                            # 主文档：流程、坑表、复用改法
├── README.md                           # 本文件（含 English 简介）
├── references/
│   └── implementation_notes.md         # 8 段可复制代码骨架 + 校验清单 + 部署故障处理
└── scripts/
    └── sync_feishu_sheet.sh            # 飞书拉取脚本模板

触发词（示例）

「把这个飞书表做成一个看板 / 项目管理驾驶舱」「XX 地区零售项目看板」「项目里程碑矩阵」「付款进度看板」「采购周期指标」「刷新一下看板数据」

版本

| 版本 | 日期 | 说明 | |---|---|---| | 1.0.0 | 2026-09-02 | 首个版本。沉淀自「西葡及瑞士地区零售项目管理看板」v16（27 项目 / PT·ES·CH / 9 供应商）。定名 retail-project-cockpit，与 retail-store-cockpit 组成双驾驶舱体系 |

作者：Davy Chen（陈哲）