======= 研发任务（日复盘 + H5 管理）— 冷启动文件 =======

> 版本: 4.4 ｜ 日期: 2026-08-27 ｜ 用途: 研发任务日复盘推送 + H5 任务管理工具的冷启动/重建/排障手册
> 服务器: 腾讯云轻量 lhins-1dai07vu ｜ 系统: Ubuntu ｜ 时区: Asia/Shanghai
> 工作流: ①**研发任务日复盘**（工作日09:00微信推送）②**研发任务 H5**（http://82.156.85.124:13544/rd/ 浏览器管理）③**钉钉日报**（工作日10:00发钉钉群）
> v4.4 更新: 负责人折叠选择器（默认收起点击展开，去+更多）、创建任务/子任务可带更新内容、日报子任务只显最新一条、家务每日小初按摩+每10天施肥（家庭侧）
> v4.3 更新: 钉钉全家桶（通讯录MCP+免登+组织架构同步+权限控制）、人员库 people.json 动态化+勾选快捷栏、日报（昨日/今日可选+子任务归属去重+钉钉群webhook发送 cron 52967bf00170）、负责人钉钉下拉+自定义、更新记录倒序、AI对话语言表(SOUL.md)
> v4.2 更新: raw 前缀自动补全（后端 add/update 保证 [优先级](项目) 前缀，防微信复盘缺显示）、name 字段撤回（列表仍显示 raw）、详情页任务名称输入框保留
> v4.1 更新: 临时小任务独立体系（独立序号/无项目优先级/时间补填/组内分类统计）、子任务更新【任务名-子任务名·负责人】、更新与进度解耦、跟踪任务开始/结束时间自动记录、任务名称字段
> v4.0 更新: 新增 H5 管理工具章节（部署/API/功能/同步机制/排障）；v3.0 的负责人彩色分组、编号复用、工作日周期规则保留

---

====== 1. 工作流总览 ======

<code>
~/docs/rd_tasks.json（唯一数据源）
  ├─→ 复盘推送: cron b9dbd39c3f34（工作日 09:00）→ rd_daily_review.py → 微信
  └─→ H5 管理: systemd rd-h5.service（:13544）→ rd_h5.py + rd_h5.html → 浏览器
         ↑ 双向同步：H5 里改任务 → JSON → 复盘推送同步显示
</code>

**两个入口（同一份数据）：**
| 入口 | 用途 | 地址 |
|------|------|------|
| 微信复盘 | 每日 09:00 自动推送任务清单+超期提示 | cron b9dbd39c3f34 |
| H5 管理 | 浏览器操作（筛选/进度/子任务/日报/只读）| http://82.156.85.124:13544/rd/ |
| H5 只读 | 给团队/领导查看（无编辑权限）| http://82.156.85.124:13544/rd/?ro=1 |

====== 2. 文件清单 ======

| 文件 | 说明 |
|------|------|
| ~/docs/rd_tasks.json | 任务清单（唯一数据源，H5 与复盘共用）|
| ~/docs/rd_tasks_completed.json | 已完成任务归档 |
| ~/.hermes/scripts/rd_daily_review.py | 复盘生成器（cron 调用，no_agent）|
| ~/.hermes/scripts/rd_task_update.py | 微信更新工具（--add 编号复用）|
| ~/.hermes/scripts/rd_history.py | 历史查询（--month/--week/--last/--all）|
| ~/.hermes/scripts/rd_h5.py | **H5 后端**（Flask :13544，API + 日报 + 免登 + 组织架构）|
| ~/.hermes/scripts/rd_h5.html | **H5 前端**（单文件，无外链）|
| ~/.hermes/scripts/rd_logo.jpg | H5 首页慧飞 logo |
| ~/.hermes/scripts/ding_daily_report.py | 日报发送钉钉群（webhook 通道）|
| ~/docs/people.json | 人员库（简称→全名 + roles 管理员名单）|
| ~/docs/ding_org.json | 钉钉组织架构快照 |
| ~/docs/AI对话语言表.md | AI 行为规范（已并入 SOUL.md）|
| /etc/systemd/system/rd-h5.service | H5 常驻服务（开机自启，root 运行）|
| cron b9dbd39c3f34 | 复盘推送（0 9 * * 1-5，no_agent）|
| cron 52967bf00170 | 钉钉日报（0 10 * * 1-5，no_agent → ding_daily_report.py）|
| cron af464d70c514 | 古筝课每周课时（无关，勿混）|

