文档贡献规范

本页说明如何为 EnerOS 撰写与维护文档，包括本网站（eneros-web）与 crate 内嵌文档（cargo doc）。EnerOS 文档是用户与开发者理解系统的关键入口，高质量的文档与高质量的代码同等重要。

文档类型

EnerOS 文档按受众与用途分为以下类型：

文档受众矩阵

不同文档针对不同读者，写作前请先明确受众：

文档结构

标准结构

每个文档应遵循以下结构：

1. Frontmatter：元数据（标题、描述、分类、顺序）
2. 一级标题：与 title 一致
3. 导语：1-3 句话说明文档目的与受众
4. 正文：分章节阐述，使用二级 / 三级标题
5. 示例：完整可运行的代码或配置
6. 检查清单：关键操作的可勾选项
7. 相关文档：交叉链接

标题层级规范

规则：

• 标题层级不跳级（不要从 ## 直接跳到 ####）
• 标题前后保留空行
• 标题使用名词或动宾短语，避免疑问句
• 标题不使用标点符号结尾

段落与列表

• 段落之间空一行
• 列表项之间不空行（除非项内含多个段落）
• 有序列表用于步骤，无序列表用于并列项
• 列表前后保留空行

Frontmatter 规范

所有 Markdown 文件必须包含 frontmatter：

---
title: "文档标题"
description: "一句话描述"   # 可选但推荐
category: "快速开始"          # 须与侧栏分组一致
order: 3                      # 同 category 内排序
---

字段说明

分类与 order

完整示例

---
title: "测试规范"
description: "测试分层与 cargo test 使用"
category: "贡献指南"
order: 3
---

# 测试规范

EnerOS 拥有 7300+ 测试用例，覆盖所有核心功能。本页详述测试分层、编写规范与 CI 流程。

## 测试分层

...

写作规范

语言

• 主语言：中文优先
• 专有名词保留英文：mTLS、SCADA、RTU、IEC 61850、GraphQL、WebSocket、SSE、Token、Cookie
• 缩略词首次出现给出全称：潮流计算（Power Flow）、能量管理系统（EMS）
• 数字与单位：阿拉伯数字 + SI 单位，如 12ms、100kW、1.06 p.u.
• 中英文混排：中英文之间加空格，如”使用 Rust 编写”
• 标点：中文使用全角标点，代码与数字使用半角

代码块

• 必须标注语言：```rust、```bash、```toml、```yaml、```json、```sql
• 代码块前后保留空行
• 代码示例须可运行或可编译，避免伪代码
• 长代码块（> 30 行）应拆分为多个，配合逐步说明
• 命令行示例使用 $ 前缀或注释说明

# 安装依赖
sudo apt install -y libssl-dev

# 构建项目
cargo build --release

链接

• 内部链接使用相对路径：[测试规范](/docs/contributing/testing)
• 避免硬编码域名（除 GitHub 仓库与文档站首页）
• 链接文本应有意义，避免”点击这里”
• 检查链接有效性，避免 404

# 正确
详见 [测试规范](/docs/contributing/testing)。

# 错误
详见 [这里](/docs/contributing/testing)。

表格

• 用于对比、映射、参数说明，优于长段落
• 表头简洁，每列对齐
• 单元格内容简短，详细说明放在段落中
• 复杂表格拆分为多个

强调

• 加粗：用于强调关键词、警示
• 斜体：用于术语首次出现、外来词
• 行内代码：用于代码标识符、文件名、命令、参数名
• 避免滥用强调，每段最多 1-2 处

提示框

使用引用块表达提示、警告、注意：

> **提示**：使用 `cargo nextest run` 比 `cargo test` 更快。

> **警告**：生产环境务必修改 `audit.toml` 中的 `hmac_key`。

> **注意**：实时域功能仅在 Linux 上获得完整支持。

示例代码规范

• 须可运行或可编译，避免伪代码与省略号
• 不要使用 // ... 省略关键逻辑
• 包含完整的 use 语句与导入
• 复杂示例分步骤展示，每步可独立验证

// 正确：完整示例
use eneros_powerflow::{NewtonRaphsonSolver, PowerflowResult};
use eneros_topology::Topology;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let topo = Topology::from_ieee_14bus();
    let solver = NewtonRaphsonSolver::new(50, 1e-8);
    let result: PowerflowResult = solver.solve(&topo)?;
    println!("收敛: {}", result.converged);
    Ok(())
}

// 错误：使用省略号
// fn main() {
//     let topo = ...;
//     let result = solver.solve(...);
//     ...
// }

术语表

首次出现的关键术语应给出全称与缩写：

Crate 内嵌文档规范

文档注释

公共 API 必须有文档注释 ///，通过 cargo doc 校验：

