Markdown 研发文档管理指南¶

project/
├── docs/                    # 技术文档根目录
│   ├── README.md            # 文档导航/索引（入口）
│   ├── architecture/        # 架构设计
│   │   ├── README.md
│   │   ├── overview.md      # 系统架构总览
│   │   ├── diagrams/        # Mermaid 源文件 (*.mmd)
│   │   └── images/          # 导出的 PNG 图片
│   ├── api/                 # API 接口文档
│   │   ├── README.md
│   │   └── endpoints.md
│   ├── design/              # 设计文档
│   │   └── technical-design.md
│   ├── decisions/           # ADR 架构决策记录
│   │   ├── README.md
│   │   └── adr/
│   │       ├── 001-xxx.md
│   │       └── 002-xxx.md
│   ├── ops/                 # 运维文档
│   │   ├── deployment/
│   │   └── monitoring/
│   ├── references/          # 参考文件
│   │   ├── specs/           # 规格说明（Excel/CSV）
│   │   ├── templates/       # 文档模板
│   │   └── exports/         # 导出文件（PDF/PNG）
│   └── templates/           # Markdown 模板
│       ├── adr-template.md
│       └── doc-template.md
├── scripts/
│   └── render-diagrams.sh   # Mermaid 渲染脚本
└── assets/                  # 公共资源
    ├── images/
    └── diagrams/

docs/
├── hardware/        # 硬件设计
│   ├── schematics/  # 原理图
│   └── bom/         # 物料清单
├── firmware/        # 固件文档
└── cloud/           # 云平台

docs/
├── models/          # 模型文档
│   ├── training/    # 训练
│   └── inference/   # 推理
└── api/
    ├── endpoints/   # 端点详情
    └── auth/        # 认证

# 文档和代码一起提交
git add docs/
git commit -m "docs: 添加系统架构设计 v2.1"

# 追踪文档变更
git log --oneline -- docs/
git diff HEAD~1 -- docs/architecture/

# 文档标签
git tag -a docs/v1.0.0 -m "技术文档 v1.0 基线"

docs: 添加 API 接口文档 v1.2
- 新增 /api/v1/completion 接口
- 更新认证方式说明
- 添加请求示例

## 架构图

```mermaid
graph TB
    A[前端] --> B[网关]
    B --> C[后端服务]

**自动导出 PNG：**
```bash
# 安装
npm install -g @mermaid-js/mermaid-cli

# 渲染单个
npx mmdc -i docs/architecture/diagrams/system.mmd \
         -o docs/architecture/images/system.png \
         -b transparent -w 2x

# 批量渲染
./scripts/render-diagrams.sh

dot -Tpng architecture.dot -o images/architecture.png

docs/module/
├── module.md          # 文档
├── diagrams/          # 图表源文件
│   ├── arch.mmd       # Mermaid
│   └── flow.drawio    # draw.io
└── images/            # 图片
    ├── arch.png       # 从 Mermaid 导出
    ├── screenshot.png # 截图
    └── generated/     # 自动生成

## 接口参数

核心参数（Markdown 表格，可版本管理）：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| user_id | string | 是 | 用户唯一标识 |
| token | string | 是 | 认证令牌 |

完整参数表：[api-params.xlsx](references/specs/api-params.xlsx)

# scripts/excel-to-csv.py
import pandas as pd

df = pd.read_excel("references/specs/api-params.xlsx")
df.to_csv("references/specs/api-params.csv", index=False)

# 在 CI 中自动同步
python3 scripts/excel-to-csv.py
git add references/specs/*.csv

references/specs/
├── api-params.xlsx      # 原始 Excel（不版本管理或 LFS）
├── api-params.csv       # 导出 CSV（版本管理）
├── test-cases.xlsx
└── bom-master.xlsx      # BOM 总表

# 用 Git LFS 管理大文件
git lfs install
git lfs track "*.xlsx" "*.png" "*.pdf"
echo "*.xlsx filter=lfs diff=lfs merge=lfs -text" >> .gitignore

# ADR-001: 选择 STM32 作为主控 MCU

**状态：** Accepted
**日期：** 2026-03-12

## 上下文
需要一款性价比高的 MCU...

## 决策
选择 STM32F4 系列

## 后果
+ 生态成熟，开发成本低
- Flash 容量有限

Proposed → Accepted → (Deprecated → Superseded by NNN)

# .github/workflows/docs.yml
name: Docs
on:
  push:
    paths: ['docs/**']
jobs:
  render-diagrams:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install -g @mermaid-js/mermaid-cli
      - name: Render diagrams
        run: |
          find docs -name "*.mmd" | while read f; do
            dir=$(dirname "$f")
            base=$(basename "$f" .mmd)
            mkdir -p "$dir/../images"
            npx mmdc -i "$f" -o "$dir/../images/$base.png" -b transparent
          done
      - name: Commit
        run: |
          git config user.name "docs-bot"
          git add docs/
          git diff --cached --quiet || git commit -m "chore: auto-render diagrams"
          git push

# [文档标题]

> [一句话描述]

---

## 概述

## 详细设计

## 接口/配置

## 部署

## 参考

---

*最后更新：YYYY-MM-DD*