====== 3. H5 管理工具（v4 新增） ======

**启动/重启：** `sudo systemctl restart rd-h5.service`（用 ctwing-2 venv 的 python，有 flask）

**API 一览：**
| 接口 | 方法 | 功能 |
|------|------|------|
| /rd/ | GET | H5 页面（no-cache 头）|
| /rd/?ro=1 | GET | 只读模式（隐藏所有编辑入口）|
| /rd/logo.jpg | GET | 首页 logo |
| /api/tasks | GET | 任务列表（含 owner_map/projects）|
| /api/tasks | POST | 新增任务（type: track/temp）|
| /api/tasks/&lt;id&gt; | POST | 更新（priority/owners/project/status/progress/subtasks）|
| /api/tasks/&lt;id&gt; | DELETE | 删除（编号释放）|
| /api/tasks/&lt;id&gt;/note | POST | 记录更新（自动+2%，99 封顶）|
| /api/tasks/&lt;id&gt;/subtask/&lt;i&gt;/note | POST | 子任务更新（+2%，记录【子任务·负责人】）|
| /api/report/today | GET | 生成研发中心日报（?date=昨日/今日可选；星级评价+只读链接）|
| /api/ding/login | POST | 钉钉免登：authCode → 员工身份（userid/name）|
| /api/ding/org | GET | 钉钉组织架构同步（30分钟缓存）|
| /api/people | GET/POST | 人员库查询/加入（自动简称）|

**H5 功能清单（v4.1，用户定稿）：**
- 筛选：优先级/项目/状态/更新天数(1-30 工作日)/搜索/人员点击(多选)
- 默认按人员分组，组内分 **📌跟踪任务 / ⏱️临时小任务** 两个子区；点人显示主负责+子任务负责两组；"全部"按钮
- 进度条：宽度=百分比数字（.pfill 必须 display:block）；**进度仅手动设置（更新内容不加进度，2026-08-26 定稿）**；有子任务时任务进度=子任务平均
- 详情页：任务名称/内容/项目/多负责人/优先级/状态/进度可改；**状态含 未开始/进行中/暂停/已完成**；**开始时间=设进行中或首次更新时自动记录，结束时间=设已完成时自动记录**
- **负责人选择器**：折叠式（默认收起只显示已选，点击"👤 选择负责人"展开钉钉人员复选框勾选）；人员=钉钉通讯录固定
- **创建任务可带更新内容**：新增表单（跟踪/临时）有"更新"输入框，创建时自动记录
- **创建子任务可带更新内容**：子任务行"更新内容"输入，保存任务后自动记录【任务名-子任务名·负责人】
- 子任务管理：名称/负责人/进度/更新内容；子任务更新：内容必填→进度+2%（99 封顶），记入总 notes 格式 `【任务名-子任务名·负责人】内容`
- 新增任务两种类型：
  - 📌**跟踪任务**：持续多人跟踪，时间跨天（字段：任务名称/内容/项目/优先级/负责人）
  - ⏱️**临时小任务**：着急当天完成，5分钟<耗时<2小时，负责人必选（字段：任务名称/内容/负责人/开始时间/耗时；创建后默认进行中，时间可完成后补填）
- 临时小任务显示：**独立序号**（每人每天从1开始⏱️1/⏱️2，历史显示📅日期），无项目/优先级/进度条/更新标记，列表只显示任务名称（详情显示完整内容），组头统计`（N项·共X小时Y分）`
- 生成日报：标题"研发中心日报"，只读链接最前面，负责人全名，任务前【项目名】，星级评价（★~★★★★★）；**今日/昨日可选（?date=）**；**子任务归属**（子任务更新协同主任务显示到子任务负责人名下，同子任务只显示最新一条）
- 今日已更新 ✓ 标记；日期按本地零点计算（防 UTC 偏移）

====== 3.5 钉钉集成（v4.3） ======

