项目管理驾驶舱（Project Cockpit）
把「进度数据 → 自包含离线 HTML 看板 + 甘特图 + 邮件提醒 + 部署」这一整套做成可复用的流水线。
适配任意行业的项目管理：IT 交付、工程建设、市场活动、产品发布、研究课题等，只要有一份
「时间轴（任务 + 起止日 + 阶段 + 责任人）」就能生成一套专业驾驶舱。
何时使用
- 新建项目看板 / 管理驾驶舱 / 进度可视化
- 「把甘特图同步到看板」「里程碑日期要跟着甘特图走」
- 「任务到期前 N 天发提醒邮件」「生成责任人缺口 / 提醒日历 Excel」
- 从飞书多维表格 / Excel / JSON 拉取进度，生成离线可打印看板
核心概念
- KEYDATE：项目唯一的关键里程碑日期（如交付日 / 上线日 / 发布日 / 验收日 / Go-Live），
是红竖线起点 + 页面上所有里程碑日显示的唯一真相源。可配一个可选的锚点事件日期
（ANCHOR_DATE）用于「锚点前 N 天」的倒推文案。 - TASKS：标准化任务数组（id/cat/name/start/end/dur/resp/person/status/detail），
cat为阶段全称，决定甘特条颜色与筛选按钮。 - 单文件离线 HTML：内联 CSS/JS、无 CDN，可打印 / 导出 PDF / 直接打开；运行时可选联网刷新。
交付物结构（项目根目录）
<project>/
├── Project_Dashboard.html # 源看板（自包含离线 HTML）
├── data.json # 单一真相源：KEYDATE / TASKS / BASICINFO / RISKS / ...
├── people_map.json # 姓名 -> 邮箱（提醒引擎用）
├── raw/timeline_live.json # 时间轴数据源抓取结果
├── deploy/index.html + data.json # 部署副本（与源同步）
├── Project_提醒日历.xlsx # 提醒日历（build_reminder_calendar.py 生成）
└── reminder_plan.json # 提醒派发计划（reminder_dispatch.py 生成）
端到端工作流
- 接数据源（一次性授权 + 拉取）：见
references/data_sourcing.md。
用lark-cli sheets +cells-get --format json把时间轴标签页存为raw/timeline_live.json；
或用 Excel/CSV 转成同构 JSON。
⚠️ 飞书返回结构是ranges[].cells（2D，每格{"value":...}），不是annotated_csv。 - 同步甘特：
python scripts/sync_timeline.py --write解析时间轴 → 回写data.json的
TASKS+ 自动推导KEYDATE（按MILESTONE_MARKERS精确匹配里程碑任务，排除 "Pre-xxx"）。
默认只 diff 不写，先跑一次看变更再--write。 - 注入看板：
python scripts/patch_html.py把TASKS/KEYDATE写回源 HTML 与deploy/index.html，
并把里程碑红框初始值 + 叙事文本锁死到KEYDATE（见下「里程碑自动同步」）。 - （可选）提醒引擎：
python scripts/reminder_dispatch.py [--send]干跑/真实发送到期前 3 天邮件；
python scripts/build_reminder_calendar.py出提醒日历 Excel（含责任人缺口）。 - 部署：资料库 page（
workbuddy.link，证书受信任）或workbuddy_cloudstudio_deploy
（action="deploy"，directory="<project>/deploy"）。同时保留离线自包含版作为兜底。
关键里程碑自动同步（硬需求，两层保障）
页面所有「里程碑 / 目标里程碑」显示必须每次更新跟着 KEYDATE 走，零手工改：
- 运行时：给里程碑红框元素加 id="keydateChipDate" / id="keydateKpiDate" / id="keydateKpiNote"，
在 renderKpi()（被 renderAll() 调用）里直接写 KEYDATE，并按 ANCHOR_DATE 重算「锚点前 N 天」。
renderBasic() 对「目标里程碑」行同样动态生成。→ 详情见 references/dashboard_patterns.md。
- 构建时：scripts/patch_html.py 的 sweep_narrative() 锚定专属短语
（见脚本顶部 MILESTONE_PHRASES，按项目术语自定义）无条件同步所有里程碑日期文本，
不会误伤任务起止日期。
关键决策 / 红线
- 任务起止日（
start/end）是真实任务边界，别动；只同步「里程碑」语境。 - 红框同步的前提是 HTML 里已有那几个
id，否则正则写不进值 → 先加 id 再跑脚本。 - 提醒引擎：收件人不在
people_map.json标「未解析」跳过，绝不盲发；people_map缺失只干跑。 - 部署前务必
patch_html.py同时写源 + 部署副本（或cp源到deploy/），否则线上是旧版。 - 更新已发布到资料库的 page 必须走 edit-flow 事务（create→upload→PUT→commit→publish），
不要用import_html.py --node-block-id（不递增版本、不刷新发布态）。
踩坑速查
完整清单见 references/pitfalls.md（数据源结构、合并单元格丢阶段、里程碑误命中 Pre-xxx、
红框 id、叙事漏扫反向词序、部署副本不同步、邮件称呼尾随数字等）。
脚本清单（scripts/）
| 脚本 | 作用 |
|---|---|
sync_timeline.py |
时间轴 → data.json（TASKS + KEYDATE，含合并单元格 carry-forward、短名→全称） |
patch_html.py |
data.json → HTML（注入 TASKS/KEYDATE + 红框初始值 + 叙事扫除），并做 node 语法自检 |
reminder_dispatch.py |
到期前 3 天邮件提醒，周末提前至周五；--send 真实发，默认 dry-run |
build_reminder_calendar.py |
提醒日历 Excel（提醒明细 / 责任人缺口 / 人员名单三表） |
参考文档（references/）
data_sourcing.md— 数据源接入、+cells-get命令、返回结构、合并单元格与字段索引dashboard_patterns.md— 单文件看板架构、刷新门控、i18n、里程碑红框同步、甘特渲染、部署pitfalls.md— 真实踩坑与避坑
