market-data-service/docs/README.md

# 管理后台文档目录

本文档目录包含行情数据服务管理后台的完整开发文档。

## 📢 重要更新

**2026-03-08**: 项目已支持 **Go** 和 **Python** 双实现，所有文档已更新以反映两种实现方式。

| 实现方式 | 目录 | 适用场景 |
|----------|------|----------|
| **Go** | 根目录 `market-data-service/` | 生产环境、高性能需求 |
| **Python** | `python_market_data_service/` | 快速开发、数据源对接 |

---

## 🚀 快速开始

**新手？从这里开始：**

1. **[QUICKSTART.md](../QUICKSTART.md)** - **最快启动指南**（推荐先看）
2. **[startup-guide.md](./startup-guide.md)** - 完整启动教程
3. **[DEPLOY.md](../DEPLOY.md)** - 生产部署指南

---

## 文档列表

### 1. 入门文档

| 文档 | 说明 | 适合读者 |
|------|------|----------|
| [QUICKSTART.md](../QUICKSTART.md) | **最快启动指南** - 30秒启动服务 | **所有用户** |
| [startup-guide.md](./startup-guide.md) | **完整启动指南** - 详细步骤 | **所有用户** |
| [go-installation-guide.md](./go-installation-guide.md) | Go 安装指南 | Go用户 |
| [python-installation-guide.md](#) | Python 安装指南 | Python用户 |

### 2. 部署文档

| 文档 | 说明 | 适合读者 |
|------|------|----------|
| [DEPLOY.md](../DEPLOY.md) | **生产部署指南** - 含Docker和Systemd | 运维人员 |
| [startup-guide.md](./startup-guide.md) | 启动和配置说明 | 开发者 |

### 3. 开发文档

| 文档 | 说明 | 适合读者 |
|------|------|----------|
| [admin-dashboard-development.md](./admin-dashboard-development.md) | 管理后台完整开发文档 | 开发者、架构师 |
| [admin-api-quick-reference.md](./admin-api-quick-reference.md) | API接口速查表 | 前端开发者、测试人员 |
| [architecture.md](./architecture.md) | 架构设计文档 | 架构师、技术负责人 |
| [development-guide.md](./development-guide.md) | 开发指南 - 如何开发新功能 | 开发者 |

### 4. 实现方式对比

| 特性 | Go实现 | Python实现 |
|------|--------|------------|
| 性能 | ⭐⭐⭐ 高 | ⭐⭐ 良好 |
| 开发效率 | ⭐⭐ 中等 | ⭐⭐⭐ 高 |
| 数据源生态 | ⭐⭐ 需封装 | ⭐⭐⭐ 原生支持 |
| 部署复杂度 | ⭐⭐⭐ 简单 | ⭐⭐ 依赖多 |

---

## 快速导航

### 如果你是...

**⏱️ 想最快启动服务：**
1. **必读** [QUICKSTART.md](../QUICKSTART.md) - 30秒启动指南
2. 根据提示选择 Go 或 Python 方式
3. 访问 `http://localhost:8080/admin`

**🔧 还没有安装环境：**
- **Go用户**: 阅读 [go-installation-guide.md](./go-installation-guide.md)
  - Windows用户可直接运行 `scripts/install-go-windows.ps1`
  - Linux/Mac用户运行 `scripts/install-go-linux.sh`
- **Python用户**: 
  1. 安装Python 3.10+：`python --version`
  2. 创建虚拟环境：`python -m venv venv`
  3. 激活环境：`source venv/bin/activate` (Linux) 或 `venv\Scripts\activate` (Windows)
  4. 安装依赖：`pip install -r python_market_data_service/requirements.txt`

**🚀 第一次使用，需要启动服务：**
1. **必读** [QUICKSTART.md](../QUICKSTART.md) - 最快的启动方式
2. 或阅读 [startup-guide.md](./startup-guide.md) - 完整的启动指南
3. 按步骤配置环境、启动服务
4. 访问 `http://localhost:8080/admin`

**📖 第一次接触这个项目：**
1. 先阅读 [QUICKSTART.md](../QUICKSTART.md) 快速体验
2. 选择实现方式（推荐Go用于生产，Python用于开发）
3. 阅读对应的安装指南
4. 阅读 [admin-dashboard-development.md](./admin-dashboard-development.md) 的"功能概述"章节
5. 查看 [architecture.md](./architecture.md) 了解系统架构

**🔌 需要调用管理后台API：**
1. 查看 [admin-api-quick-reference.md](./admin-api-quick-reference.md)
2. 参考其中的cURL示例（接口在Go和Python中完全一致）

**💻 需要开发新功能：**
1. 阅读 [development-guide.md](./development-guide.md)
2. 参考"开发新功能"章节中的场景示例
3. 注意Go和Python的实现差异

**🏗️ 需要进行架构设计：**
1. 查看 [architecture.md](./architecture.md)
2. 参考"设计决策"和"扩展点设计"章节
3. 查看 `python_market_data_service/MIGRATION_GUIDE.md` 了解双实现对等关系

**🚢 需要部署到生产环境：**
1. 阅读 [DEPLOY.md](../DEPLOY.md) - 详细部署指南
2. 选择 Go 或 Python 部署方式
3. 参考Systemd和Docker部署章节

---

## 相关文件

### Go实现代码分布

```
market-data-service/
├── api/
│   ├── admin_types.go          # 类型定义
│   └── admin_router.go         # 路由 + HTML页面
├── internal/
│   ├── handler/
│   │   └── admin.go            # Handler实现
│   └── service/
│       ├── config.go           # 配置服务
│       ├── adapter.go          # 适配器服务
│       └── test.go             # 测试服务
├── cmd/
│   └── server/
│       └── main.go             # 主程序入口
├── QUICKSTART.md              # 快速启动指南
├── DEPLOY.md                  # 部署文档
└── docs/                       # 本文档目录
```

### Python实现代码分布

```
python_market_data_service/
├── app/
│   ├── api/
│   │   ├── routes.py           # 主要API路由
│   │   └── admin_routes.py     # 管理后台路由
│   ├── models/
│   │   ├── types.py            # 基础类型（Pydantic）
│   │   └── admin_types.py      # 管理后台类型
│   ├── services/
│   │   ├── config_service.py   # 配置服务
│   │   ├── adapter_service.py  # 适配器服务
│   │   └── test_service.py     # 测试服务
│   └── main.py                 # FastAPI主应用
├── scripts/
│   └── sync_data.py            # 数据同步工具
├── QUICKSTART.md              # 快速启动指南（根目录）
├── MIGRATION_GUIDE.md          # Go到Python迁移对照
└── README.md                   # Python项目说明
```

---

## 更新记录

| 日期 | 版本 | 说明 |
|------|------|------|
| 2026-03-07 | v1.0 | 初始版本，包含完整管理后台功能文档 |
| 2026-03-07 | v1.1 | 添加启动指南文档 |
| 2026-03-07 | v1.2 | 添加 Go 安装指南和自动安装脚本 |
| 2026-03-08 | v2.0 | **重大更新**: 添加Python实现支持，文档结构重组 |
| 2026-03-08 | v2.1 | 添加QUICKSTART.md快速启动指南 |

---

## 贡献指南

如需更新文档：

1. 修改对应 Markdown 文件
2. 更新本文档的更新记录
3. 确保文档中的代码示例可运行（Go和Python双版本）
4. 保持文档间的链接有效性
5. 如涉及到实现差异，请在文档中标注Go和Python的不同

---

**文档结束**