文档总目录

三端项目文档统一放在这个仓（docs），按产品分；不用一个一个文件夹翻，点下面的链接就能跳。md 是源，html 是同一份文档的代码高亮版；改动只改 md，改完重跑生成器同步 html，不直接改 html。以后写文档，一律放这个仓。

在线阅读：文档站（与本仓内容同步）。

网关（gateway）

• board-h743.md（HTML）— H743 板级支撑（第一批）
• device-ota.md（HTML）— 设备端 firmware_update 处理
• firmware-version-block.md（HTML）— 固件版本块（格式 2）
• flash-boot.md（HTML）— 真实 Flash 存储与启动切换
• mqtt.md（HTML）— 网关 MQTT 层
• otp-read.md（HTML）— 网关 OTP 身份读取
• pinmap-h743.md（HTML）— H743 板级引脚表（模组星球 STM32H743VIT6 双网口板）
• provisioning.md（HTML）— 出厂 provisioning 串口协议

签名服务（sign）

本节索引：README.md（HTML）

入门

• usage.md（HTML）— 使用步骤：从零跑通服务签名打包 + 机器调用
• server-readme.md（HTML）— sign-server（server/ 说明）

接口与格式

• sign-server-api.md（HTML）— sign-server 接口文档
• package-format.md（HTML）— GWPK 包格式 v3：共用包 + 按设备包密钥包
• firmware-version-block.md（HTML）— 固件版本块格式 2
• models.md（HTML）— 型号与固件名注册表

测试流程

• 本地开发测试.md（HTML）— 本地开发测试（前后端分离）
• 测试流程.html（仅 HTML）— 测试流程
• 测试流程首页.md（HTML）— 测试流程首页
• sign-tool本地测试流程.md（HTML）— sign-tool 本地测试流程
• sign-server服务检查.md（HTML）— sign-server 服务检查
• 原生库测试流程.md（HTML）— 原生库测试流程
• 固件分发全流程.md（HTML）— 固件分发全流程

部署与开发环境

• 生产环境部署.md（HTML）— 生产环境部署（前后端分离）
• openresty-deployment.md（HTML）— sign-server 网页 OpenResty 部署（静态导出）
• development-environment.md（HTML）— 开发环境（沙盒与 Mac 同一套）

固件写入工具（firmware-tool）

• 固件写入工具设计.md（HTML）— 固件写入工具设计

共享契约（shared）

• mqtt-device-protocol.md（HTML）— MQTT 设备协议规范（v1.2）
• rest-api.md（HTML）— 云端 REST API 契约 v1.1
• integration-test-plan.md（HTML）— 三端联调测试计划（v1）

生成器与规则

• md 是源，html 从 md 生成；改动只改 md，改完重跑生成器同步 html，不直接改 html。
• 生成器：gen_html.py（代码块用 Pygments Monokai 高亮）。
• 全量重生成：python3 gen_html.py README.md gateway/.md sign/.md firmware-tool/.md shared/.md（需先 pip install markdown pygments，或用 mdvenv）。
• 单份生成：python3 gen_html.py <某份 .md>（只生成该份 html，不动其他 html）。
• 各产品仓原 docs/ 位置留有指向这个仓的说明，旧链接不断档。
• SG 那台的 MIGRATION.md、PORTS.md 不在这个仓（留在 SG 上）。
• 相关仓库：gateway https://github.com/ffffxxxjjj/gateway、sign https://github.com/ffffxxxjjj/sign、firmware-tool https://github.com/ffffxxxjjj/firmware-tool。