BFM Pay

Appearance

丛书编写标准 ​

本文档定义 KeyApp 技术丛书的编写规范，作为撰写和审稿的依据。

1. 丛书结构标准 ​

1.1 索引完整性 ​

index.md 必须列出所有 Book

规则要求
MUST每个顶层目录在 index.md 中有对应条目
MUSTBook 编号与目录编号一致
MUST描述准确反映内容

Book 分类:

  • 📙 E-Series: Engineering (工程手册) - 面向开发流程
  • 📘 T-Series: Technical (技术参考) - 面向实现细节
  • 📗 F-Series: Functional (业务指南) - 面向业务功能

1.2 目录命名规范 ​

{序号}-{英文名}/
├── README.md          # Book 入口 (MUST)
├── 00-Overview.md     # 概览 (SHOULD)
├── 01-{Chapter}/      # 章节目录
│   ├── 01-{Section}.md
│   └── 02-{Section}.md
└── ...

命名规则:

规则要求示例
MUST顶层目录使用 {2位序号}-{PascalCase}01-Kernel-Ref
MUST子目录使用 {2位序号}-{PascalCase}01-Process
MUST文件使用 {2位序号}-{PascalCase}.md01-State-Machine.md
MUST每个目录有 README.md 或 00-Index.md-
SHOULD目录名与内容主题对应-

1.3 Book 入口标准 ​

每个 Book 的 README.md 必须包含:

markdown
# 📘 Book {编号}: {英文名} ({中文名})

> {一句话描述}

## 📖 目录

| 文档 | 说明 |
|------|------|
| [章节1](./path) | 描述 |
| [章节2](./path) | 描述 |

---

## 🎯 核心要点

{3-5 个核心要点}

---

## 相关文档

- [相关 Book 1](../path)
- [相关 Book 2](../path)

2. 文档内容标准 ​

2.1 文档头部 ​

每个文档必须以标题和描述开始:

markdown
# 文档标题

> 源码: [`src/path/`](https://github.com/BioforestChain/KeyApp/blob/main/src/path/)

---

规则:

规则要求
MUST有一级标题
SHOULD有源码链接 (技术文档)
SHOULD使用 --- 分隔主要章节

2.2 源码链接规范 ​

格式: 使用绝对 GitHub URL

markdown
> 源码: [`src/services/wallet/`](https://github.com/BioforestChain/KeyApp/blob/main/src/services/wallet/)

规则:

规则要求
MUST技术参考文档必须有源码链接
MUST使用 blob/main/ 指向主分支
MUST NOT使用相对路径链接源码
SHOULD链接到目录而非单个文件 (除非特指)

2.3 行为约束标记 ​

使用 RFC 2119 关键词标记规范:

关键词含义使用场景
MUST必须遵守违反将导致功能缺陷或安全问题
MUST NOT禁止行为违反将导致严重问题
SHOULD建议遵守不遵守会降低质量
SHOULD NOT不建议可能导致问题
MAY可选实现增强但非必需

格式:

markdown
| 约束级别 | 要求 |
|----------|------|
| **MUST** | 私钥永不上传服务器 |
| **SHOULD** | 使用后清除内存 |
| **MAY** | 支持远程锁定 |

2.4 代码示例规范 ​

格式:

markdown
### 使用示例

\`\`\`typescript
// 简短注释说明用途
const example = doSomething()
\`\`\`

规则:

规则要求
MUST指定语言 (typescript, json, bash 等)
MUST代码可独立运行或有完整上下文
SHOULD包含简短注释
SHOULD NOT包含过长的代码块 (>50行拆分)

2.5 表格规范 ​

格式:

markdown
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 值1 | 值2 | 值3 |

规则:

规则要求
MUST表头与分隔符对齐
SHOULD列宽适中，避免过长
SHOULD表格有上下文说明

2.6 图表规范 ​

使用 ASCII 图表:

markdown
\`\`\`
┌─────────────┐
│   模块 A    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   模块 B    │
└─────────────┘
\`\`\`

规则:

规则要求
MUST使用等宽字体字符 (Box Drawing)
SHOULD图表宽度 < 80 字符
SHOULD图表有标题或说明

3. 交叉引用标准 ​

3.1 内部链接 ​

同 Book 内:

markdown
[章节名](./01-Chapter/01-Section.md)

跨 Book:

markdown
[Security Reference](../08-Security-Ref/README.md)

规则:

规则要求
MUST使用相对路径
MUST链接目标存在
SHOULD每个文档末尾有"相关文档"章节

3.2 相关文档章节 ​

每个文档末尾应有:

markdown
---

## 相关文档

- [相关文档1](./path1.md) - 简短描述
- [相关文档2](../other/path2.md) - 简短描述

4. 内容完整性标准 ​

4.1 技术参考 (T-Series) 必须包含 ​

章节要求
源码链接MUST
接口/类型定义MUST
使用示例MUST
行为约束SHOULD
相关文档SHOULD

4.2 业务指南 (F-Series) 必须包含 ​

章节要求
业务流程图MUST
状态定义SHOULD
边界条件SHOULD
错误处理SHOULD
相关文档SHOULD

4.3 工程手册 (E-Series) 必须包含 ​

章节要求
快速开始MUST
命令参考MUST
配置说明SHOULD
常见问题MAY

5. 审稿检查清单 ​

5.1 结构检查 ​

  • [ ] index.md 列出所有 Book
  • [ ] 每个目录有 README.md
  • [ ] 文件命名符合规范
  • [ ] 编号连续无跳跃

5.2 内容检查 ​

  • [ ] 每个文档有一级标题
  • [ ] 技术文档有源码链接
  • [ ] 代码示例指定语言
  • [ ] 表格格式正确
  • [ ] 行为约束使用标准关键词

5.3 链接检查 ​

  • [ ] 内部链接目标存在
  • [ ] 源码链接使用绝对 URL
  • [ ] 相关文档章节完整

5.4 一致性检查 ​

  • [ ] 术语使用一致 (参考术语表)
  • [ ] 格式风格一致
  • [ ] 中英文混排规范 (空格)

6. 中英文混排规范 ​

6.1 空格规则 ​

规则示例
中文与英文之间加空格使用 React 框架
中文与数字之间加空格共 178 个文件
英文与数字之间不加空格React19
全角标点前后不加空格框架，包含

6.2 标点规则 ​

规则要求
中文语境使用全角标点
英文/代码语境使用半角标点
列表项不加句末标点

7. 版本与更新 ​

7.1 文档版本 ​

markdown
---
version: 1.0
lastUpdated: 2024-01-07
---

7.2 变更记录 ​

重大更新应在 CHANGELOG 中记录:

markdown
## [1.1.0] - 2024-01-15
### Added
- 新增 Security Reference
### Changed
- 重构 UI Reference 结构

附录: 目录编号规范 ​

编号范围用途
00-09元文档 (Manifesto, 索引)
01-09技术参考 (T-Series)
10-19业务指南 (F-Series)
90-98工程手册 (E-Series)
99附录与指南

Released under the MIT License.

Copyright © 2026 BioforestChain