文档编写规范

版本: 1.0.0 最后更新: 2025-11-18 状态: 生效中

核心原则

1. AI 优先 (AI-First)

文档结构必须利于 AI 快速定位和理解
使用清晰的标题层级和一致的格式
每个文档开头提供概述和目录
关键信息使用结构化格式（列表、表格、代码块）

2. 当前时态 (Present Tense)

描述现有系统功能，不包含未来计划
使用”系统提供”而非”系统将提供”
记录已实现的功能，不记录规划中的功能
变更历史记录在独立的 CHANGELOG 中
禁止在文档中以”补丁”方式追加变更记录（如”2025-11-16 更新了 XXX”）
禁止保留已删除组件的描述（如”~~已废弃~~“、”~~已移除~~“）
文档应始终反映系统的当前状态，而非记录变化过程
删除组件时，直接从文档中移除相关描述，不保留任何历史痕迹

3. 模块化组织 (Modular Organization)

按模块而非功能组织文档
每个核心模块对应一个架构文档
避免文档职责重叠
模块间引用使用相对链接

内容指南

信息密度要求

核心模块文档: ≥20KB（参考值，与代码复杂度相关）
支撑模块文档: ≥15KB
指南类文档: ≥10KB
重点是有效传达信息，而非追求文件大小

结构要求

使用 Markdown 标准语法
标题层级不超过 4 层（# 到 ####）
每个主要章节包含概述段落
代码示例必须可运行且包含注释

语言规范

标准语言: 中文
专业术语: 首次出现时提供英文对照
代码注释: 关键逻辑使用中文注释
命名规范: 变量和函数名使用英文

敏感信息处理

API 密钥使用占位符：your_api_key_here
内部路径使用通用路径：/path/to/config
数据库连接使用示例值：user:pass@localhost:5432/dbname
保持示例的完整性和可理解性

真实性验证要求

核心原则

必须: 每个技术细节都要在代码中找到对应实现
必须: 引用的文件路径必须真实存在
必须: 配置项必须在代码中有实际使用
禁止: 凭想象添加”应该有”但实际不存在的内容

验证清单

在文档中提及以下内容前，必须验证：

