From 78df903debb4840ad52092282414f4c77faee212 Mon Sep 17 00:00:00 2001 From: yangzhijia <547486824@qq.com> Date: Tue, 15 Sep 2026 09:09:51 +0800 Subject: [PATCH] =?UTF-8?q?docs=EF=BC=9A=E4=BB=8E=20Healthv2.0=20=E5=A4=8D?= =?UTF-8?q?=E5=88=B6=E7=A0=94=E5=8F=91=E8=BF=87=E7=A8=8B=E6=80=A7=E6=9D=90?= =?UTF-8?q?=E6=96=99=E6=A1=86=E6=9E=B6=20+=20=E8=BD=ACWord=E8=AF=B4?= =?UTF-8?q?=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/研发过程性材料-框架.md | 435 ++++++++++++++++++++++++++++++++++++ docs/转Word说明.md | 95 ++++++++ 2 files changed, 530 insertions(+) create mode 100644 docs/研发过程性材料-框架.md create mode 100644 docs/转Word说明.md diff --git a/docs/研发过程性材料-框架.md b/docs/研发过程性材料-框架.md new file mode 100644 index 0000000..8a52cb6 --- /dev/null +++ b/docs/研发过程性材料-框架.md @@ -0,0 +1,435 @@ +--- +title: "五劳无感康养监测系统 — 研发过程性材料" +subtitle: "过程记录 · 版本演进 · 关键问题修复" +version: V1.0（框架版，待补充图/视频） +date: 2026-08-26 +author: 杨志佳 +project: Healthv2.0 +branch: main +git-head: 7845836 +--- + +# 五劳无感康养监测系统 + +## 研发过程性材料 + +> **本文档说明** +> +> - **用途**：面向甲方的研发过程性材料（验收/结项参考）。 +> - **形式**：简要版，约 5–10 页（Word A4）。 +> - **状态**：本版本为**框架**，各章节预留了图位、视频位与文字占位符。研发人员自行补图/视频/详细说明。 +> - **图位标记**：`[📷 图片占位 — 描述]` — 替换为 `![描述](相对路径)`。 +> - **视频位标记**：`[🎬 视频占位 — 描述]` — 替换为 Word 中插入的视频；Markdown 阶段可保留占位符。 +> - **代码/日志贴图位**：`[🖥 屏幕截图位 — 描述]`。 +> - **未提交/进行中标记**：⏳ 标识。 + +--- + +## 目录 + +1. 项目概述 +2. 系统架构与硬件组成 +3. 关键功能演示（视频位） +4. 软件模块划分 +5. 版本演进（Git 历史） +6. 关键 Bug 修复过程（案例） +7. 测试与验证记录 +8. 当前已交付功能 / 待办 + +--- + +## 1. 项目概述 + +### 1.1 项目定位 + +> 【📝 占位 200–300 字。内容方向：】 +> - 项目背景与甲方需求（一句话总结） +> - 设备形态：卫生间/卧室/客厅/阳台/厨房，挂壁式 +> - "无感监测"理念：零穿戴、零接触、隐私优先（雷达不上传原始波形） + +### 1.2 核心能力一览 + +| 维度 | 能力 | +|------|------| +| 生命安全 | 跌倒检测、生命体征异常（心率/呼吸） | +| 环境安全 | 水浸、 温湿度异常 | +| 设备自检 | 雷达超时、 DHT11 故障 | +| 通信 | MQTT V0.08 协议、WiFi 配网、蓝牙配网 | +| 联动 | 本地蜂鸣 + 远程告警、双向告警恢复 | +| 显示 | OLED 多页显示（环境 / 体征 / 状态 / 报警） | + +### 1.3 技术指标（关键参数） + +> 【📝 占位：列出关键阈值——心率 50–120 bpm、呼吸 10–26 次/分、温度 5–45℃、湿度 15–90% RH、上报周期 1s/60s 心跳、报警响应延迟 ≤ 20s】 + +### 1.4 项目实物图 + +【📷 图片占位 — 整机实物照片：外壳 + OLED 显示 + 雷达天线位 + 接线端子】 + +--- + +## 2. 系统架构与硬件组成 + +### 2.1 总体架构（ASCII） + +``` + ┌───────────────────────────┐ + │ 云端 MQTT 服务 │ + │ 202.110.234.102:8000 │ + └─────────────┬─────────────┘ + │ (WiFi, MQTT V0.08) + │ + ┌──────────────────────┴──────────────────────┐ + │ 五劳无感康养监测终端 (本设备) │ + │ │ + │ ┌─────────┐ ┌─────────┐ ┌──────────┐ │ + │ │ R60AFD1 │ │ DHT11 │ │ 水浸传感 │ │ + │ │ 60G雷达 │ │ 温湿度 │ │ GPIO45 │ │ + │ └────┬────┘ └────┬────┘ └────┬─────┘ │ + │ │UART2 │GPIO4 │GPIO45 │ + │ ┌────┴────────────┴─────────────┴──────┐ │ + │ │ ESP32-S3 (双核) │ │ + │ │ │ │ + │ │ 核心0: 雷达解析任务 (10ms) │ │ + │ │ 核心1: 主循环 / WiFi / MQTT / 报警 │ │ + │ └───┬─────┬─────┬─────┬─────┬─────┬───┘ │ + │ │ │ │ │ │ │ │ + │ 蜂鸣 LED OLED 按钮 WiFi NTP │ + │ GPIO21 GPIO9 I2C×2 3键 2.4G 阿里云 │ + └──────────────────────────────────────────────┘ +``` + +### 2.2 硬件清单 + +| 模块 | 型号 | 接口 | 备注 | +|------|------|------|------| +| MCU | ESP32-S3-DevKitC-1 | — | 双核 240MHz, 8MB Flash, PSRAM | +| 雷达 | R60AFD1 60GHz 毫米波 | UART2 (GPIO17/1, 115200) | 跌倒/姿态精准型；卫生间用 | +| 温湿度 | DHT11 | GPIO4 | 单总线，2s 一次 | +| 水浸 | 单数字引脚 | GPIO45 (INPUT_PULLUP) | LOW=有水 | +| 蜂鸣器 | 有源蜂鸣器 | GPIO21 | PWM 预留，实际用 digitalWrite | +| 报警 LED | 红 | GPIO9 | 按报警类型节奏闪烁 | +| WiFi LED | 蓝 | GPIO8 | 状态指示 | +| OLED | SSD1306 128×64 | I2C (GPIO15/16) | 多页显示 | +| 配网按钮 | 微型轻触 | GPIO0 / GPIO14 | 长按 3s | +| 解除按钮 | 微型轻触 | GPIO13 | 一键全解 | +| 翻页按钮 | 微型轻触 | GPIO46 | OLED 页面切换 | + +### 2.3 接线图与实物 + +- 【📷 图片占位 — 接线示意图（杜邦线 / 端子排）】 +- 【📷 图片占位 — PCB / 内部布局】 +- 【📷 图片占位 — 卫生间安装实景（雷达顶装）】 + +### 2.4 引脚定义速查 + +| 功能 | GPIO | 说明 | +|------|------|------| +| 雷达 RX | 17 | 接雷达 TX | +| 雷达 TX | 1 | 接雷达 RX (调试用) | +| 雷达 GPIO1/2 | 2 / 11 | 活跃/有人指示 | +| DHT11 | 4 | 数据线 | +| 水浸 | 45 | INPUT_PULLUP | +| 蜂鸣器 | 21 | OUTPUT | +| LED 报警 | 9 | OUTPUT | +| LED WiFi | 8 | OUTPUT | +| OLED SDA/SCL | 15 / 16 | I2C | +| 按钮：配网 | 0 / 14 | 长按 3s | +| 按钮：解除 | 13 | 单击 | +| 按钮：翻页 | 46 | 单击 | + +--- + +## 3. 关键功能演示（视频位） + +> 每条功能一句要点 + 一个演示视频。视频由研发自拍。 + +| # | 功能 | 要点 | 视频 | +|---|------|------|------| +| 3.1 | 上电自检与启动 | 串口日志显示 "系统就绪" | 【🎬 启动序列】 | +| 3.2 | WiFi 配网（按键 / 远程 / 蓝牙） | 三种配网方式演示 | 【🎬 三种配网】 | +| 3.3 | OLED 多页切换 | 翻页按钮循环：环境/体征/状态/报警 | 【🎬 OLED 翻页】 | +| 3.4 | MQTT 上下行 | 串口 + 服务端抓包联动 | 【🎬 MQTT 报文】 | +| 3.5 | 跌倒报警触发与解除 | 跌倒模拟 → 蜂鸣急促 → 一键解除 | 【🎬 跌倒报警】 | +| 3.6 | 心率/呼吸异常报警 | 阈值内/外对比 | 【🎬 体征异常】 | +| 3.7 | 水浸报警 | 模拟浸水（棉签沾水） | 【🎬 水浸报警】 | +| 3.8 | 远程告警联动 | 服务端下发 → 设备蜂鸣 | 【🎬 远程告警】 | +| 3.9 | 远程告警恢复 | 服务端下发 → 蜂鸣停止 + 重武装 | 【🎬 远程恢复】 | + +--- + +## 4. 软件模块划分 + +### 4.1 模块清单 + +| 模块 | 文件 | 职责 | +|------|------|------| +| 配置中心 | `include/config.h` | 全局宏、阈值、引脚、MQTT 默认参数 | +| 雷达 | `src/radar_manager.cpp` | UART 逐字节解析 + 防抖 | +| 传感器 | `src/sensor_manager.cpp` | DHT11 + 水浸采集、防抖 | +| 报警 | `src/alarm_manager.cpp` | 优先级管理、蜂鸣、LED | +| MQTT | `src/mqtt_manager.cpp` | 连接、订阅、上报、心跳 | +| WiFi | `src/wifi_manager.cpp` | 连接、配网、WiFiManager | +| 按钮 | `src/button_manager.cpp` | 去抖、单击/长按分发 | +| OLED | `src/display_manager.cpp` | 多页渲染 | +| 主程序 | `src/main.cpp` | 主循环 + 本地报警判定 | + +### 4.2 主循环流程（ASCII） + +``` + ┌─────────────────────────────────┐ + │ loop() 核心1 │ + │ 按钮 → WiFi → MQTT → 传感器 │ + │ → 本地报警检查 → 报警模块更新 │ + │ → 遥测上报 → OLED → 10ms delay │ + └──────────────┬──────────────────┘ + │ 双核 + ┌──────────────┴──────────────────┐ + │ radarTask() 核心0 │ + │ 10ms 周期: UART 字节流解析 │ + │ → 防抖 → 数据更新 │ + └─────────────────────────────────┘ +``` + +### 4.3 报警优先级 + +| 优先级 | 类型 | 蜂鸣模式 | LED 闪烁 | +|--------|------|----------|----------| +| ★★★★★ 1 | 跌倒 | 急促连续哔（200/200ms） | 200ms | +| ★★★★★ 2 | 心率/呼吸异常 | 5连急哔 + 停顿 | 500ms | +| ★★★ 3 | 水浸 | 3连哔 + 停顿 | 300ms | +| ★★ 4 | 温湿度异常 | 2声长停 | 800ms | +| ★ 5 | 传感器故障 | 单声长哔 | 1000ms | + +【🖥 屏幕截图位 — 串口日志演示报警触发】 + +--- + +## 5. 版本演进（Git 历史） + +### 5.1 演进时间线 + +``` +2026-07-22 init ───────────┐ + ▼ +2026-07-31 v1.0: 按钮去抖+配网美化+水浸离线+LED独立任务+ + 报警全拓展+有人才检测 ──┐ +2026-08-06 版本1.2 ─────────────────────┤ +2026-08-12 蓝牙配网 ─┐ │ + ├ 修补 bug ┤ 配网完整化 │ + ├ 配编号 ┤ │ + ├ 多设备烧 ┤ │ + └ 清理 ai/ ┘─────────────────┤ + │ +2026-08-14 阈值重整 + 跌倒时间消抖 ← 关键里程碑 +2026-08-17 MQTT 重连修复 + 防抖层加入 + resident 字段还原 +2026-08-18 跌倒 2 帧防抖 + 开机误报修复 ◀── 当前 HEAD (7845836) + ⏳ 进行中: 蜂鸣静音开关（MUTE_VITAL_BUZZER） +``` + +### 5.2 关键 Commit 列表 + +| SHA | 日期 | 类型 | 标题 | 影响 | +|-----|------|------|------|------| +| `49e3abb` | 07-22 | feat | init | 项目初始骨架 | +| `69e927c` | 07-31 | feat | 按钮去抖+配网美化+水浸离线+LED独立任务+报警全拓展+有人才检测 | v1.0 主要能力奠定 | +| `2ce4ac0` | 08-06 | — | 版本1.2 | 阶段化归档 | +| `93112dc` | 08-12 | feat | 增加蓝牙配网功能 | 配网多端支持 | +| `08a055b` | 08-12 | fix | 修补蓝牙配网bug | — | +| `36f5a28` | 08-12 | feat | 增加蓝牙配网设备编号 | — | +| `cc3ba5a` | 08-12 | feat | 增加多设备烧录 | 量产支撑 | +| `8facb8b` | 08-12 | chore | 忽略 ai/sessions/ | 仓库瘦身 | +| `577eafd` | 08-14 | init | init | 重整基线 | +| `9a4b5cf` | 08-14 | fix/feat | 跌倒时间消抖 + 修复误触发报警 | **误报收敛第一阶段** | +| `b960682` | 08-17 | fix | MQTT 断线重连 + 报警阈值修改 | **稳定性提升** | +| `03129c9` | 08-17 | fix/feat | resident 字段还原 + 增加防抖 | **误报收敛第二阶段** | +| `7845836` | 08-18 | feat/fix | 跌倒 2 帧防抖 + 修复开机错误跌倒报警 | **当前 HEAD** | + +### 5.3 各版本能力差异 + +| 阶段 | 新增能力 | 已删除/替换 | +|------|----------|--------------| +| v1.0 | 4 类报警 → 7 类报警；LED 独立任务；有人才检测；离线水浸 | — | +| v1.2 | 蓝牙配网多端、多设备烧录 | — | +| v1.3 | 跌倒时间消抖、阈值下调、远程断线修复 | 部分阈值放宽 | +| v1.4 | 防抖层（运动 3 帧、presence 8 帧） | resident 误判修复 | +| v1.5（当前） | 跌倒 2 帧防抖 + 开机误报修复 | — | +| ⏳ 进行中 | 蜂鸣静音开关（MUTE_VITAL_BUZZER） | 临时测试用，正常模式仍全开 | + +--- + +## 6. 关键 Bug 修复过程（案例） + +> 挑选 3–4 个最有代表性的真实案例，**甲方最能感知**的修复优先。 + +### 6.1 案例：跌倒开机误报 + +- **现象**：设备上电后即触发蜂鸣 + 上报 fall=1。 +- **根因**：R60AFD1 雷达上电自检约 15–30s，期内 `data[3]` 的 fall 位为随机值。 +- **修复**（双层防御）： + - **L1 时间跳过**：`checkLocalAlarms()` 中 `millis() > 30000` 才进入跌倒判定。 + - **L2 数据防抖**：`_filterFall()` 连续 2 帧 fall=true 才置位。 +- **验证**：实测快速坐下不报警；唯一跌倒模拟仍触发。 +- **变更文件**：`main.cpp`（30s 跳过）、`radar_manager.cpp/_filterFall`（2 帧去抖）。 + +【🖥 屏幕截图位 — 开机 30s 内的串口日志 + 修复后日志对比】 + +【🎬 视频位 — 修复前后跌倒模拟对比】 + +### 6.2 案例：跌倒信号抖动 → 报警反复 + +- **现象**：跌倒持续中偶尔清掉，10s 后又触发，反复。 +- **根因**：原 FALL_DETECT_MS 较紧，AFD1 fall 位信号不稳。 +- **修复**： + - 检测阶段：`FALL_DETECT_MS = 10000`（持续 10s 才触发）。 + - 清除阶段：`FALL_CLEAR_MS = 18000`（消失 18s 后才解除，防止误清）。 +- **变更文件**：`main.cpp` 第 70–77 行宏定义、第 354–369 行清除逻辑。 + +【🖥 屏幕截图位 — 修复前后误报序列对比】 + +### 6.3 案例：MQTT 告警阈值调整（误报收敛） + +- **现象**：心率偶发飙到 130+ 触发报警，用户无感。 +- **根因**：原阈值过严，睡眠翻身等场景会让雷达瞬时给出异常心率。 +- **修复**： + - 心率放宽 → 50–120 bpm；呼吸 10–26 次/分。 + - 持续 20s 异常才触发，恢复 15s 才解除。 +- **副作用**：阈值放宽后，需要配合"VITAL_LOST_MS = 60s 生命体征丢失判定"做兜底。 +- **变更文件**：`config.h`、`main.cpp`。 + +### 6.4 案例：resident 字段误判（一波三折） + +- **现象**：在床监测时人未离床，resident 出现 0/1 跳变。 +- **根因**：睡眠帧 `data[3]` 的 bit 含义在 ABD1 与 AFD1 上不同；最初误把 ABD1 的 bit0 当 fall。 +- **修复**： + - ABD1：只取 `bit1` 为 resident，bit0 视为睡眠标志。 + - AFD1：bit0=fall、bit1=resident，二者都报 fall=true 时计数。 +- **教训**：协议文档不严谨导致两次还原（一次"fix"反而误伤，又一次"fix"放开）。 +- **变更文件**：`radar_manager.cpp/_extractSleep`，`include/radar_manager.h`。 + +【📷 图片占位 — 协议字段对比截图（AFD1 vs ABD1）】 + +### 6.5 案例 ⏳ 进行中：蜂鸣静音开关 + +- **当前状态**：未提交（修改 `alarm_manager.h/.cpp`）。 +- **背景**：测试环境心率/呼吸异常频率高，希望保留状态/MQTT/LED 但屏蔽蜂鸣（避免误响）。 +- **方案**： + - 新增编译期宏 `MUTE_VITAL_BUZZER = 1`（默认测试模式）。 + - 新增 `_shouldBuzz(t)`：心率/呼吸返回 false，其余返回 true。 + - `triggerLocal/clearLocal` 蜂鸣开/关前过该判断。 +- **安全约束**：跌倒/水浸**仍必须响**（保障人身安全），代码内注释硬性声明。 +- **预计提交**：测试通过后改回 `0` 重烧，正式版恢复全蜂鸣。 + +--- + +## 7. 测试与验证记录 + +> 【📝 占位：以下各项填实际测试结果】 + +### 7.1 测试环境 + +| 项 | 内容 | +|----|------| +| 固件版本 | v1.5（7845836） + ⏳ MUTE_VITAL_BUZZER | +| 设备编号 | 【编号】 | +| 安装位置 | 【卫生间/卧室/客厅…】 | +| 测试时间 | 【起~止】 | + +### 7.2 测试用例与结果 + +| 编号 | 用例 | 期望 | 实际 | 通过 | +|------|------|------|------|------| +| TC-01 | 上电启动 30s 内不报警 | 30s 内无任何报警 | 【粘贴】 | ✅/❌ | +| TC-02 | 跌倒模拟触发 | 10s 内报 fall=1 | 【粘贴】 | ✅/❌ | +| TC-03 | 快速坐下不报警 | 坐下不报 fall | 【粘贴】 | ✅/❌ | +| TC-04 | 心率 50bpm 持续 20s 触发 | 触发报警 | 【粘贴】 | ✅/❌ | +| TC-05 | 心率恢复 15s 解除 | 解除报警 | 【粘贴】 | ✅/❌ | +| TC-06 | 水浸触发（棉签沾水） | 触发报警 | 【粘贴】 | ✅/❌ | +| TC-07 | 远程告警下发 | 蜂鸣 + LED | 【粘贴】 | ✅/❌ | +| TC-08 | 远程告警恢复 | 蜂鸣停止 | 【粘贴】 | ✅/❌ | +| TC-09 | MQTT 断线恢复 | 60s 内重连 | 【粘贴】 | ✅/❌ | +| TC-10 | 配网 3 种方式 | 全部成功 | 【粘贴】 | ✅/❌ | + +### 7.3 跑分 / 性能数据 + +> 【📝 占位：上报周期实测、内存占用、CPU 占用、MQTT 流量统计】 + +【🖥 屏幕截图位 — 性能面板】 + +--- + +## 8. 当前已交付功能 / 待办 + +### 8.1 ✅ 已交付能力 + +- [x] 7 类报警：跌倒 / 水浸 / 心率异常 / 呼吸异常 / 温度异常 / 湿度异常 / 传感器故障 +- [x] 优先级蜂鸣 + LED 分级闪烁 +- [x] 双核并行：核心 0 雷达 + 核心 1 主循环 +- [x] MQTT V0.08 双向告警（含恢复） +- [x] 三种配网：按键 / 远程 / 蓝牙 +- [x] OLED 多页显示 +- [x] OTA-ready 分区表（默认 8MB） +- [x] 多设备烧录（upload_port 可配） + +### 8.2 ⏳ 进行中 / 待办 + +- [ ] ⏳ **提交 MUTE_VITAL_BUZZER 静音开关**（测试用，正常版应改回 0） +- [ ] 🕒 **水浸「沾水不报警」根因待查** — 数字引脚 + INPUT_PULLUP 默认 HIGH（干），需要确认 `env_type=bathroom` 与水浸硬件接入；需用户提供浴室实机串口日志 +- [ ] 📋 文档：完整协议 V0.08 公开 +- [ ] 🛠 生产固件打包脚本 + +### 8.3 已知限制 + +| 项 | 限制 | 影响 | +|----|------|------| +| R60AFD1 | 不发心跳/呼吸数据 | 心率呼吸类报警仅 ABD1 上有效 | +| OLED 128×64 | 多行不可同屏 | 需要翻页 | +| WiFi | 2.4G only | — | +| MQTT | 仅支持一台设备一对一下发 | 多设备需扩展 | + +--- + +## 附录 A：仓库与构建信息 + +- **仓库**：（公司内 Git 服务器） +- **当前分支**：`main` +- **HEAD Commit**：`7845836`（feat：增加跌倒防抖帧 / fix：修复开机错误跌倒报警。） +- **构建系统**：PlatformIO + Arduino Framework +- **板型**：`esp32-s3-devkitc-1` +- **Flash 分区**：`default_8MB.csv` +- **LittleFS**：用于 WiFi / MQTT / 设备配置持久化 +- **第三方依赖**（来自 `platformio.ini`）： + - `knolleary/PubSubClient@^2.8` + - `bblanchon/ArduinoJson@^7.1.0` + - `adafruit/DHT sensor library@^1.4.6` + - `adafruit/Adafruit Unified Sensor@^1.1.14` + - `olikraus/U8g2@^2.35.30` + +## 附录 B：变更与构建命令 + +```bash +# 烧录 +pio run -t upload --upload-port COM19 + +# 监视 +pio device monitor --port COM19 --baud 115200 + +# 清理 +pio run -t clean + +# 查看当前 git 差异（含未提交） +git diff HEAD + +# 查看已提交历史 +git log --oneline --graph --all +``` + +--- + +**文档结束** + +> **填图/视频小贴士** +> 1. 每条 `【📷 图片占位】` 改成 `![说明](./images/abc.png)`，图片统一放 `docs/images/`。 +> 2. 每条 `【🎬 视频占位】` 在 Markdown 阶段可用占位说明；转 Word 时手动插入"插入 → 联机视频"或本地 MP4。 +> 3. 每条 `【🖥 屏幕截图位】` 直接贴图，建议 1200×800 左右。 +> 4. 所有"⏳ 进行中"项，转交前请与甲方确认是否纳入正式交付范围。 diff --git a/docs/转Word说明.md b/docs/转Word说明.md new file mode 100644 index 0000000..3ae1885 --- /dev/null +++ b/docs/转Word说明.md @@ -0,0 +1,95 @@ +# 框架转 Word（.docx）说明 + +> 当前环境（Git Bash）下未找到 `pandoc`，下面的方案需在你本机执行。 + +--- + +## 1. 安装 Pandoc（一次性） + +### 方案 A：winget（Windows 11 自带，推荐） +```powershell +winget install JohnMacFarlane.Pandoc +``` +安装完关闭当前 PowerShell / Git Bash，重新打开。 + +### 方案 B：Chocolatey +```powershell +choco install pandoc +``` + +### 方案 C：手动下载 +到 https://github.com/jgm/pandoc/releases 下载最新版 `pandoc-X.X.X-windows-x86_64.msi` 双击装即可。 + +### 验证 +```powershell +pandoc --version +``` +看到版本号即成功。 + +--- + +## 2. 转 Word 命令 + +打开 PowerShell 或 Git Bash，`cd` 到仓库根目录： + +### 2.1 最简转换 +```bash +pandoc "docs/研发过程性材料-框架.md" -o "docs/研发过程性材料.docx" +``` + +### 2.2 生成带目录的版本（推荐甲方用） +```bash +pandoc "docs/研发过程性材料-框架.md" -o "docs/研发过程性材料.docx" \ + --toc \ + --toc-depth=3 \ + -V lang=zh-CN \ + -V mainfont="Microsoft YaHei" \ + -V geometry:margin=2.5cm +``` + +### 2.3 加样式的版本（更正式） +如果你有 `reference.docx` 模板（标题、表格、代码块样式）： +```bash +pandoc "docs/研发过程性材料-框架.md" \ + -o "docs/研发过程性材料.docx" \ + --reference-doc=docs/reference.docx \ + --toc --toc-depth=3 +``` + +--- + +## 3. 填图/视频工作流 + +1. 在 Word 中打开 `研发过程性材料.docx`。 +2. 找到每个 `[📷 图片占位 — 描述]`（Word 中显示为 Markdown 文本），删除占位符，**插入 → 图片**。 +3. 每个 `[🎬 视频占位 — 描述]`：**插入 → 联机视频**（B站/腾讯视频URL）或 **插入 → 对象 → 媒体**（本地 MP4）。 +4. 填完所有 `[📝 占位 ...]` 与代码片段。 +5. **最终交付前**： + - 检查所有 ⏳ 项，确认是否纳入正式交付 + - 更新封面日期与版本号 + - 导出 PDF 一并交付（`文件 → 另存为 → PDF`） + +--- + +## 4. 备选方案（不装 Pandoc） + +| 方案 | 操作 | 优缺点 | +|------|------|--------| +| VSCode 插件 | 装 `Markdown PDF` / `Markdown Word` 扩展，右键导出 | 简单，但样式不如 Pandoc | +| 在线工具 | `https://cloudconvert.com/md-to-docx` 上传 → 下载 | 零安装，但内容会过第三方服务器 | +| Typora | 导入 md → 导出 docx | 商业软件，样式好 | +| PowerShell + Word COM | 自动调用 Word.Application 转换（需 Word 已装） | 可批处理但脚本较复杂 | + +如要 PowerShell + Word COM 脚本，告诉我我写给你。 + +--- + +## 5. 文件位置 + +| 文件 | 路径 | +|------|------| +| Markdown 源（你填这个） | `docs/研发过程性材料-框架.md` | +| Word 输出（待生成） | `docs/研发过程性材料.docx` | +| 图片（建议） | `docs/images/`（自己建） | +| 视频（建议） | `docs/videos/`（自己建） | +| 引用样式模板（可选） | `docs/reference.docx` |