docs: 建立完整的项目文档体系

- 创建6大文档分类:需求/设计/API/用户指南/运维/研究
- 添加各目录的 README 和模板说明
- 定义文档命名规范和编写规范
- 建立文档与代码的对应关系

文档目录结构:
├── requirements/  - 业务需求、功能需求、非功能需求
├── design/        - 架构设计、数据库设计、UI设计、集成设计
├── api/           - REST API、事件定义、内部接口
├── user_guide/    - 快速开始、教程、FAQ
├── operations/    - 部署、监控、故障排查
└── research/      - 因子研究、策略研究、回测报告

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-07-01 21:13:44 +08:00
parent 8dd1cf326d
commit a37c43f691
7 changed files with 1127 additions and 0 deletions
+204
View File
@@ -0,0 +1,204 @@
# 运维文档目录
本目录用于存放系统运维相关的文档。
## 目录结构
```
operations/
├── deployment/ # 部署文档
│ ├── local.md
│ ├── server.md
│ └── docker.md
├── monitoring/ # 监控文档
│ ├── metrics.md
│ ├── alerts.md
│ └── logging.md
└── troubleshooting/ # 故障排查
├── common.md
├── critical.md
└── recovery.md
```
## 文档命名规范
| 类型 | 命名格式 | 示例 |
|-----|---------|------|
| 部署文档 | `deployment/环境.md` | `deployment/server.md` |
| 监控文档 | `monitoring/类型.md` | `monitoring/metrics.md` |
| 故障排查 | `troubleshooting/级别-主题.md` | `troubleshooting/critical-order.md` |
## 部署文档模板
### deployment/server.md
```markdown
# 服务器部署指南
## 环境准备
### 硬件要求
- CPU: 4核+
- 内存: 8GB+
- 磁盘: 100GB+
### 软件要求
- OS: Ubuntu 22.04 LTS+
- Python: 3.10+
- 数据库: PostgreSQL 14+
## 部署步骤
### 1. 安装依赖
\`\`\`bash
sudo apt update
sudo apt install python3.11 python3.11-venv postgresql
\`\`\`
### 2. 配置数据库
\`\`\`bash
sudo -u postgres createdb sanguo_trading
sudo -u postgres psql -c "CREATE USER sanguo WITH PASSWORD 'xxx';"
sudo -u postgres psql -c "GRANT ALL ON DATABASE sanguo_trading TO sanguo;"
\`\`\`
### 3. 部署应用
\`\`\`bash
git clone http://192.168.2.154:3000/sanguo/sanguo_vnpy_v2
cd sanguo_vnpy_v2
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements/base.txt
\`\`\`
### 4. 配置服务
创建 systemd 服务文件...
### 5. 启动服务
\`\`\`bash
sudo systemctl start sanguo-trader
sudo systemctl enable sanguo-trader
\`\`\`
## 验证部署
\`\`\`bash
curl http://localhost:8000/health
\`\`\`
```
## 监控文档模板
### monitoring/metrics.md
```markdown
# 系统监控指标
## 核心指标
### 交易相关
| 指标 | 说明 | 告警阈值 |
|-----|------|---------|
| order_latency | 订单延迟 | >100ms |
| order_success_rate | 订单成功率 | <99% |
| position_sync_rate | 持仓同步率 | <95% |
| tick_delay | 行情延迟 | >500ms |
### 系统相关
| 指标 | 说明 | 告警阈值 |
|-----|------|---------|
| cpu_usage | CPU使用率 | >80% |
| memory_usage | 内存使用率 | >85% |
| disk_io | 磁盘IO | >90% |
## 告警规则
\`\`\`yaml
alerts:
- name: OrderDelay
condition: order_latency > 100
action: send_alert
severity: warning
\`\`\`
## 监控工具
- Prometheus + Grafana
- 日志分析
```
## 故障排查模板
### troubleshooting/critical.md
```markdown
# 紧急故障处理手册
## 故障分级
| 级别 | 描述 | 响应时间 |
|-----|------|---------|
| P0 | 系统不可用 | 15分钟 |
| P1 | 核心功能异常 | 1小时 |
| P2 | 部分功能异常 | 4小时 |
| P3 | 轻微问题 | 1个工作日 |
## 常见紧急场景
### 场景1: 订单无法下发
**症状**
- 订单一直处于提交中状态
- 日志显示连接超时
**排查步骤**
1. 检查网络连接
2. 检查接口状态
3. 查看错误日志
**解决方案**
\`\`\`bash
# 重启接口连接
systemctl restart sanguo-gateway
\`\`\`
### 场景2: 行情中断
**症状**
- K线图不再更新
- Tick 数据停止
**排查步骤**
...
## 紧急联系人
| 角色 | 姓名 | 电话 |
|-----|------|------|
| 开发负责人 | xxx | xxx |
| 运维负责人 | xxx | xxx |
| 业务负责人 | xxx | xxx |
```
## 运维检查清单
### 日常检查(每日)
- [ ] 系统运行状态
- [ ] 接口连接状态
- [ ] 错误日志检查
- [ ] 数据备份确认
### 周期检查(每周)
- [ ] 磁盘空间检查
- [ ] 性能指标分析
- [ ] 安全补丁更新
### 月度检查(每月)
- [ ] 备份恢复测试
- [ ] 灾备演练
- [ ] 容量规划评估