gavindiaz/vibe-coding-cn
1
0
Fork 0
mirror of https://github.com/tradecatlabs/vibe-coding-cn.git synced 2026-07-28 03:07:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: references - merge architecture templates

Browse Source
This commit is contained in:
tukuaiai
2026-05-02 21:50:59 +08:00
parent fb62a6331b
commit e2e2153b34
8 changed files with 621 additions and 1174 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+2 -2
View File
@@ -390,7 +390,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt
* [**第三方系统提示词学习库**](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools): 用于学习和参考其他 AI 工具的系统提示词。
* [**Skills 制作器**](https://github.com/yusufkaraaslan/Skill_Seekers): 可根据需求生成定制化 Skills 的工具。
* [**元提示词**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): 用于生成提示词的高级提示词。
* [**通用项目架构模板**](docs/references/通用项目架构模板.md): 可用于快速搭建标准化的项目目录结构。
* [**项目架构模板**](docs/references/项目架构模板.md): 可用于快速搭建标准化项目目录，并覆盖 Dataset First 数据服务架构。
* [**元技能：Auto Skill**](./skills/auto-skill/SKILL.md): 用于生成、重构与校验 Skills 的元技能。
### 外部教程与资源
@@ -411,7 +411,7 @@ pip install -r tools/prompts-library/scripts/requirements.txt
* [**编程提示词集合**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): 适用于 Vibe Coding 流程的专用提示词（云端表格）。
* [**系统提示词构建原则**](docs/references/系统提示词构建原则.md): 构建高效 AI 系统提示词的综合指南。
* [**开发经验总结**](docs/references/开发经验.md): 变量命名、文件结构、编码规范、架构原则等。
* [**通用项目架构模板**](docs/references/通用项目架构模板.md): 多种项目类型的标准目录结构。
* [**项目架构模板**](docs/references/项目架构模板.md): 多种项目类型的标准目录结构与数据服务架构模板。
* [**系统提示词集合**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): AI 开发的系统提示词，含多版本开发规范（云端表格）。
* [**TradeCat Sheets API 使用说明**](docs/playbooks/tradecat-sheets-api-usage.md): 把公开 Google Sheet 当作 API 注册表与数据面（Data Plane），供 Agent/服务端消费结构化 JSON。
* [**外部资源（在线表格）**](./assets/README.md): 外部资源的唯一真相源（按类型分表），本地 Markdown 保留为历史参考。
assets/ai-citation/faq.md
+1 -1
View File
@@ -32,4 +32,4 @@
1. `docs/concepts/拼好码.md`
2. `docs/references/强前置条件约束.md`
3. `skills/README.md`
4. `docs/references/通用项目架构模板.md`
4. `docs/references/项目架构模板.md`
docs/references/README.md
+1 -2
View File
@@ -27,8 +27,7 @@
- [常见坑汇总](常见坑汇总.md) - Vibe Coding 常见问题与解决方案
### 项目规范
- [通用项目架构模板](通用项目架构模板.md) - 标准化项目结构
- [数据集导向数据服务模板](数据集导向数据服务模板.md) - 以 dataset/contract/registry/runtime 为核心的数据服务架构模板
- [项目架构模板](项目架构模板.md) - 通用项目结构与 Dataset First 数据服务架构模板
- [代码组织](代码组织.md) - 代码组织原则
- [开发经验](开发经验.md) - 实战经验总结
docs/references/常见坑汇总.md
+1 -1
View File
@@ -290,7 +290,7 @@ git config --global https.proxy http://127.0.0.1:7890
|:---|:---|:---|
| 代码越写越乱 | 没有架构设计 | 先画架构图，再写代码 |
| 改一处坏多处 | 耦合太紧 | 拆分模块，定义清晰接口 |
| 不知道代码放哪 | 目录结构混乱 | 参考 [通用项目架构模板](通用项目架构模板.md) |
| 不知道代码放哪 | 目录结构混乱 | 参考 [项目架构模板](项目架构模板.md) |
| 重复代码太多 | 没有抽象 | 提取公共函数/组件 |
| 状态管理混乱 | 全局状态滥用 | 用状态管理库，单向数据流 |
| 配置散落各处 | 没有统一管理 | 集中到 config 文件或环境变量 |
docs/references/数据集导向数据服务模板.md
-473
View File
@@ -1,473 +0,0 @@
# 数据集导向数据服务模板
> 这份文档定义一套可复用的**数据采集服务通用架构模板**：以后新建数据服务，或把外部源码重构纳入本仓库时，优先按这套模板落地。
## 1) 一句话
- **以 dataset 为边界、以 schema/data contract 为先、以 runtime/registry/config 为共享控制面、以 collect/backfill/repair/validate 为实现单元。**
## 2) 适用范围
### 适合
- 行情事实采集服务
- 另类事件采集服务
- 周期轮询快照服务
- 原子事件流 + 时间桶聚合并存的数据服务
- 需要长期运行、补数、巡检、血缘、质量治理的数据产品服务
### 不适合直接照抄
- 纯 API 网关
- 纯 Web 应用
- 纯交易执行服务
- 一次性脚本工具
- 不产出稳定 dataset 的临时任务
> 判断规则：**如果服务的核心交付物是“稳定数据集”，而不是“页面”或“接口”，就优先用这套模板。**
## 3) 设计目标
- 让 **dataset** 成为开发、调度、部署、运维、血缘、权限、生命周期管理的统一边界
- 让 **schema / contract** 成为稳定真相源，而不是让采集代码反过来定义数据模型
- 让 **控制面**（config / registry / service_entry / runtime）统一收口，避免每个数据集各自长脚本
- 让 **legacy 兼容层** 明确可识别、可退役，而不是长期混在主链里
## 4) 核心原则
### 4.1 Dataset First
- 顶层先按 dataset 划分，而不是先按 `collector/ parser/ writer/ task` 划分
- 一个 dataset 对应一个清晰的数据交付对象
- 代码、存储、血缘、权限都围绕 dataset 收口
### 4.2 Schema / Contract First
- 先定义目标落表、字段语义、主键/幂等键、时间列、分区策略、刷新粒度
- 再写采集、解析、写入、校验、回补逻辑
- 不允许“先把代码跑起来，后面再猜表结构”
### 4.3 Layered Modeling
- 原子层和聚合层分开
- 事件流和时间桶分开
- 运行状态和资源存在性分开
- active / backfill_only / reserved 分开
### 4.4 Shared Control Plane
- `config.py`：统一配置入口
- `registry.py`：统一 dataset 真相矩阵
- `service_entry.py`：统一内部服务入口
- `runtime/*`：统一执行面
- 业务代码不允许自己重新发明第二套控制面
### 4.5 Legacy Is Explicit
- 过渡期允许保留 legacy 壳
- 但 legacy 壳只能做兼容转发
- 新逻辑不得回流 legacy 路径
## 5) 标准目录模板
```text
<service-root>/
├── README.md
├── AGENTS.md
├── pyproject.toml # 单工程时使用；多壳过渡期可暂时保留多个
├── scripts/
│ ├── start.sh # 薄壳：统一转发到 service_entry
│ ├── verify.sh # 服务级快速校验（可选）
│ └── check_legacy_shells.sh # legacy 回流静态门禁（迁移期建议强制）
├── src/<service_name>/
│ ├── __init__.py
│ ├── config.py # 统一配置入口
│ ├── registry.py # dataset 真相矩阵
│ ├── service_entry.py # 统一内部入口：plan/start/stop/status/restart
│ ├── common/ # 公共工具：env、io、time、symbols、shared utils
│ ├── runtime/ # 统一执行层
│ │ ├── stack_runner.py
│ │ ├── process_utils.py
│ │ ├── <group>_runner.py
│ │ └── <group>_worker.py
│ ├── writers/ # 统一写入层（可选，按需要抽）
│ ├── validators/ # 统一校验层（可选，按需要抽）
│ └── datasets/
│ ├── <dataset_a>/
│ │ ├── contract.py
│ │ ├── collect.py
│ │ ├── backfill.py
│ │ ├── repair.py
│ │ ├── writer.py
│ │ ├── validate.py
│ │ └── README.md
│ ├── <dataset_b>/
│ └── _reserved/
│ └── <future_dataset>/
├── tests/
│ ├── unit/
│ ├── integration/
│ └── fixtures/
└── legacy/ or old-shells/ # 可选：迁移期显式归档
```
## 6) dataset 目录的标准职责
每个 dataset 目录不是“一个表一个文件”，而是**一个数据集一个实现单元**。
推荐最小结构：
```text
<dataset>/
├── contract.py
├── collect.py
├── backfill.py
├── repair.py
├── writer.py
├── validate.py
└── README.md
```
### 每个文件干什么
- `contract.py`
- 定义 dataset key、resource_id、物理表、主键/幂等键、时间语义、字段语义
- `collect.py`
- 实时采集 / 轮询采集主逻辑
- `backfill.py`
- 历史补数、文件回填、分页补齐
- `repair.py`
- 缺口修复、异常恢复、局部重算
- `writer.py`
- 统一落库 / 批量写入 / 去重 / 冲突处理
- `validate.py`
- 数据质量检查、行数/字段/时间连续性校验
- `README.md`
- 只说明这个 dataset 的输入、输出、约束与边界
> 如果某个 dataset 没有 `repair` 或 `backfill`，可以不实现，但必须在 registry 里显式标记为不支持，而不是偷偷缺省。
## 7) registry 统一真相矩阵
`registry.py` 至少应定义这些字段：
```text
dataset_key
resource_id
runtime_status # active | backfill_only | reserved | disabled
physical_table
group # 例如 lf / hf / events / snapshots
source_kind # ws / rest / zip / scrape / file / api
collect_supported
backfill_supported
repair_supported
default_enabled
owner
```
推荐额外字段：
```text
symbol_scope
refresh_granularity
retention_policy
partition_key
schema_version
sensitivity
```
### 为什么 registry 必须存在
- 它是 dataset 清单的单一真相源
- 文档、运行、血缘、权限、门禁都应从这里派生
- 没有 registry，就会回到“代码里藏着很多隐式数据集”的旧问题
## 8) 命名规则
### 8.1 dataset 命名
推荐组合维度：
```text
<market>_<instrument>_<topic>_<granularity?>_<layer?>
```
例如：
- `spot_trades`
- `futures_um_trades`
- `futures_um_book_ticker`
- `futures_um_book_depth`
- `candles_1m`
- `futures_metrics_5m`
- `futures_um_metrics_atomic`
### 8.2 命名要求
- 名字必须表达**数据是什么**，不是代码怎么实现
- 尽量包含这些维度：
- 市场类型：`spot` / `futures`
- 合约类型：`um` / `cm`
- 主题：`trades` / `book_ticker` / `book_depth` / `metrics`
- 粒度：`1m` / `5m`
- 层次：`atomic` / aggregate
- `_reserved/` 只用于预留未来命名空间，不用于临时垃圾存放
## 9) 统一控制面模板
### 9.1 service_entry
统一入口只做这几类动作：
- `plan`
- `start`
- `stop`
- `status`
- `restart`
它不直接写业务逻辑，只负责：
- 读取 config
- 读取 registry
- 调 runtime runner
- 输出当前运行真相
### 9.2 runtime
runtime 负责：
- 进程编排
- 模式分组（如 lf / hf / events / snapshots）
- PID / 日志 / 健康状态
- cold-start / restart / stop 行为一致性
业务代码不允许各自实现第二套守护逻辑。
## 10) 数据模型分层建议
推荐至少区分这几类：
```text
atomic # 原子事件/原子明细
snapshot # 单次轮询快照
bucketed # 时间桶聚合结果
derived # 从事实层再派生的结果
reserved # 预留但未启用
```
### 两类典型模型
#### A. 事件流模型
适合：
- trades
- orderbook updates
- tick events
- message stream
特点：
- 高频
- append-only 倾向更强
- 更强调顺序、幂等、去重、水位线
#### B. 时间桶 / 快照模型
适合：
- candles_1m
- metrics_5m
- periodic snapshots
- polling APIs
特点：
- 按窗口/批次刷新
- 更强调覆盖、补齐、时间边界一致性
## 11) 从零新建服务的推荐流程
### Step 1：先定 dataset 清单
明确：
- 服务要产出哪些 dataset
- 每个 dataset 的物理表是什么
- 哪些是 active，哪些是 backfill_only，哪些是 reserved
### Step 2：先写 contract
每个 dataset 先写 `contract.py`，明确：
- 字段
- 主键/幂等键
- 时间列
- 分区策略
- 资源 ID
- schema version
### Step 3：再建 registry / config / service_entry / runtime
先把共享控制面搭起来，再实现具体 dataset。
### Step 4：逐个实现 dataset
每个 dataset 按：
```text
contract -> writer -> collect -> backfill -> validate -> repair
```
的顺序推进。
### Step 5：最后补文档与门禁
至少补：
- README
- AGENTS
- verify / CI
- 资源目录 / 血缘映射 / smoke
## 12) 从外部源码接入时的重构流程
很多外部源码不是按 dataset-first 设计的，通常是：
```text
collector/
parser/
writer/
scripts/
```
接入时不要直接原样搬进来。建议这样重构：
### Step 1：先做盘点，不先搬代码
盘点外部源码：
- 实际产出哪些数据对象
- 每个对象对应什么表/文件/消息
- 哪些逻辑是 collect，哪些是 backfill，哪些是 repair
- 哪些模块只是工具层
### Step 2：反向抽 dataset
把原项目里的功能点反向映射成 dataset：
```text
外部源码里的“多个脚本”
-> 抽象成若干 dataset
-> 为每个 dataset 建 contract / writer / collect / backfill
```
### Step 3：公共能力抽到 common/runtime/writers
例如：
- API client
- auth
- rate limiter
- symbol normalize
- storage client
- retry / backoff
- file downloader
这些不属于单一 dataset，应放共享层。
### Step 4：把 legacy 壳显式隔离
过渡期可以保留旧入口，但必须：
- 只做兼容转发
- 不再承载新逻辑
- 有门禁防止回流
## 13) 最低门禁模板
每个 dataset-first 服务至少要有这些门禁：
### 代码门禁
- `compileall` 覆盖服务新树
- 无语法错误
- 无关键路径未纳入版本控制
### 结构门禁
- 不允许新逻辑回流 legacy 壳
- 不允许第二套 start/status/restart 控制面
- registry 中的 dataset 必须与实际实现一致
### 运行门禁
- `stop -> start -> status -> restart -> status` 可通过
- 日志可证明真实执行源
- PID / log / run metadata 可追踪
### 数据门禁
- 每个 active dataset 至少有 contract + writer + collect/或 backfill
- 血缘 resource_id 与 registry 一致
- 质量检查最少覆盖：空写、重复写、时间边界、幂等
### 文档门禁
- README 更新
- AGENTS 更新
- 资源目录 / 当前真相文档更新
## 14) 反模式
以下情况不应接受：
- 顶层继续按 `collector/ parser/ writer` 组织，dataset 只是注释概念
- 没有 registry，dataset 清单散落在代码里
- 先写采集器，再倒推表结构
- runtime 到处复制，每个 dataset 都有自己一套守护脚本
- legacy 壳长期承担真实执行逻辑
- `_reserved` 被当成垃圾桶
- 同一 dataset 同时存在两套 writer / 两套 contract / 两套运行入口
## 15) 推荐的最小模板文件
如果以后你新建一个数据服务，最少应先建出这些文件：
```text
<service-root>/
├── README.md
├── AGENTS.md
├── scripts/start.sh
└── src/<service_name>/
├── config.py
├── registry.py
├── service_entry.py
├── runtime/
│ ├── stack_runner.py
│ └── process_utils.py
└── datasets/
├── <dataset_a>/
│ ├── contract.py
│ ├── collect.py
│ ├── writer.py
│ └── README.md
└── _reserved/
```
## 16) 仓库内参考实现
当前仓库里，最接近这套模板的落地参考是：
- `core/market/binance/src/binance/`
- `core/market/binance/src/binance/datasets/*`
- `core/market/binance/src/binance/registry.py`
- `core/market/binance/src/binance/service_entry.py`
- `core/market/binance/src/binance/runtime/*`
> 说明：这份模板不是说“以后每个服务都必须和 Binance 长得一模一样”，而是说：**以后凡是新的数据采集服务，都优先按这个方法组织，再根据数据源特性做局部裁剪。**
## 17) 一句话结论
- **这套模板可以作为你后续“数据采集服务”的通用源码架构模板。**
- 它的核心不是目录长什么样，而是：**先定义 dataset 与 contract，再围绕 dataset 实现 collect/backfill/repair/write/validate，并把 config/registry/runtime/service_entry 收敛成统一控制面。**
docs/references/通用项目架构模板.md
-695
View File
@@ -1,695 +0,0 @@
# 通用项目架构模板
## 1️⃣ Python Web/API 项目标准结构
```
项目名称/
├── 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的会话恢复指令^_^
│
├── docs/ # 文档目录
│ ├── api.md # API文档
│ ├── development.md # 开发指南
│ └── architecture.md # 架构说明
│
├── scripts/ # 脚本工具
│ ├── deploy.sh # 部署脚本
│ ├── backup.sh # 备份脚本
│ └── init_db.sh # 数据库初始化
│
├── tests/ # 测试代码
│ ├── __init__.py
│ ├── conftest.py # pytest配置
│ ├── unit/ # 单元测试
│ ├── integration/ # 集成测试
│ └── test_config.py # 配置测试
│
├── src/ # 源代码（推荐方式）
│ ├── __init__.py
│ ├── main.py # 程序入口
│ ├── app.py # Flask/FastAPI应用
│ ├── config.py # 配置管理
│ │
│ ├── core/ # 核心业务逻辑
│ │ ├── __init__.py
│ │ ├── models/ # 数据模型
│ │ ├── services/ # 业务服务
│ │ └── utils/ # 工具函数
│ │
│ ├── api/ # API接口层
│ │ ├── __init__.py
│ │ ├── v1/ # 版本1
│ │ └── dependencies.py
│ │
│ ├── data/ # 数据处理
│ │ ├── __init__.py
│ │ ├── repository/ # 数据访问层
│ │ └── migrations/ # 数据库迁移
│ │
│ └── external/ # 外部服务
│ ├── __init__.py
│ ├── clients/ # API客户端
│ └── integrations/ # 集成服务
│
├── logs/ # 日志目录（不提交到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/
│
├── assets/ # 资产中心
│ ├── common/ # 公共模块
│ │ ├── utils/
│ │ └── models/
│ ├── repo/ # 外部仓库中心（不可修改，只调用）
│ └── 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，记录版本变更
---
在**编程 / 软件开发**里，**项目架构（Project Architecture / Software Architecture）**指的是：
> **一个项目在“整体层面”是如何被拆分、组织、通信和演进的设计方案**
> ——它决定了代码怎么分层、模块怎么分工、数据怎么流动、系统如何扩展和维护。
---
## 一句话理解
**项目架构 = 不写具体业务代码之前，就先决定“代码怎么放、模块怎么连、职责怎么分”。**
---
## 一、项目架构主要解决什么问题？
项目架构不是“写代码的技巧”，而是解决这些**更高层问题**：
* 📦 代码怎么组织才不乱？
* 🔁 模块之间怎么通信？
* 🧱 哪些地方可以独立修改而不影响全局？
* 🚀 项目以后怎么扩展？
* 🧪 如何方便测试、调试、部署？
* 👥 多人协作如何不互相踩代码？
---
## 二、项目架构一般包含哪些内容？
### 1️⃣ 目录结构（最直观）
```text
project/
├── src/
│ ├── main/
│ ├── services/
│ ├── models/
│ ├── utils/
│ └── config/
├── tests/
├── docs/
└── README.md
```
👉 决定 **“不同类型代码放哪里”**
---
### 2️⃣ 分层设计（核心）
最常见的是 **分层架构（Layered Architecture）**：
```text
表示层（UI / API）
↓
业务逻辑层（Service）
↓
数据访问层（DAO / Repository）
↓
数据库 / 外部系统
```
**规则：**
* 上层可以调用下层
* 下层不能反过来依赖上层
---
### 3️⃣ 模块划分（职责边界）
比如一个交易系统：
```text
- market_data # 行情
- strategy # 策略
- risk # 风控
- order # 下单
- account # 账户
```
👉 每个模块：
* 只做一类事情
* 尽量低耦合、高内聚
---
### 4️⃣ 数据与控制流
* 数据从哪里来？
* 谁负责处理？
* 谁负责存储？
* 谁负责对外输出？
例如：
```text
WebSocket → 数据清洗 → 指标计算 → AI评分 → SQLite → API → 前端
```
---
### 5️⃣ 技术选型（架构的一部分）
* 编程语言（Python / Java / Go）
* 框架（FastAPI / Spring / Django）
* 通信方式（HTTP / WebSocket / MQ）
* 存储（SQLite / Redis / PostgreSQL）
* 部署（本地 / Docker / 云）
---
## 三、常见项目架构类型（入门必懂）
### 1️⃣ 单体架构（Monolith）
```text
一个项目，一个进程
```
**适合：**
* 个人项目
* 原型
* 小系统
**优点：**
* 简单
* 好调试
**缺点：**
* 后期难扩展
---
### 2️⃣ 分层架构（最常见）
```text
Controller → Service → Repository
```
**适合：**
* Web 后端
* 业务系统
---
### 3️⃣ 模块化架构
```text
core + plugins
```
**适合：**
* 可插拔系统
* 策略 / 指标系统
👉 **你做量化、AI分析，非常适合这个**
---
### 4️⃣ 微服务架构（进阶）
```text
每个服务一个独立进程 + API 通信
```
**适合：**
* 大团队
* 高并发
* 长期演进
❌ **新手不建议一开始用**
---
## 四、用一个“真实例子”理解（贴近你现在做的）
假设你做 **币安永续 AI 分析系统**：
```text
backend/
├── data/
│ └── binance_ws.py # 行情订阅
├── indicators/
│ └── vpvr.py
├── strategy/
│ └── signal_score.py
├── storage/
│ └── sqlite_writer.py
├── api/
│ └── http_server.py
└── main.py
```
这就是**项目架构设计**：
* 每个文件夹只负责一件事
* 可替换、可测试
* 后面想接 Telegram Bot / Web 前端都不用重写核心
---
## 五、初学者常见误区 ⚠️
❌ 一开始就搞微服务
❌ 所有代码写在一个文件
❌ 架构追求“高级感”，而不是“可维护”
❌ 没想清楚数据流就开始写
---
## 六、学习路线建议（很重要）
你现在学 CS，很推荐这个顺序：
1. **先写能跑的项目（不完美）**
2. **代码开始乱 → 才学架构**
3. 学会：
* 模块拆分
* 分层
* 依赖方向
4. 再学：
* 设计模式
* 微服务 / 消息队列
---
**版本**: 1.0
**更新日期**: 2025-11-24
**维护**: CLAUDE，CODEX，KIMI
docs/references/项目架构模板.md
+612
View File
@@ -0,0 +1,612 @@
# 项目架构模板
> 本文档合并原 `通用项目架构模板.md` 与 `数据集导向数据服务模板.md`，用于新项目初始化、旧项目重组和数据采集服务架构设计。
## 1. 使用原则
项目架构不是先追求“高级感”，而是先回答这些问题：
- 代码放哪里。
- 模块怎么分工。
- 数据怎么流动。
- 依赖怎么隔离。
- 如何测试、部署、回滚和维护。
默认顺序：
1. 先确定交付物：页面、API、数据集、CLI、服务还是组合系统。
2. 再确定边界：模块边界、数据边界、运行边界、外部依赖边界。
3. 再确定目录：目录只服务于边界，不反过来制造复杂度。
4. 最后补门禁：测试、lint、schema、配置示例、README、AGENTS。
## 2. 快速选型
| 项目类型 | 推荐模板 |
| --- | --- |
| Web API / 后端服务 | Python Web/API 项目结构 |
| 数据分析 / 量化 / 机器学习 | 数据科学项目结构 |
| 多服务 / 大型系统 | Monorepo 项目结构 |
| 前后端一体项目 | Full-Stack Web 应用结构 |
| 长期运行的数据采集服务 | Dataset First 数据服务结构 |
## 3. Python Web/API 项目结构
适合 Flask、FastAPI、RESTful API、Web 后端服务。
```text
project/
├── README.md
├── AGENTS.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
├── .env.example
├── .gitignore
├── docs/
│ ├── api.md
│ ├── architecture.md
│ └── development.md
├── scripts/
│ ├── deploy.sh
│ ├── backup.sh
│ └── init_db.sh
├── tests/
│ ├── conftest.py
│ ├── unit/
│ └── integration/
├── src/
│ ├── main.py
│ ├── app.py
│ ├── config.py
│ ├── api/
│ │ ├── v1/
│ │ └── dependencies.py
│ ├── core/
│ │ ├── models/
│ │ ├── services/
│ │ └── utils/
│ ├── data/
│ │ ├── repository/
│ │ └── migrations/
│ └── external/
│ ├── clients/
│ └── integrations/
├── data/ # 不提交，或只提交 README/.gitkeep
└── logs/ # 不提交，或只提交 README/.gitkeep
```
关键边界：
- `api/` 只处理协议、路由、参数校验和响应格式。
- `core/services/` 承载业务逻辑。
- `data/repository/` 隔离数据库访问。
- `external/` 隔离第三方 API、SDK 和平台依赖。
- `.env` 不提交，必须提供 `.env.example`。
## 4. 数据科学 / 量化项目结构
适合量化交易、机器学习、数据分析、AI 研究。
```text
project/
├── README.md
├── AGENTS.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
├── .env.example
├── .gitignore
├── docs/
│ ├── notebooks/
│ └── reports/
├── notebooks/
│ ├── 01_data_exploration.ipynb
│ ├── 02_feature_engineering.ipynb
│ └── 03_model_training.ipynb
├── scripts/
│ ├── collect_data.py
│ ├── train_model.py
│ ├── backtest.py
│ └── deploy_model.py
├── tests/
│ ├── test_data/
│ └── test_models/
├── configs/
│ ├── model.yaml
│ ├── database.yaml
│ └── trading.yaml
├── src/
│ ├── data/
│ │ ├── collectors/
│ │ ├── processors/
│ │ ├── features/
│ │ └── loaders.py
│ ├── models/
│ │ ├── strategies/
│ │ ├── backtest/
│ │ └── risk/
│ ├── core/
│ │ ├── config.py
│ │ ├── signals.py
│ │ └── portfolio.py
│ └── utils/
│ ├── logging.py
│ ├── database.py
│ └── api_client.py
├── data/ # 不提交大数据文件
├── models/ # 不提交大模型/大 checkpoint
└── logs/
```
关键边界：
- Notebook 用于探索，不作为长期生产入口。
- `scripts/` 是薄入口，核心逻辑应在 `src/`。
- 数据、模型、日志默认不进 Git，除非是小型示例或 fixture。
- 回测、训练、采集、部署脚本必须能复现关键参数。
## 5. Monorepo 项目结构
适合多服务架构、大型项目、团队协作。
```text
project-monorepo/
├── README.md
├── AGENTS.md
├── LICENSE
├── .gitignore
├── .gitmodules
├── docker-compose.yml
├── docs/
│ ├── architecture.md
│ └── deployment.md
├── scripts/
│ ├── build_all.sh
│ ├── test_all.sh
│ └── deploy.sh
├── services/
│ ├── user-service/
│ │ ├── Dockerfile
│ │ ├── pyproject.toml
│ │ ├── src/
│ │ └── tests/
│ ├── trading-service/
│ └── data-service/
├── packages/
│ ├── common/
│ └── contracts/
├── infrastructure/
│ ├── terraform/
│ ├── kubernetes/
│ └── nginx/
└── monitoring/
├── prometheus/
├── grafana/
└── alertmanager/
```
关键边界：
- 每个 `services/*` 应能独立构建、测试和部署。
- 公共能力放 `packages/`，不要让服务之间互相直接 import 私有实现。
- `contracts/` 存 API schema、事件 schema、数据契约，作为跨服务真相源。
- 顶层脚本只做编排，不隐藏服务内部逻辑。
## 6. Full-Stack Web 应用结构
适合 SPA、前后端分离项目、轻量产品原型。
```text
project/
├── README.md
├── AGENTS.md
├── LICENSE
├── .gitignore
├── docker-compose.yml
├── docs/
│ ├── architecture.md
│ └── deployment.md
├── frontend/
│ ├── package.json
│ ├── vite.config.js
│ ├── public/
│ └── src/
│ ├── components/
│ ├── pages/
│ ├── store/
│ └── utils/
└── backend/
├── Dockerfile
├── pyproject.toml
├── src/
│ ├── api/
│ ├── core/
│ └── models/
└── tests/
```
关键边界：
- 前端状态管理不要直接绑定后端数据库结构。
- 后端 API contract 应有 schema 或类型定义。
- 前后端共享类型时，优先从 OpenAPI、JSON Schema 或生成工具派生。
## 7. Dataset First 数据服务结构
适合长期运行、补数、巡检、血缘、质量治理的数据产品服务。
判断规则：
> 如果服务的核心交付物是“稳定数据集”，而不是页面、接口或一次性脚本，就优先使用 Dataset First。
### 一句话
以 dataset 为边界，以 schema/data contract 为先，以 runtime/registry/config 为共享控制面，以 collect/backfill/repair/validate 为实现单元。
### 适合
- 行情事实采集服务。
- 另类事件采集服务。
- 周期轮询快照服务。
- 原子事件流 + 时间桶聚合并存的数据服务。
- 需要长期运行、补数、巡检、血缘、质量治理的数据服务。
### 不适合直接照抄
- 纯 API 网关。
- 纯 Web 应用。
- 纯交易执行服务。
- 一次性脚本工具。
- 不产出稳定 dataset 的临时任务。
### 核心原则
1. Dataset First：顶层先按 dataset 划分，而不是按 `collector/parser/writer/task` 划分。
2. Contract First：先定义目标落表、字段语义、主键、时间列、分区策略和刷新粒度。
3. Layered Modeling：原子层、聚合层、事件流、时间桶、运行状态分开建模。
4. Shared Control Plane：`config.py`、`registry.py`、`service_entry.py`、`runtime/*` 统一收口。
5. Legacy Is Explicit：迁移期 legacy 壳只能兼容转发，新逻辑不得回流旧路径。
### 标准目录
```text
service-root/
├── README.md
├── AGENTS.md
├── pyproject.toml
├── scripts/
│ ├── start.sh
│ ├── verify.sh
│ └── check_legacy_shells.sh
├── src/<service_name>/
│ ├── __init__.py
│ ├── config.py
│ ├── registry.py
│ ├── service_entry.py
│ ├── common/
│ ├── runtime/
│ │ ├── stack_runner.py
│ │ ├── process_utils.py
│ │ ├── <group>_runner.py
│ │ └── <group>_worker.py
│ ├── writers/
│ ├── validators/
│ └── datasets/
│ ├── <dataset_a>/
│ │ ├── contract.py
│ │ ├── collect.py
│ │ ├── backfill.py
│ │ ├── repair.py
│ │ ├── writer.py
│ │ ├── validate.py
│ │ └── README.md
│ ├── <dataset_b>/
│ └── _reserved/
├── tests/
│ ├── unit/
│ ├── integration/
│ └── fixtures/
└── legacy/ or old-shells/
```
### Dataset 最小结构
```text
<dataset>/
├── contract.py
├── collect.py
├── backfill.py
├── repair.py
├── writer.py
├── validate.py
└── README.md
```
职责边界：
- `contract.py`：定义 dataset key、resource_id、物理表、主键、幂等键、时间语义、字段语义。
- `collect.py`：实时采集或轮询采集主逻辑。
- `backfill.py`：历史补数、文件回填、分页补齐。
- `repair.py`：缺口修复、异常恢复、局部重算。
- `writer.py`：统一落库、批量写入、去重、冲突处理。
- `validate.py`：数据质量检查、行数、字段、时间连续性校验。
- `README.md`：说明该 dataset 的输入、输出、约束与边界。
如果某个 dataset 没有 `repair` 或 `backfill`，必须在 registry 中显式标记为不支持。
### Registry 真相矩阵
`registry.py` 至少应定义：
```text
dataset_key
resource_id
runtime_status # active | backfill_only | reserved | disabled
physical_table
group # lf | hf | events | snapshots
source_kind # ws | rest | zip | scrape | file | api
collect_supported
backfill_supported
repair_supported
default_enabled
owner
```
推荐额外字段：
```text
symbol_scope
refresh_granularity
retention_policy
partition_key
schema_version
sensitivity
```
Registry 的作用：
- 它是 dataset 清单的单一真相源。
- 文档、运行、血缘、权限、门禁都应从 registry 派生。
- 没有 registry，就会回到“数据集藏在脚本里”的旧问题。
### Dataset 命名
推荐格式：
```text
<market>_<instrument>_<topic>_<granularity?>_<layer?>
```
示例：
- `spot_trades`
- `futures_um_trades`
- `futures_um_book_ticker`
- `futures_um_book_depth`
- `candles_1m`
- `futures_metrics_5m`
- `futures_um_metrics_atomic`
命名要求：
- 名字必须表达数据是什么，而不是代码怎么实现。
- `_reserved/` 只用于预留未来命名空间，不用于临时文件。
- 事件流、快照、时间桶、派生结果要在命名或 contract 中显式表达。
### Service Entry 与 Runtime
`service_entry.py` 统一入口只做：
- `plan`
- `start`
- `stop`
- `status`
- `restart`
它不直接写业务逻辑，只负责读取 config、读取 registry、调用 runtime runner、输出运行真相。
`runtime/` 负责：
- 进程编排。
- 模式分组。
- PID、日志、健康状态。
- cold-start、restart、stop 行为一致性。
业务代码不允许各自实现第二套守护逻辑。
### 数据模型分层
推荐区分：
```text
atomic # 原子事件/原子明细
snapshot # 单次轮询快照
bucketed # 时间桶聚合结果
derived # 从事实层再派生的结果
reserved # 预留但未启用
```
事件流模型适合 trades、orderbook updates、tick events、message stream，重点是顺序、幂等、去重、水位线。
时间桶 / 快照模型适合 candles、metrics、periodic snapshots、polling APIs，重点是覆盖、补齐、时间边界一致性。
### 新建数据服务流程
1. 先定 dataset 清单：哪些 active、哪些 backfill_only、哪些 reserved。
2. 先写 contract：字段、主键、时间列、分区策略、资源 ID、schema version。
3. 再建 registry、config、service_entry、runtime。
4. 逐个实现 dataset：`contract -> writer -> collect -> backfill -> validate -> repair`。
5. 最后补 README、AGENTS、verify/CI、资源目录、血缘映射、smoke。
### 外部源码接入流程
1. 先盘点外部源码实际产出的数据对象，不先搬代码。
2. 把原项目脚本反向映射为 dataset。
3. 将 API client、auth、rate limiter、storage client、retry/backoff 抽到 `common/`、`runtime/` 或 `writers/`。
4. 将 legacy 壳显式隔离，只允许兼容转发，不允许承载新逻辑。
## 8. 架构设计原则
### 关注点分离
```text
API -> Service -> Repository -> Database / External System
```
上层可以调用下层，下层不能反向依赖上层。
### 可测试性
- 每个模块可独立测试。
- 外部依赖可 mock。
- 核心业务逻辑不依赖 CLI、HTTP、数据库连接对象。
### 可配置性
```text
环境变量 > 配置文件 > 默认值
```
配置与代码分离，敏感配置不得提交。
### 可维护性
- 文件名表达职责。
- 目录边界表达模块边界。
- 业务逻辑、平台适配、第三方依赖隔离。
### 版本控制友好
- `data/`、`logs/`、`models/` 默认加入 `.gitignore`。
- 大文件不进 Git，必要时使用对象存储、Release、DVC 或外部数据源。
- 提交源代码、配置示例、文档、测试和小型 fixture。
## 9. 最低门禁
### 代码门禁
- 语法检查通过。
- 单元测试覆盖核心业务。
- lint/format 有明确命令。
- 关键路径纳入版本控制。
### 结构门禁
- 不允许临时脚本成为长期入口。
- 不允许同一职责存在多套实现入口。
- 不允许外部 SDK 类型污染核心业务模型。
- 数据服务不允许新逻辑回流 legacy 壳。
### 运行门禁
- 服务能按 README 启动。
- `stop -> start -> status -> restart -> status` 可验证。
- 日志能证明真实执行源。
- PID、log、run metadata 可追踪。
### 数据门禁
- 每个 active dataset 至少有 contract + writer + collect 或 backfill。
- resource_id 与 registry 一致。
- 质量检查至少覆盖空写、重复写、时间边界、幂等。
### 文档门禁
- README 说明项目定位、安装、启动、测试和目录结构。
- AGENTS 说明 AI Agent 修改边界、验证命令和禁止事项。
- `.env.example` 说明必要配置。
- 架构变化同步更新文档。
## 10. `.gitignore` 推荐模板
```gitignore
# Python
__pycache__/
*.py[cod]
*.egg-info/
dist/
build/
# Environment
.env
.venv/
env/
venv/
# IDE
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store
# Data
data/
*.csv
*.db
*.sqlite
*.duckdb
# Logs
logs/
*.log
# Models
models/
*.h5
*.pkl
*.pt
*.onnx
# Temporary
tmp/
temp/
*.tmp
```
## 11. 技术选型参考
| 场景 | 推荐技术栈 |
| --- | --- |
| 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 |
## 12. 新项目检查清单
- [ ] 创建 `README.md`，说明项目目标、安装、启动、测试。
- [ ] 创建 `AGENTS.md`，说明 AI Agent 操作边界与必须验证命令。
- [ ] 创建 `LICENSE`。
- [ ] 创建 `.gitignore`。
- [ ] 创建 `.env.example`。
- [ ] 建立虚拟环境或包管理配置。
- [ ] 明确目录结构。
- [ ] 明确配置入口。
- [ ] 设置 lint/format/test 命令。
- [ ] 编写第一个测试用例。
- [ ] 记录架构决策和后续 TODO。
## 13. 常见反模式
- 一开始就做微服务。
- 所有代码写在一个文件。
- 架构追求高级感，而不是可维护。
- 没想清楚数据流就开始写。
- 目录按技术名堆砌，但没有业务边界。
- 业务逻辑直接依赖第三方 SDK。
- 临时脚本长期成为生产入口。
- 数据服务没有 registry，dataset 清单散落在脚本里。
- 先写采集器，再倒推表结构。
- 每个 dataset 各自实现 start/status/restart。
## 14. 一句话结论
项目架构的目标不是把目录做复杂，而是让职责、数据流、依赖和验证路径清楚。普通项目先选通用结构；稳定数据服务优先采用 Dataset First，用 contract、registry、runtime 和质量门禁固定长期演进边界。
metadata/redirects.yml
+4
View File
@@ -9,6 +9,10 @@ redirects:
to: docs/playbooks/
- from: docs/getting-started/Codex-CLI配置.md
to: docs/getting-started/CLI配置.md
- from: docs/references/通用项目架构模板.md
to: docs/references/项目架构模板.md
- from: docs/references/数据集导向数据服务模板.md
to: docs/references/项目架构模板.md
- from: skills/
to: skills/
- from: prompts/