# doc

**Repository Path**: smart-mip/doc

## Basic Information

- **Project Name**: doc
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 物联网系统文档 (Smart-MIP Docs)

基于 [Docusaurus](https://docusaurus.io/) 构建的物联网系统文档站，包含 MIP 协议规范、系统设计文档和 OpenAPI 自动生成的 API 文档。

## 编译环境

| 依赖 | 最低版本 | 说明 |
|------|---------|------|
| Node.js | `>= 20.0` | JavaScript 运行时 |
| npm | `>= 10.x` | 随 Node.js 20 附带 |

建议使用 [nvm](https://github.com/nvm-sh/nvm) 管理 Node.js 版本：

```bash
nvm install 20
nvm use 20
```

## 快速开始

```bash
# 1. 安装依赖
npm install

# 2. 启动开发服务器（含热更新）
npm start
```

浏览器打开 `http://localhost:3000`。

## 编译过程

### 编译流程图

`npm run build` 执行完整的生产构建，流程如下：

```mermaid
graph TD
    A[npm run build] --> B["prebuild 钩子<br/>npm run gen-api-docs"]
    B --> C["docusaurus gen-api-docs all<br/>从 OpenAPI YAML 生成 API 文档"]
    C --> D["scripts/fix-openapi-mdx.js<br/>修复生成的 MDX 格式"]
    D --> E["docusaurus build<br/>编译所有文档为静态 HTML"]
    E --> F["输出到 build/ 目录"]
```

### 分步说明

```bash
# ===== 步骤 1：生成 API 文档 =====
# 从 docs/api/openapi/*.yaml 自动生成 MDX 页面到 docs/api/openapi/generated/
npm run gen-api-docs

# ===== 步骤 2：编译完整站点 =====
# 执行 prebuild(步骤1) + Docusaurus 构建
npm run build

# ===== 步骤 3：本地预览构建结果 =====
npm run serve
```

> **说明**：`npm run build` 会自动触发 `prebuild` 钩子，先执行 `gen-api-docs` 再编译。因此日常构建只需执行 `npm run build` 即可。

### 编译产物

| 产物 | 路径 | 说明 |
|------|------|------|
| 静态站点 | `build/` | 可直接部署到 Nginx / CDN 的纯静态文件 |
| API 文档 | `docs/api/openapi/generated/` | 由 OpenAPI YAML 自动生成，**不纳入版本控制** |
| 缓存 | `.docusaurus/` | Docusaurus 内部缓存，已加入 `.gitignore` |

## 项目结构

```
doc/
├── docs/
│   ├── protocol/             # MIP 协议文档
│   │   ├── overview.md       #   协议概览
│   │   ├── glossary.md       #   术语表
│   │   ├── transports/       #   传输层协议 (MIPoT / MIPoU / MIPoM)
│   │   ├── frames/           #   帧格式详解 + 字节级示例
│   │   ├── data/             #   数据 ID 定义与映射
│   │   ├── flows/            #   设备接入流程 / 设备发现
│   │   └── examples/         #   接入案例（智能插座等）
│   ├── design/               # 系统设计文档
│   │   ├── architecture/     #   系统架构设计
│   │   ├── database/         #   数据库设计
│   │   ├── security/         #   安全性设计
│   │   └── device-types/     #   设备类型注册表
│   └── api/                  # API 文档
│       ├── openapi/           #   OpenAPI YAML 规范（手工维护）
│       └── openapi/generated/ #   自动生成的 MDX（gitignore）
├── src/                      # 自定义 React 组件与样式
├── static/                   # 静态资源 (logo, favicon)
├── scripts/                  # 构建辅助脚本
│   └── fix-openapi-mdx.js    #   修复 OpenAPI 生成文件的格式问题
├── sidebars.js               # 侧边栏配置
├── docusaurus.config.js      # 站点配置（含 Mermaid 支持）
└── package.json
```

## 可用脚本

| 命令 | 说明 |
|------|------|
| `npm start` | 启动开发服务器，支持热更新 |
| `npm run build` | 完整生产构建（自动触发 gen-api-docs） |
| `npm run serve` | 本地预览 build 目录 |
| `npm run gen-api-docs` | 单独执行 API 文档生成 |
| `npm run clear` | 清理缓存和构建产物 |
| `npm run swizzle` | 弹出 Docusaurus 主题组件（高级） |

## 文档编写指南

### Mermaid 图表

项目已配置 `@docusaurus/theme-mermaid`，使用 `mermaid` 代码块即可渲染图表：

````markdown
```mermaid
sequenceDiagram
    participant A as 客户端
    participant B as 服务端
    A->>B: 请求
    B-->>A: 响应
```
````

### 文件命名

- 英文短横线命名：`device-architecture.md`，`byte-examples.md`
- 目录索引文件统一使用 `overview.md` 或 `readme.md`

## 技术栈

| 组件 | 版本 | 用途 |
|------|------|------|
| Docusaurus | 3.10 | 文档框架 |
| docusaurus-plugin-openapi-docs | 5.x | API 文档自 OpenAPI YAML 生成 |
| @docusaurus/theme-mermaid | 3.10 | Mermaid 图表渲染 |
| @easyops-cn/docusaurus-search-local | 0.55 | 离线中文搜索 |