diff --git a/README.md b/README.md index 5ea50a7..93afb0b 100644 --- a/README.md +++ b/README.md @@ -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 保留为历史参考。 diff --git a/assets/ai-citation/faq.md b/assets/ai-citation/faq.md index 4eae8b6..f3b3768 100644 --- a/assets/ai-citation/faq.md +++ b/assets/ai-citation/faq.md @@ -32,4 +32,4 @@ 1. `docs/concepts/拼好码.md` 2. `docs/references/强前置条件约束.md` 3. `skills/README.md` -4. `docs/references/通用项目架构模板.md` +4. `docs/references/项目架构模板.md` diff --git a/docs/references/README.md b/docs/references/README.md index eac6efb..f86ac7e 100644 --- a/docs/references/README.md +++ b/docs/references/README.md @@ -27,8 +27,7 @@ - [常见坑汇总](常见坑汇总.md) - Vibe Coding 常见问题与解决方案 ### 项目规范 -- [通用项目架构模板](通用项目架构模板.md) - 标准化项目结构 -- [数据集导向数据服务模板](数据集导向数据服务模板.md) - 以 dataset/contract/registry/runtime 为核心的数据服务架构模板 +- [项目架构模板](项目架构模板.md) - 通用项目结构与 Dataset First 数据服务架构模板 - [代码组织](代码组织.md) - 代码组织原则 - [开发经验](开发经验.md) - 实战经验总结 diff --git a/docs/references/常见坑汇总.md b/docs/references/常见坑汇总.md index 96867df..9c7a9f0 100644 --- a/docs/references/常见坑汇总.md +++ b/docs/references/常见坑汇总.md @@ -290,7 +290,7 @@ git config --global https.proxy http://127.0.0.1:7890 |:---|:---|:---| | 代码越写越乱 | 没有架构设计 | 先画架构图，再写代码 | | 改一处坏多处 | 耦合太紧 | 拆分模块，定义清晰接口 | -| 不知道代码放哪 | 目录结构混乱 | 参考 [通用项目架构模板](通用项目架构模板.md) | +| 不知道代码放哪 | 目录结构混乱 | 参考 [项目架构模板](项目架构模板.md) | | 重复代码太多 | 没有抽象 | 提取公共函数/组件 | | 状态管理混乱 | 全局状态滥用 | 用状态管理库，单向数据流 | | 配置散落各处 | 没有统一管理 | 集中到 config 文件或环境变量 | diff --git a/docs/references/数据集导向数据服务模板.md b/docs/references/数据集导向数据服务模板.md deleted file mode 100644 index 71dc0f1..0000000 --- a/docs/references/数据集导向数据服务模板.md +++ /dev/null @@ -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 -/ -├── README.md -├── AGENTS.md -├── pyproject.toml # 单工程时使用；多壳过渡期可暂时保留多个 -├── scripts/ -│ ├── start.sh # 薄壳：统一转发到 service_entry -│ ├── verify.sh # 服务级快速校验（可选） -│ └── check_legacy_shells.sh # legacy 回流静态门禁（迁移期建议强制） -├── src// -│ ├── __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 -│ │ ├── _runner.py -│ │ └── _worker.py -│ ├── writers/ # 统一写入层（可选，按需要抽） -│ ├── validators/ # 统一校验层（可选，按需要抽） -│ └── datasets/ -│ ├── / -│ │ ├── contract.py -│ │ ├── collect.py -│ │ ├── backfill.py -│ │ ├── repair.py -│ │ ├── writer.py -│ │ ├── validate.py -│ │ └── README.md -│ ├── / -│ └── _reserved/ -│ └── / -├── tests/ -│ ├── unit/ -│ ├── integration/ -│ └── fixtures/ -└── legacy/ or old-shells/ # 可选：迁移期显式归档 -``` - -## 6) dataset 目录的标准职责 - -每个 dataset 目录不是“一个表一个文件”，而是**一个数据集一个实现单元**。 - -推荐最小结构： - -```text -/ -├── 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 -____ -``` - -例如： - -- `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 -/ -├── README.md -├── AGENTS.md -├── scripts/start.sh -└── src// - ├── config.py - ├── registry.py - ├── service_entry.py - ├── runtime/ - │ ├── stack_runner.py - │ └── process_utils.py - └── datasets/ - ├── / - │ ├── 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 收敛成统一控制面。** diff --git a/docs/references/通用项目架构模板.md b/docs/references/通用项目架构模板.md deleted file mode 100644 index 168c61e..0000000 --- a/docs/references/通用项目架构模板.md +++ /dev/null @@ -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 diff --git a/docs/references/项目架构模板.md b/docs/references/项目架构模板.md new file mode 100644 index 0000000..6eef3ce --- /dev/null +++ b/docs/references/项目架构模板.md @@ -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// +│ ├── __init__.py +│ ├── config.py +│ ├── registry.py +│ ├── service_entry.py +│ ├── common/ +│ ├── runtime/ +│ │ ├── stack_runner.py +│ │ ├── process_utils.py +│ │ ├── _runner.py +│ │ └── _worker.py +│ ├── writers/ +│ ├── validators/ +│ └── datasets/ +│ ├── / +│ │ ├── contract.py +│ │ ├── collect.py +│ │ ├── backfill.py +│ │ ├── repair.py +│ │ ├── writer.py +│ │ ├── validate.py +│ │ └── README.md +│ ├── / +│ └── _reserved/ +├── tests/ +│ ├── unit/ +│ ├── integration/ +│ └── fixtures/ +└── legacy/ or old-shells/ +``` + +### Dataset 最小结构 + +```text +/ +├── 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 +____ +``` + +示例： + +- `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 和质量门禁固定长期演进边界。 diff --git a/metadata/redirects.yml b/metadata/redirects.yml index f9a96f3..03d3915 100644 --- a/metadata/redirects.yml +++ b/metadata/redirects.yml @@ -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/