配置文件: 确认 config/*.yaml 文件是否存在
环境变量: 检查 settings.py 中是否定义
API端点: 验证在路由文件中是否实现
部署文件: 确认 Dockerfile、k8s yaml 是否存在
监控端点: 检查 /metrics、/health 等是否实现

常见错误示例

❌ 错误：虚构配置文件

# 错误：假设存在 config/strategy.yaml
strategy:
  enabled: true
  cache_ttl: 3600

✅ 正确：基于实际代码

# 正确：引用实际存在的 settings.py
from infrastructure.config.settings import settings
redis_host = settings.redis_host

❌ 错误：虚构部署配置

# 错误：项目中不存在 Dockerfile
FROM python:3.13-slim
...

✅ 正确：描述实际运行方式

# 正确：描述实际的运行命令
cd backend && source venv/bin/activate
uvicorn main:app --reload

验证工具命令

# 检查配置文件是否存在
ls -la config/
find . -name "*.yaml" -o -name "*.yml"

# 检查环境变量定义
grep "class Settings" backend/infrastructure/config/settings.py

# 检查 API 端点
grep "@app.get\|@app.post" backend/main.py
grep "@router.get\|@router.post" backend/api/v1/endpoints/*.py

# 检查部署文件
ls -la Dockerfile docker-compose.yml
find . -name "*.yaml" | xargs grep -l "kind: Deployment"

文档章节要求

必需章节（基于实际代码）

每个架构文档必须包含以下核心章节：

1. 概述 (Overview) - 必需

模块的实际职责（基于代码）
在系统中的位置和作用
主要功能列表
快速开始（仅当有特定用法时）

2. 组件 (Components) - 必需

实际存在的组件列表
组件间关系（Mermaid 图）
每个组件的职责说明
状态管理（有状态/无状态）

3. 依赖关系 (Dependencies) - 必需

内部依赖（实际 import 的模块）
外部依赖（requirements.txt 中的库）
版本要求（如实际指定）

4. 数据流 (Data Flow) - 必需

数据处理流程（基于实际逻辑）
输入/输出格式（实际的数据结构）
处理步骤（按代码流程）

5. 接口 (Interfaces) - 必需

实际存在的 API 端点
类和方法签名
参数和返回值
使用示例（可运行的代码）

6. 扩展点 (Extension Points) - 仅当存在时

实际的抽象基类
已实现的钩子机制
装饰器和注册机制

7. 配置 (Configuration) - 基于实际

只记录实际存在的配置
settings.py 中的配置项
支持的环境变量
数据库配置（如使用）

禁止包含的内容

以下内容不应出现，除非代码中实际存在：

❌ 虚构的配置文件（如 config/*.yaml）
❌ 不存在的部署配置（Docker/K8s）
❌ 未实现的监控端点（/metrics, /ready）
❌ 通用的运行说明（如 uvicorn main:app）
❌ 假想的故障处理
❌ 虚构的版本兼容性
❌ 不存在的性能指标

质量检查清单

禁止词汇清单

以下词汇不应出现在技术文档中：

模糊形容词（7个）

高性能（使用具体指标）
可扩展（说明如何扩展）
灵活（描述具体灵活性）
鲁棒（使用容错、稳定等）
强大（列举具体功能）
智能（说明具体算法）
先进（使用具体技术名称）

营销语言（5个）

革命性（使用”创新”或具体改进）
突破性（描述具体突破点）
领先（使用行业对比数据）
卓越（使用性能数据）
完美（承认限制和边界）

模糊量词（5个）

大量（使用具体数量）
许多（使用数量范围）
少量（使用具体数值）
若干（明确数量）
部分（指明具体部分）

未来语言检测

以下词汇和模式表示未来计划，应避免使用：

将要、将会、将被
计划实现、计划添加、计划支持
未来将、未来可以
即将推出、即将发布
准备要、准备添加
打算、预计
下一步、接下来
之后会、随后将
正在开发中、开发中
TODO、FIXME（移到 issues）
待实现、待完成
日期标记的变更记录（如”2025-11-16 更新了 XXX”、”Phase 4.1: XXX (2025-11-16)”）
版本号标记的功能（如”v2.0 新增 XXX”，应直接描述当前功能）

Markdown 语法验证

所有内部链接必须有效
代码块必须指定语言
图片必须有 alt 文本
表格必须有表头
列表格式必须一致

图表格式要求

强制使用 Mermaid: 所有架构图、流程图、类图必须使用 Mermaid
禁止格式: 不使用 PNG、SVG、PlantUML 等其他格式
最小要求: 每个核心模块至少包含一个模块关系图
图表类型:
- graph: 模块关系、依赖图
- sequenceDiagram: 交互流程
- classDiagram: 类结构
- stateDiagram: 状态转换
- flowchart: 数据流、业务流程

代码块使用原则

文档中的代码块必须遵循严格的使用规范，避免展示不必要的内部实现细节。

允许使用代码块的场景

扩展点说明
- 展示如何基于抽象类或基类实现扩展功能
- 示例：展示 BaseStrategy 抽象类定义，指导如何实现自定义策略
```
class BaseStrategy(ABC):
  @abstractmethod
  def analyze(self, symbol: str, data: pd.DataFrame) -> Signal:
      pass
```

用法解释

演示如何使用模块提供的接口完成特定任务

示例：展示如何调用交易引擎执行订单

# 使用交易引擎执行订单
engine = TradingEngine()
order = engine.create_order(symbol="AAPL", quantity=100)

多接口协作

指导其他模块如何组合使用多个接口完成功能

示例：展示策略引擎和投票服务的协作

# 组合使用策略引擎和投票服务
strategy_engine = StrategyEngine()
voting_service = VotingService()
signal = voting_service.aggregate([strategy_engine.run(s) for s in strategies])

接口签名
- 展示抽象基类、基类、关键接口的定义
- 包括方法签名、参数类型、返回值类型

禁止使用代码块的场景

内部实现介绍
- ❌ 不展示模块内部的具体实现逻辑
- 示例：不展示 RSIStrategy 的完整实现代码
算法细节
- ❌ 不展示具体的算法实现代码
- 示例：不展示 calculate_rsi() 函数的具体算法
工具函数
- ❌ 不展示内部辅助函数的实现
- 示例：不展示数据清洗、日志记录等辅助函数
私有方法
- ❌ 不展示私有方法或内部细节
- 示例：不展示 _process_internal_data() 等私有方法

判断标准

在决定是否包含代码块时，问自己两个问题：

这段代码是给谁看的？
- 如果是给扩展者或使用者看的 → 保留
- 如果只是展示内部实现 → 删除
这段代码能帮助别人做什么？
- 如果能指导扩展或使用 → 保留
- 如果只是说明”我们怎么做的” → 删除

示例对比

✅ 允许 - 扩展点说明

# 展示如何实现自定义策略
class MyCustomStrategy(BaseStrategy):
    def analyze(self, symbol: str, data: pd.DataFrame) -> Signal:
        # 你的策略逻辑
        return Signal(direction="BUY", confidence=0.8)

❌ 禁止 - 内部实现

# 不要展示 RSIStrategy 的完整实现
class RSIStrategy(BaseStrategy):
    def analyze(self, symbol: str, data: pd.DataFrame) -> Signal:
        rsi = self._calculate_rsi(data)  # 内部算法细节
        if rsi < 30:
            return Signal(direction="BUY", confidence=0.7)
        # ... 更多实现细节

✅ 允许 - 接口使用

# 展示如何使用 FeeCalculator
calculator = FeeCalculator(config)
fee = calculator.calculate_fee(order_type="US", quantity=100, price=150.0)

❌ 禁止 - 算法实现

# 不要展示费用计算的具体算法
def _calculate_us_fee(self, quantity, price):
    platform_fee = max(quantity * 0.005, 1.0)  # 算法细节
    activity_fee = min(quantity * 0.000166, 8.3)  # 算法细节
    # ... 更多计算细节

嵌套代码块格式

当需要在代码块中展示代码块示例时，使用 ~~~ 标记内层：

# 示例：如何编写配置文件

~~~yaml
server:
  host: localhost
  port: 8000
database:
  url: postgresql://localhost:5432/mydb
~~~

文档模板示例

架构文档模板

# [模块名称] 架构文档

## 概述

[模块名称] 负责 [核心职责]，为系统提供 [主要功能]。

**核心功能**：
- 功能 1：[描述]
- 功能 2：[描述]
- 功能 3：[描述]

## 组件

### 组件架构图

~~~mermaid
graph TD
    A[组件A] --> B[组件B]
    B --> C[组件C]
    A --> D[组件D]
~~~

### 核心组件

#### ComponentA
- **职责**: [描述]
- **接口**: [主要方法]
- **依赖**: [依赖项]

#### ComponentB
- **职责**: [描述]
- **接口**: [主要方法]
- **依赖**: [依赖项]

## 依赖关系

### 内部依赖
- `module-a`: 用于 [用途]
- `module-b`: 用于 [用途]

### 外部依赖
| 库名 | 版本 | 用途 |
|------|------|------|
| library-1 | ^1.0.0 | [用途说明] |
| library-2 | ~2.3.0 | [用途说明] |

## 数据流

### 数据处理流程

~~~mermaid
flowchart LR
    Input[输入数据] --> Process[处理逻辑]
    Process --> Transform[数据转换]
    Transform --> Output[输出结果]
~~~

### 数据格式

**输入格式**：
~~~json
{
  "field1": "string",
  "field2": 123
}
~~~

**输出格式**：
~~~json
{
  "result": "processed_value",
  "metadata": {}
}
~~~

## 接口

### REST API

#### `GET /api/v1/resource`

获取资源列表。

**参数**：
- `limit` (可选): 返回数量限制，默认 20
- `offset` (可选): 偏移量，默认 0

**响应**：
~~~json
{
  "data": [],
  "total": 100
}
~~~

**示例**：
~~~bash
curl -X GET "http://localhost:8000/api/v1/resource?limit=10"
~~~

## 扩展点

### 自定义处理器

实现 `BaseProcessor` 接口来创建自定义处理器：

~~~python
from core.base import BaseProcessor

class CustomProcessor(BaseProcessor):
    def process(self, data):
        # 自定义处理逻辑
        return processed_data
~~~

### 注册扩展

~~~python
from core.registry import register_processor

register_processor("custom", CustomProcessor)
~~~

## 配置

### 配置文件

配置文件位于 `config/module.yaml`：

~~~yaml
# 必需配置
database:
  host: localhost
  port: 5432
  name: mydb

# 可选配置
cache:
  enabled: true  # 默认: false
  ttl: 3600     # 默认: 1800
~~~

### 环境变量

支持以下环境变量：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `MODULE_DB_HOST` | 数据库主机 | localhost |
| `MODULE_DB_PORT` | 数据库端口 | 5432 |
| `MODULE_CACHE_ENABLED` | 启用缓存 | false |

版本历史

1.0.0 (2025-11-18): 初始版本，建立文档规范基础

文档编写规范

核心原则

1. AI 优先 (AI-First)

2. 当前时态 (Present Tense)

3. 模块化组织 (Modular Organization)

内容指南

信息密度要求

结构要求

语言规范

敏感信息处理

真实性验证要求

核心原则

验证清单

常见错误示例

❌ 错误：虚构配置文件

✅ 正确：基于实际代码

❌ 错误：虚构部署配置

✅ 正确：描述实际运行方式

验证工具命令

文档章节要求

必需章节（基于实际代码）

1. 概述 (Overview) - 必需

2. 组件 (Components) - 必需

3. 依赖关系 (Dependencies) - 必需

4. 数据流 (Data Flow) - 必需

5. 接口 (Interfaces) - 必需

6. 扩展点 (Extension Points) - 仅当存在时

7. 配置 (Configuration) - 基于实际

禁止包含的内容

质量检查清单

禁止词汇清单

模糊形容词（7个）

营销语言（5个）

模糊量词（5个）

未来语言检测

Markdown 语法验证

图表格式要求

代码块使用原则

允许使用代码块的场景

禁止使用代码块的场景

判断标准

示例对比

嵌套代码块格式

文档模板示例

架构文档模板

版本历史

相关文档