- **免登**：钉钉工作台打开 → authCode → /api/ding/login → 员工身份（凭证 .env DINGTALK_CLIENT_ID/SECRET）
- **权限**：people.json roles.admin（武燕青/张景茹/潘保琰/席江锋/宋逊文/刘瑞红）= 全功能；普通员工=只看自己任务（主负责+子任务）只读；未登录=只读
- **组织架构**：/api/ding/org 拉取钉钉部门+员工（30分钟缓存）；人员筛选快捷栏=钉钉全量+勾选配置（localStorage rd_people_picks）
- **负责人下拉**：钉钉通讯录 + 自定义人员（"＋更多负责人"→ /api/people 自动加入）
- **日报发送**：ding_daily_report.py → 群机器人 webhook（.env DINGTALK_GROUP_WEBHOOK，研发中心日报群）；cron 52967bf00170 工作日10:00自动发当日日报；命令行支持指定日期（发昨日）
- **钉钉 MCP**（Hermes 侧）：dingtalk-contacts/bot/todo/group/oa（重启 gateway 生效）

====== 4. 推送格式（微信复盘） ======

<code>
📋 研发任务日复盘 2026-08-26（在办 N 项）

🔵武 1: ✅【中】(其他)25年项目验收(8月底统一处理) 📊0%  📝 今日: 内容
🟣张 7: 【中】(P3)P3电路测试(安排) 📊50%  📝 昨天: 内容
...
⏸️ 挂起: ...
⚠️ 超期未更新（工作日）: #N（...）← 超期X个工作日
🏁 已完成: ...
💬 更新方式：发「更新N：内容」或「N：完成」；新增任务发「新增(高)(项目)任务内容」
</code>

**格式铁律：**
- 负责人：彩色圆点+简称（🔵武/🟣张/🟠潘/🔴席/🟢宋/🟡刘/🟤汤/⚪无），按负责人分组，组内高→中→低
- **半角 `[中]` 是微信表情代码会被吞** → 必须全角【】；项目名必须用小括号且不能为空
- ✅ 绿钩=今日更新；📊N%=进度（H5 同步）；📝 只显示最新一条更新（今日覆盖历史）
- 更新记录日期：今日/昨天/前天/M月D日（自然日）
- 编号：阿拉伯数字；完成/删除后**释放复用**（新增用最小空缺，不重排）

====== 5. 更新周期（2026-08-25 定稿，按工作日） ======

| 优先级 | 周期 | 说明 |
|--------|------|------|
| 高 | 1 个工作日 | 每日必更（进度%+内容描述）|
| 中 | 3 个工作日 | |
| 低 | 5 个工作日 | |
| 挂起 | 30 个工作日 | |

- 工作日 = 跳过周六日（H5 筛选与复盘超期提示一致）
- 超期未更新 → ⚠️ 超期提示（H5 任务行红字 + 复盘推送末尾列表）
- 周末不推送（cron 0 9 * * 1-5）

====== 6. 负责人映射与项目规范 ======

**负责人简称→全名（H5 显示全名，复盘显示简称）：**
武=武燕青 ｜ 张=张景茹 ｜ 潘=**潘保琰** ｜ 席=席江峰 ｜ 宋=宋讯文 ｜ 刘=刘瑞红 ｜ 汤=汤宝岩

**项目（2026-08-25 合并定稿）：**
拓远T1（拓远+T1）｜ 普惠P1（P1+普惠P1）｜ 金穗S1（金穗+金穗S1+S1）｜ 其他（研发文件+管理+模具+测试）｜ P3 ｜ P5 ｜ 表压 ｜ 软管泵 ｜ 施肥阀 ｜ AI 等

====== 7. 任务 JSON 结构 ======

<code>
{"id": 4, "raw": "[中](拓远T1)二维码，安排实际尺寸测试",
 "priority": "中", "project": "拓远T1", "name": "二维码实际尺寸测试",
 "owners": ["席"], "last_update": "2026-08-26",
 "done": false, "progress": 51, "status": "进行中",
 "start_time": "2026-08-26 15:50", "end_time": "",
 "notes": [{"date": "2026-08-26", "text": "【任务名-子任务·负责人】内容"}],
 "subtasks": [{"name": "子任务", "owner": "张", "progress": 50}],
 "type": "track", "duration": 0}
</code>

