gavindiaz/vibe-coding-cn
1
0
Fork 0
mirror of https://github.com/tradecatlabs/vibe-coding-cn.git synced 2026-08-21 06:48:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(i18n): 重构中文文档结构并同步更新链接

Browse Source 
主要变更：

1.  **目录重命名**:
    *   将  下的 , ,  重命名为中文的 , , 。
2.  **新增新手入门**:
    *   创建  目录，为新用户提供入门指南。
3.  **文件迁移与清理**:
    *   将原有文档迁移到新的中文目录结构下。
    *   删除了部分过时或重复的中文文档。
4.  **链接与脚本同步**:
    *   更新了根 ,  以及  中所有指向旧路径的链接。
    *   修改了  下的英文文档，以反映中文文档的结构变化。
    *   更新了  翻译脚本，使其能够处理新的中文路径。

此次重构统一了中文文档的目录命名，使其更符合中文用户的习惯，并优化了整体文档的组织结构，提升了可维护性。
This commit is contained in:
tukuaiai
2025-12-17 12:07:54 +08:00
parent 9b42dd10dd
commit e239f9e4b8
33 changed files with 753 additions and 738 deletions
Download Patch File Download Diff File Expand all files Collapse all files
i18n/en/documents/Templates and Resources/General_Project_Architecture_Template.md
+49 -439
View File
@@ -1,461 +1,71 @@
TRANSLATED CONTENT:
# 通用项目架构模板
# General Project Architecture Template
## 1️⃣ Python Web/API 项目标准结构
## 1️⃣ Standard Structure for Python Web/API Projects
```
项目名称/
├── README.md # 项目说明文档
├── LICENSE # 开源协议
├── requirements.txt # 依赖管理（pip）
├── pyproject.toml # 现代Python项目配置（推荐）
├── setup.py # 包安装脚本（如果做成库）
├── .gitignore # Git忽略文件
├── .env # 环境变量（不提交到Git）
├── .env.example # 环境变量示例
├── CLAUDE.md # claude持久上下文
├── AGENTS.md # codex持久上下文
├── Sublime-Text.txt # 放需求和注意事项，给自己看的，和cli的会话恢复指令^_^
ProjectName/
├── README.md # Project description document
├── LICENSE # Open-source license
├── requirements.txt # Dependency management (pip)
├── pyproject.toml # Modern Python project configuration (recommended)
├── setup.py # Package installation script (if used as a library)
├── .gitignore # Git ignore file
├── .env # Environment variables (not committed to Git)
├── .env.example # Example environment variables
├── CLAUDE.md # Claude persistent context
├── AGENTS.md # Codex persistent context
├── Sublime-Text.txt # For demands and notes, for myself, and CLI session recovery commands ^_^
│
├── docs/ # 文档目录
│ ├── api.md # API文档
│ ├── development.md # 开发指南
│ └── architecture.md # 架构说明
├── docs/ # Documentation directory
│ ├── api.md # API documentation
│ ├── development.md # Development guide
│ └── architecture.md # Architecture description
│
├── scripts/ # 脚本工具
│ ├── deploy.sh # 部署脚本
│ ├── backup.sh # 备份脚本
│ └── init_db.sh # 数据库初始化
├── scripts/ # Script tools
│ ├── deploy.sh # Deployment script
│ ├── backup.sh # Backup script
│ └── init_db.sh # Database initialization
│
├── tests/ # 测试代码
├── tests/ # Test code
│ ├── __init__.py
│ ├── conftest.py # pytest配置
│ ├── unit/ # 单元测试
│ ├── integration/ # 集成测试
│ └── test_config.py # 配置测试
│ ├── conftest.py # Pytest configuration
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── test_config.py # Configuration tests
│
├── src/ # 源代码（推荐方式）
├── src/ # Source code (recommended)
│ ├── __init__.py
│ ├── main.py # 程序入口
│ ├── app.py # Flask/FastAPI应用
│ ├── config.py # 配置管理
│ ├── main.py # Program entry point
│ ├── app.py # Flask/FastAPI application
│ ├── config.py # Configuration management
│ │
│ ├── core/ # 核心业务逻辑
│ ├── core/ # Core business logic
│ │ ├── __init__.py
│ │ ├── models/ # 数据模型
│ │ ├── services/ # 业务服务
│ │ └── utils/ # 工具函数
│ │ ├── models/ # Data models
│ │ ├── services/ # Business services
│ │ └── utils/ # Utility functions
│ │
│ ├── api/ # API接口层
│ ├── api/ # API interface layer
│ │ ├── __init__.py
│ │ ├── v1/ # 版本1
│ │ ├── v1/ # Version 1
│ │ └── dependencies.py
│ │
│ ├── data/ # 数据处理
│ ├── data/ # Data processing
│ │ ├── __init__.py
│ │ ├── repository/ # 数据访问层
│ │ └── migrations/ # 数据库迁移
│ │ ├── repository/ # Data access layer
│ │ └── migrations/ # Database migrations
│ │
│ └── external/ # 外部服务
│ └── external/ # External services
│ ├── __init__.py
│ ├── clients/ # API客户端
│ └── integrations/ # 集成服务
│ ├── clients/ # API clients
│ └── integrations/ # Integration services
│
├── logs/ # 日志目录（不提交到Git）
├── logs/ # Log directory (not committed to Git)
│ ├── app.log
│ └── error.log
│
└── data/ # 数据目录（不提交到Git）
├── raw/ # 原始数据
├── processed/ # 处理后的数据
└── cache/ # 缓存
```
**使用场景**：Flask/FastAPI Web应用、RESTful API服务、Web后端
---
## 2️⃣ 数据科学/量化项目标准结构
```
项目名称/
├── README.md
├── LICENSE
├── requirements.txt
├── .gitignore
├── .env
├── .env.example
├── CLAUDE.md # claude持久上下文
├── AGENTS.md # codex持久上下文
├── Sublime-Text.txt # 放需求和注意事项，给自己看的，和cli的会话恢复指令^_^
│
├── docs/ # 文档目录
│ ├── notebooks/ # Jupyter文档
│ └── reports/ # 分析报告
│
├── notebooks/ # Jupyter Notebook
│ ├── 01_data_exploration.ipynb
│ ├── 02_feature_engineering.ipynb
│ └── 03_model_training.ipynb
│
├── scripts/ # 脚本工具
│ ├── train_model.py # 训练脚本
│ ├── backtest.py # 回测脚本
│ ├── collect_data.py # 数据采集
│ └── deploy_model.py # 模型部署
│
├── tests/ # 测试
│ ├── test_data/
│ └── test_models/
│
├── configs/ # 配置文件
│ ├── model.yaml
│ ├── database.yaml
│ └── trading.yaml
│
├── src/ # 源代码
│ ├── __init__.py
│ │
│ ├── data/ # 数据处理模块
│ │ ├── __init__.py
│ │ ├── collectors/ # 数据采集器
│ │ ├── processors/ # 数据清洗
│ │ ├── features/ # 特征工程
│ │ └── loaders.py # 数据加载
│ │
│ ├── models/ # 模型模块
│ │ ├── __init__.py
│ │ ├── strategies/ # 交易策略
│ │ ├── backtest/ # 回测引擎
│ │ └── risk/ # 风险管理
│ │
│ ├── utils/ # 工具模块
│ │ ├── __init__.py
│ │ ├── logging.py # 日志配置
│ │ ├── database.py # 数据库工具
│ │ └── api_client.py # API客户端
│ │
│ └── core/ # 核心模块
│ ├── __init__.py
│ ├── config.py # 配置管理
│ ├── signals.py # 信号生成
│ └── portfolio.py # 投资组合
│
├── data/ # 数据目录（Git忽略）
│ ├── raw/ # 原始数据
│ ├── processed/ # 处理后数据
│ ├── external/ # 外部数据
│ └── cache/ # 缓存
│
├── models/ # 模型文件（Git忽略）
│ ├── checkpoints/ # 检查点
│ └── exports/ # 导出模型
│
└── logs/ # 日志（Git忽略）
├── trading.log
└── errors.log
```
**使用场景**：量化交易、机器学习、数据分析、AI研究
---
## 3️⃣ Monorepo（多项目仓库）标准结构
```
项目名称-monorepo/
├── README.md
├── LICENSE
├── .gitignore
├── .gitmodules # Git子模块
├── docker-compose.yml # Docker编排
├── CLAUDE.md # claude持久上下文
├── AGENTS.md # codex持久上下文
├── Sublime-Text.txt # 这个是文件，放需求和注意事项，给自己看的，和cli的会话恢复指令^_^
│
├── docs/ # 全局文档
│ ├── architecture.md
│ └── deployment.md
│
├── scripts/ # 全局脚本
│ ├── build_all.sh
│ ├── test_all.sh
│ └── deploy.sh
│
├── backups/ # 放备份文件
│ ├── archive/ # 放旧的备份文件
│ └── gz/ # 放备份文件的gz
│
├── services/ # 微服务目录
│ │
│ ├── user-service/ # 用户服务
│ │ ├── Dockerfile
│ │ ├── requirements.txt
│ │ ├── src/
│ │ └── tests/
│ │
│ ├── trading-service/ # 交易服务
│ │ ├── Dockerfile
│ │ ├── requirements.txt
│ │ ├── src/
│ │ └── tests/
│ ...
│ └── data-service/ # 数据服务
│ ├── Dockerfile
│ ├── requirements.txt
│ ├── src/
│ └── tests/
│
├── libs/ # 共享库
│ ├── common/ # 公共模块
│ │ ├── utils/
│ │ └── models/
│ ├── external/ # 第三方库（不可修改，只调用）
│ └── database/ # 数据库访问库
│
├── infrastructure/ # 基础设施
│ ├── terraform/ # 云资源定义
│ ├── kubernetes/ # K8s配置
│ └── nginx/ # 反向代理配置
│
└── monitoring/ # 监控系统
├── prometheus/ # 指标收集
├── grafana/ # 可视化
└── alertmanager/ # 告警
```
**使用场景**：微服务架构、大型项目、团队协作
---
## 4️⃣ Full-Stack Web 应用标准结构
```
项目名称/
├── README.md
├── LICENSE
├── .gitignore
├── docker-compose.yml # 前后端一起编排
├── CLAUDE.md # claude持久上下文
├── AGENTS.md # codex持久上下文
├── Sublime-Text.txt # 放需求和注意事项，给自己看的，和cli的会话恢复指令^_^
│
├── frontend/ # 前端目录
│ ├── public/ # 静态资源
│ ├── src/ # 源码
│ │ ├── components/ # React/Vue组件
│ │ ├── pages/ # 页面
│ │ ├── store/ # 状态管理
│ │ └── utils/ # 工具
│ ├── package.json # NPM依赖
│ └── vite.config.js # 构建配置
│
└── backend/ # 后端目录
├── requirements.txt
├── Dockerfile
├── src/
│ ├── api/ # API接口
│ ├── core/ # 业务逻辑
│ │ └── models/ # 数据模型
└── tests/
```
**使用场景**：全栈应用、SPA单页应用、前后端分离项目
---
## 📌 核心设计原则
### 1. 关注点分离（Separation of Concerns）
```
API → 服务 → 数据访问 → 数据库
一目了然，层级清晰
```
### 2. 可测试性（Testability）
```
每个模块可独立测试
依赖可mock
```
### 3. 可配置性（Configurability）
```
配置与代码分离
环境变量 > 配置文件 > 默认值
```
### 4. 可维护性（Maintainability）
```
代码自解释
合理的文件命名
清晰的目录结构
```
### 5. 版本控制友好（Git-Friendly）
```
data/、logs/、models/ 添加到 .gitignore
只提交源代码和配置示例
```
---
## 🎯 最佳实践建议
1. **使用 `src/` 目录**：把源代码放在专门的src目录，避免顶级目录混乱
2. **相对导入**：统一使用 `from src.module import thing` 的导入方式
3. **测试覆盖**：保证核心业务逻辑有单元测试和集成测试
4. **文档先行**：重要模块都要写README.md说明
5. **环境隔离**：使用virtualenv或conda创建独立环境
6. **依赖明确**：所有依赖都写入requirements.txt，并锁定版本
7. **配置管理**：使用环境变量 + 配置文件的组合方式
8. **日志分级**：DEBUG、INFO、WARNING、ERROR、FATAL
9. **错误处理**：不要吞掉异常，要有完整的错误链
10. **代码规范**：使用black格式化，flake8检查
---
## 🔥 .gitignore 推荐模板
```gitignore
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
*.egg-info/
dist/
build/
# 环境
.env
.venv/
env/
venv/
ENV/
# IDE
.vscode/
.idea/
*.swp
*.swo
*~
# 数据
data/
*.csv
*.json
*.db
*.sqlite
*.duckdb
# 日志
logs/
*.log
# 模型
models/
*.h5
*.pkl
# 临时文件
tmp/
temp/
*.tmp
.DS_Store
```
---
## 📚 技术选型参考
| 场景 | 推荐技术栈 |
|-----|----------|
| Web API | FastAPI + Pydantic + SQLAlchemy |
| 数据处理 | Pandas + NumPy + Polars |
| 机器学习 | Scikit-learn + XGBoost + LightGBM |
| 深度学习 | PyTorch + TensorFlow |
| 数据库 | PostgreSQL + Redis |
| 消息队列 | RabbitMQ / Kafka |
| 任务队列 | Celery |
| 监控 | Prometheus + Grafana |
| 部署 | Docker + Docker Compose |
| CI/CD | GitHub Actions / GitLab CI |
---
## 📝 文件模板示例
### requirements.txt
```txt
# 核心依赖
fastapi==0.104.1
uvicorn[standard]==0.24.0
pydantic==2.5.0
# 数据库
sqlalchemy==2.0.23
alembic==1.12.1
psycopg2-binary==2.9.9
# 测试
pytest==7.4.3
pytest-cov==4.1.0
pytest-asyncio==0.21.1
# 工具
python-dotenv==1.0.0
loguru==0.7.2
# 开发（可选）
black==23.11.0
flake8==6.1.0
mypy==1.7.1
```
### pyproject.toml（现代Python项目推荐）
```toml
[project]
name = "项目名称"
version = "0.1.0"
description = "项目描述"
authors = [{name = "作者", email = "邮箱@example.com"}]
dependencies = [
"fastapi>=0.104.0",
"uvicorn[standard]>=0.24.0",
"sqlalchemy>=2.0.0",
]
[project.optional-dependencies]
dev = ["pytest", "black", "flake8", "mypy"]
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"
```
---
## ✅ 新项目检查清单
启动新项目时，确保完成以下事项：
- [ ] 创建README.md，包含项目简介和使用说明
- [ ] 创建LICENSE文件，明确开源协议
- [ ] 设置Python虚拟环境（venv/conda）
- [ ] 创建requirements.txt并锁定依赖版本
- [ ] 创建.gitignore，排除敏感和不必要的文件
- [ ] 创建.env.example，说明需要的环境变量
- [ ] 设计目录结构，符合关注点分离原则
- [ ] 创建基础的配置文件
- [ ] 设置代码格式化工具（black）
- [ ] 设置代码检查工具（flake8/ruff）
- [ ] 编写第一个测试用例
- [ ] 设置Git仓库并提交初始代码
- [ ] 创建CHANGELOG.md，记录版本变更
---
**版本**: 1.0
**更新日期**: 2025-11-24
**维护**: CLAUDE，CODEX，KIMI
└── data/ # Data directory (not committed to Git)
├── raw/ # Raw data
├── processed/ # Processed data
└── cache/ # Cache
```