/// 求解给定拓扑的潮流方程。
///
/// 使用牛顿-拉夫逊法迭代求解，最大迭代次数由 `max_iterations` 控制。
/// 当相邻两次迭代电压差小于 `tolerance` 时认为收敛。
///
/// # 参数
/// - `topology`：电网拓扑，须已完成孤岛检测
/// - `max_iterations`：最大迭代次数，建议 20-50
/// - `tolerance`：收敛容差，默认 1e-8
///
/// # 返回
/// 返回 [`PowerflowResult`]，包含每个母线的电压、相角与支路功率。
///
/// # 错误
/// - [`PowerflowError::NonConvergence`]：迭代次数超限仍未收敛
/// - [`PowerflowError::InvalidTopology`]：拓扑数据不完整或存在环
///
/// # 示例
///
/// ```rust
/// use eneros_powerflow::{NewtonRaphsonSolver, PowerflowResult};
/// use eneros_topology::Topology;
///
/// let topo = Topology::from_ieee_14bus();
/// let solver = NewtonRaphsonSolver::new(20, 1e-8);
/// let result: PowerflowResult = solver.solve(&topo).unwrap();
/// assert!(result.converged);
/// ```
pub fn solve(&self, topology: &Topology) -> Result<PowerflowResult> {
    unimplemented!()
}

rustdoc 章节

模块文档

lib.rs 与 mod.rs 顶部应有 //! 模块文档：

//! # EnerOS Power Flow
//!
//! 电网潮流计算模块，支持牛顿-拉夫逊法与快速解耦法。
//!
//! ## 概览
//!
//! - [`NewtonRaphsonSolver`]：牛顿-拉夫逊法，收敛快但计算量大
//! - [`FastDecoupledSolver`]：快速解耦法，适用于配网
//!
//! ## 示例
//!
//! ```rust
//! use eneros_powerflow::NewtonRaphsonSolver;
//! use eneros_topology::Topology;
//!
//! let topo = Topology::from_ieee_14bus();
//! let solver = NewtonRaphsonSolver::new(50, 1e-8);
//! let result = solver.solve(&topo).unwrap();
//! ```

文档测试

cargo doc 中的示例代码会被作为测试执行：

# 运行所有文档测试
cargo test --doc --workspace

# 运行特定 crate 的文档测试
cargo test --doc -p eneros-powerflow

文档测试要求：

• 代码必须可编译
• 使用 # 隐藏不必要的行（如 # use ...）
• 使用 no_run 跳过执行但验证编译：```rust,no_run
• 使用 ignore 完全跳过：```rust,ignore
• 使用 should_panic 验证 panic：```rust,should_panic

/// ```rust,no_run
/// # use eneros_powerflow::NewtonRaphsonSolver;
/// // 这段代码会编译但不会运行
/// let solver = NewtonRaphsonSolver::new(50, 1e-8);
/// ```

翻译指南

支持的语言

EnerOS 文档目前支持以下语言：

翻译流程

1. 认领任务：在 GitHub Issues 中筛选 i18n 标签，留言认领
2. 基于最新 main：拉取最新代码，避免与原文不同步
3. 翻译：保留代码块原样，仅翻译注释与说明文字
4. 校对：母语者校对，确保术语准确
5. 提交 PR：标题标注 [i18n]，如 [i18n] Translate testing.md to English

翻译规范

• 代码块原样保留：不翻译代码、命令、配置、文件路径
• 代码注释：可翻译，但保留 // 或 # 前缀
• 专有名词：保留英文，如 mTLS、SCADA、Rust、Cargo
• 链接：内部链接保持不变，外部链接可替换为对应语言版本
• frontmatter：title 与 description 翻译，category 与 order 保持不变
• 术语统一：参考术语表，保持与已翻译文档一致

Fluent 本地化

eneros-i18n crate 使用 Fluent 管理界面文案，翻译文件位于 locales/：

locales/
├── en-US.ftl    # 英语
├── zh-CN.ftl    # 简体中文
├── ja-JP.ftl    # 日语
└── es-ES.ftl    # 西班牙语

.ftl 文件示例：

# locales/zh-CN.ftl
powerflow-solving = 正在求解潮流...
powerflow-converged = 潮流计算收敛，迭代 { $iterations } 次
powerflow-failed = 潮流计算失败：{ $error }

# locales/en-US.ftl
powerflow-solving = Solving power flow...
powerflow-converged = Power flow converged in { $iterations } iterations
powerflow-failed = Power flow failed: { $error }

文档构建与预览

本地预览

EnerOS 文档站基于 Fumadocs 构建，使用 Next.js：

cd eneros-web
npm install
npm run dev    # 启动开发服务器，访问 http://localhost:3000

构建生产版本

cd eneros-web
npm run build  # 构建生产版本
npm run start  # 启动生产服务器

构建失败常见原因：

验证文档

# 验证所有 Markdown 文件包含 frontmatter
cd eneros-web
npm run lint

# 检查链接有效性
npm run check-links

# 类型检查
npm run typecheck

Cargo Doc 构建

# 构建所有 crate 文档
cargo doc --no-deps --all-features

# 构建特定 crate 文档
cargo doc --no-deps -p eneros-powerflow

# 在浏览器打开
cargo doc --no-deps --open

# 构建并运行文档测试
cargo test --doc --workspace

部署

文档站部署在 GitHub Pages，由 .github/workflows/deploy-web.yml 自动化：

ADR 贡献

