ocdp v1
This commit is contained in:
mangomqy
212
docs/README.md
Normal file
212
docs/README.md
Normal file
@ -0,0 +1,212 @@
|
||||
# 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>
|
||||
Reference in New Issue
Block a user