213 lines
5.4 KiB
Markdown
213 lines
5.4 KiB
Markdown
# 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>
|