- **id**：编号复用（最小空缺）；**raw**：用户原文（含[优先级](项目名)）
- **owners 数组**（H5 v2+）；旧数据兼容单值 owner（复盘 get_owner 兼容）
- **progress**：仅手动设置（更新内容不加）；有子任务时=子任务平均
- **type**：track/temp；temp 任务含 start_time(当天时间)/duration(5<分钟<120)，创建后默认进行中
- **name**：任务名称（跟踪任务，详情页维护）
- **start_time/end_time**：开始=设"进行中"或首次更新时自动记；结束=设"已完成"时自动记

====== 8. 排障速查（血泪教训） ======

| 症状 | 原因与修复 |
|------|-----------|
| H5 进度条不按比例 | `.pfill` 是 span(inline)，width% 无效 → 加 `display:block` |
| 昨天更新显示"今日" | daysAgo 用 UTC 解析偏移 8h → `setHours(0,0,0,0)` 本地零点 |
| "今日已更新"筛选含昨天 | workdaysBetween `while(d<t)` 漏算今天 → `while(d<=t)` |
| 昨天更新仍在"今日已更新" | 浏览器缓存旧 JS → 后端加 no-cache 头 |
| H5 新增任务复盘显示⚪无 | owners 数组 vs owner 单值 → get_owner 兼容 |
| H5 改项目复盘不更新 | project 字段与 raw 不同步 → update_task 同步 raw 项目名 |
| **H5 保存后复盘缺【优先级】(项目)** | H5 add/update 曾把 raw 存成纯内容丢前缀 → 后端自动补 `[优先级](项目)` 前缀（新增/编辑都保证）|
| 任务内容丢失 | H5 saveTask 空内容覆盖 → `if(raw)body.raw=raw` |
| --add 新增任务优先级解析错 | 正则贪婪 → `^[\(\[]([^\)\]]+)[\)\]]` |
| 挂起任务更新不显示 | v1 bug → 挂起分支也调 note_suffix |
| 微信 [中] 变"中"(项目)丢失 | 半角[]是表情代码 → 全角【】 |
| gateway 内重启被拦截 | 从外部 shell 重启（SIGTERM 传播）|
| 用户报编号对不上 | 编号释放/复用 → 按任务名称匹配 |

====== 9. 冷启动恢复步骤 ======

1. 恢复 ~/docs/rd_tasks.json、rd_tasks_completed.json 与 ~/.hermes/scripts/ 全部脚本（rd_daily_review.py、rd_task_update.py、rd_history.py、rd_h5.py、rd_h5.html、rd_logo.jpg）
2. 复盘 cron：`研发任务日复盘` 工作日 09:00（0 9 * * 1-5），no_agent=true，script=rd_daily_review.py，deliver=origin
3. H5 服务：`sudo cp rd-h5.service /etc/systemd/system/ && sudo systemctl enable --now rd-h5`（用 ctwing-2 venv python 跑）
4. 防火墙放行 13544（腾讯云轻量 ap-beijing lhins-1dai07vu）
5. 测试：`python3 ~/.hermes/scripts/rd_daily_review.py` + `curl http://127.0.0.1:13544/api/tasks`

====== 10. 常用命令 ======

<code>
# 手动生成复盘
python3 ~/.hermes/scripts/rd_daily_review.py
# 微信更新任务
python3 ~/.hermes/scripts/rd_task_update.py "N" "内容"      # 更新
python3 ~/.hermes/scripts/rd_task_update.py "N" "完成" --done  # 完成归档
python3 ~/.hermes/scripts/rd_task_update.py --add "[中](项目)内容"  # 新增(自动最小空缺编号)
# H5 重启
sudo systemctl restart rd-h5.service
# 历史查询
python3 ~/.hermes/scripts/rd_history.py --month 2026-08
# 生成日报
curl http://127.0.0.1:13544/api/report/today
</code>

====== 11. 注意事项 ======

- 任务清单是唯一数据源，改 JSON 前先备份
- **删除任务需用户明确确认**；删除/完成后不重排编号，空缺供新任务复用
- H5 与复盘共用 JSON：H5 里的修改（项目/优先级/负责人/进度/内容/子任务）全部同步到复盘推送
- raw 用户原文一字不改；只加编号/项目/进度展示层转换
- 只读链接 `/rd/?ro=1` 无任何编辑入口，适合外发