新增架构决策须按 ADR 总览 格式撰写。

ADR 模板

---
title: "ADR 0015: 短标题"
description: "架构决策记录"
category: "ADR"
order: 15
---

# ADR 0015: 短标题

- **状态**：提议 / 已接受 / 已废弃 / 已被替代
- **日期**：2026-07-06
- **决策者**：核心团队

## 背景

（描述促使本决策的背景、问题与约束）

## 决策

（描述做出的具体决策）

## 备选方案

（列出考虑过的其他方案及其优劣）

## 后果

- **正面**：...
- **负面**：...
- **中性**：...

## 参考

- [相关 ADR](/docs/adr/0002-power-native-agentos)
- [外部资料](https://example.com)

ADR 提交流程

1. 在 src/content/docs/adr/ 创建新文件，编号自增
2. 在 src/content/docs/adr/index.md 列表中登记
3. 提交 PR，标题 docs(adr): 新增 ADR 0015 ...
4. 至少一位架构师 Review
5. 合并后状态为”已接受”

完整文档示例

以下是一个完整的能力文档示例，展示各规范的应用：

---
title: "潮流计算能力"
description: "EnerOS 潮流计算引擎的能力、接口与示例"
category: "能力"
order: 3
---

# 潮流计算能力

EnerOS 提供高性能的潮流计算（Power Flow）引擎，支持牛顿-拉夫逊法与快速解耦法，适用于输电网与配电网分析。本页介绍其能力、接口与使用示例。

## 支持的求解方法

| 方法 | 适用场景 | 收敛性 | 性能 |
|------|---------|--------|------|
| 牛顿-拉夫逊（Newton-Raphson） | 输电网、强耦合系统 | 强 | 中 |
| 快速解耦（Fast Decoupled） | 配电网、辐射状系统 | 中 | 高 |
| 直流潮流（DC Power Flow） | 规划、近似分析 | 弱 | 极高 |

## API 使用

### Rust API

```rust
use eneros_powerflow::{NewtonRaphsonSolver, PowerflowResult, PowerflowError};
use eneros_topology::Topology;
use std::time::Duration;

fn main() -> Result<(), PowerflowError> {
    // 加载 IEEE 14-bus 标准测试系统
    let topo = Topology::from_ieee_14bus();

    // 创建求解器
    let solver = NewtonRaphsonSolver::new(50, 1e-8);

    // 求解
    let result: PowerflowResult = solver.solve(&topo)?;

    // 输出结果
    println!("收敛: {}", result.converged);
    println!("迭代次数: {}", result.iterations);
    for bus in &result.buses {
        println!(
            "Bus {}: V = {:.4} p.u., θ = {:.4} rad",
            bus.id, bus.voltage_magnitude, bus.voltage_angle
        );
    }

    Ok(())
}
```

### REST API

```bash
# 求解潮流
curl -X POST http://localhost:8080/api/powerflow/solve \
    -H "Content-Type: application/json" \
    -d @ieee14.json

# 预期响应
# {
#   "converged": true,
#   "iterations": 4,
#   "buses": [
#     {"id": 1, "v": 1.06, "theta": 0.0},
#     ...
#   ]
# }
```

## 性能指标

| 测试用例 | 节点数 | 平均延迟 | 内存占用 |
|---------|--------|---------|---------|
| IEEE 14-bus | 14 | < 12ms | 2 MB |
| IEEE 30-bus | 30 | < 18ms | 4 MB |
| IEEE 118-bus | 118 | < 45ms | 12 MB |
| IEEE 300-bus | 300 | < 120ms | 28 MB |

## 限制与约束

- 输入拓扑须已完成孤岛检测
- 平衡节点（Slack Bus）必须存在且唯一
- 节点电压须在 [0.5, 1.5] p.u. 范围内

> **警告**：潮流计算不收敛时返回 `PowerflowError::NonConvergence`，调用方应处理此错误而非 unwrap。

## 检查清单

- [ ] 拓扑已完成孤岛检测
- [ ] 已设置平衡节点
- [ ] 节点编号无重复
- [ ] 阻抗参数非零

## 相关文档

- [电网拓扑](/docs/capabilities/grid-topology) - 拓扑引擎
- [安全约束](/docs/capabilities/physics-constraint) - 约束引擎
- [潮流计算教程](/docs/tutorials/load-flow) - 完整教程
- [API 参考](/docs/api-reference/rest) - REST API

文档贡献检查清单

提交文档 PR 前请逐项检查：

• frontmatter 完整（title / description / category / order）
• title 与首行 # 标题 一致
• 标题层级不跳级
• 代码块标注语言
• 代码示例可运行或可编译（无 // ... 省略）
• 内部链接使用相对路径
• 链接有效，无 404
• 表格字段完整，无遗漏列
• 中英文之间加空格
• 术语首次出现给出全称
• npm run build 通过
• cargo doc --no-deps 通过（涉及 crate 文档时）
• 已更新 CHANGELOG.md（如涉及行为变更）

相关文档

• 贡献流程总览
• Pull Request 流程
• 开发环境搭建
• ADR 总览
• 项目结构