# OCDP 文档中心

欢迎查阅 OCDP 项目文档。本目录包含开发、部署、功能和安全相关的详细文档。

---

## 📚 文档导航

### 🚀 快速开始

新用户请先阅读根目录的快速开始文档：

- **[快速开始指南](../QUICK_START.md)** - 5分钟快速上手
- **[使用指南](../USAGE_GUIDE.md)** - Docker 统一配置详细说明
- **[命令速查表](../COMMANDS_CHEATSHEET.md)** - 常用命令快速参考

---

## 📖 核心文档

### 🔧 开发文档

- **[开发规范](./development/specification.md)**
  - 代码规范和最佳实践
  - 项目架构说明
  - 开发工作流程
- **[命名约定对照表](./development/naming-conventions.md)**
  - 前后端命名一致性
  - JSON 与 OpenAPI 映射
  - 常见字段示例
- **[Go vs TypeScript 对照](./development/go-vs-typescript.md)**
  - 命名约定差异
  - 自动转换方案
  - 双端代码示例

### 🎨 功能文档

- **[Artifact MediaType 过滤](./features/ARTIFACT_MEDIATYPE_FILTER.md)**
  - 功能说明和技术实现
  - API 使用示例
  - 类型识别规则

- **[MediaType 过滤测试](./features/TESTING_MEDIATYPE_FILTER.md)**
  - 功能测试指南
  - 测试场景和用例
  - 故障排查

### 🚢 部署文档

- **[Docker 部署指南](./deployment/docker-guide.md)**
  - Docker 环境搭建
  - 生产环境部署
  - 配置说明

### 🔒 安全文档

- **[安全实践](./security/security-implementation.md)**
  - 安全配置指南
  - 认证和授权
  - 数据加密

---

## 📁 文档结构

```
docs/
├── README.md                           # 本文档（文档索引）
│
├── development/                        # 开发相关
│   ├── go-vs-typescript.md            # Go / TS 命名对照
│   ├── naming-conventions.md          # 命名约定
│   └── specification.md               # 开发规范
│
├── features/                          # 功能文档
│   ├── ARTIFACT_MEDIATYPE_FILTER.md  # Artifact 过滤功能
│   └── TESTING_MEDIATYPE_FILTER.md   # 功能测试指南
│
├── deployment/                        # 部署相关
│   └── docker-guide.md               # Docker 部署指南
│
├── security/                          # 安全相关
│   └── security-implementation.md    # 安全实践
│
└── archive/                           # 历史归档
    ├── root-cleanup/                 # 根目录清理存档
    └── …                             # 其他里程碑记录
```

---

## 🔗 相关资源

### 根目录文档

项目根目录还包含以下重要文档：

- **[README.md](../README.md)** - 项目主页和概述
- **[QUICK_START.md](../QUICK_START.md)** - 5分钟快速开始
- **[USAGE_GUIDE.md](../USAGE_GUIDE.md)** - 详细使用指南
- **[COMMANDS_CHEATSHEET.md](../COMMANDS_CHEATSHEET.md)** - 命令速查表

### 归档文档

历史报告与结果被移动到 `docs/archive/`，保留查阅但不再在根目录占位。例如：

- `docs/archive/root-cleanup/` - 命名迁移、测试总结等历史记录
- `docs/archive/PROJECT_RESTRUCTURE_SUMMARY.md` 等

### API 文档

- **[OpenAPI 规范](../backend/docs/openapi.yaml)** - RESTful API 定义

---

## 🎯 按场景查找文档

### 我是新手，想快速了解项目

1. [README.md](../README.md) - 项目概述
2. [QUICK_START.md](../QUICK_START.md) - 快速开始
3. [USAGE_GUIDE.md](../USAGE_GUIDE.md) - 使用指南

### 我要开始开发

1. [开发规范](./development/specification.md) - 了解开发规范
2. [USAGE_GUIDE.md](../USAGE_GUIDE.md) - 了解如何运行项目
3. [COMMANDS_CHEATSHEET.md](../COMMANDS_CHEATSHEET.md) - 常用命令

### 我要部署到生产环境

1. [Docker 部署指南](./deployment/docker-guide.md) - 部署步骤
2. [USAGE_GUIDE.md](../USAGE_GUIDE.md) - 运行与配置
3. [安全实践](./security/security-implementation.md) - 安全配置

### 我要了解某个功能

1. [功能文档](./features/) - 查看功能列表
2. [OpenAPI 规范](../backend/docs/openapi.yaml) - API 定义

---

## 📝 文档编写指南

如果您想为项目贡献文档：

### 文档原则

- ✅ **清晰简洁** - 使用简单直接的语言
- ✅ **结构化** - 使用标题、列表、代码块
- ✅ **示例丰富** - 提供实际的命令和代码示例
- ✅ **保持更新** - 及时更新过时的内容

### 文档分类

- **开发文档** → `docs/development/`
- **功能文档** → `docs/features/`
- **部署文档** → `docs/deployment/`
- **安全文档** → `docs/security/`
- **快速参考** → 项目根目录

### Markdown 格式

```markdown
# 标题

## 二级标题

### 三级标题

- 列表项
- 列表项

\`\`\`bash
# 代码示例
make docker-dev
\`\`\`

**粗体** 和 *斜体*
```

---

## 🆘 需要帮助？

如果文档中没有找到您需要的信息：

1. 💬 查看项目 [GitHub Discussions](https://github.com/your-repo/discussions)
2. 🐛 提交 [GitHub Issue](https://github.com/your-repo/issues)
3. 📧 联系项目维护者

---

## 📊 文档更新记录

### 2025-11-11
- ✅ 移动根目录历史文档到 `docs/archive/`
- ✅ 新增开发类文档（命名约定、Go/TS 对照）
- ✅ 更新文档索引与结构展示
- ✅ 保持根目录仅包含核心入门文档

### 2025-11-09
- ✅ 清理重复和过时的文档
- ✅ 整理文档结构
- ✅ 更新文档索引
- ✅ 精简文档数量从 13 个减少到 6 个

---

<div align="center">
  <sub>保持文档简洁，提升查找效率</sub>
</div>