> ⚠️ **本 ADR 是模板示例**
>
> 这是 AppGenesisForge 自身的技术栈选型记录，**仅供参考**。复用本模板到新项目时，请二选一：
> 1. **重写**：让 `tech-lead` 根据你项目的实际栈重写本文件的"决策"表，同步更新 `CLAUDE.md` "Tech Stack" 节
> 2. **删除**：直接删本文件，首个 feature 启动时 `tech-lead` 会按团队约束自动补 ADR-000

# ADR-000: 系统架构基线

- 状态：Accepted
- 日期：2026-04-27
- 决策者：tech-lead
- 影响范围：项目全栈

## 上下文

AppGenesisForge 是一个 Web + AI Agent 混合系统：前端是面向最终用户的 Web 应用，后端在常规业务接口之外承载 LLM Agent 流程。仓库此前仅含 `.claude/` 团队模板与 `docs/` 规范，尚无应用代码。在第一份 PRD 进入开发前，需要先固化技术栈基线，让 frontend-dev / backend-dev / ml-engineer 在首个 feature 启动时按统一约束搭骨架，避免后续返工。

## 决策

| 类别 | 选型 | 理由 |
|---|---|---|
| 项目形态 | Web + AI Agent 混合 | 前端交付用户界面，后端同时承载 REST 业务与 LLM Agent 编排，单仓 monorepo 管理 |
| 前端框架 | React + Vite | React 生态成熟、团队熟悉；Vite 冷启动快、HMR 体验优于 webpack/CRA |
| 包管理 | pnpm | 磁盘占用低、依赖隔离严格，适合 monorepo 后续拆 workspace |
| 前端路由/状态 | React Router + Zustand | React Router 是事实标准；Zustand 比 Redux 轻量、API 简洁，足以覆盖中等规模应用，避免过度设计 |
| 前端样式 | Tailwind CSS + shadcn/ui | 原子类提速、shadcn/ui 提供可拷贝可定制的组件源码，避免被组件库版本锁死 |
| 前端测试 | Vitest + React Testing Library | Vitest 与 Vite 共享配置，启动快；RTL 强调按用户行为测试，组件测试质量高于 enzyme |
| 后端框架 | FastAPI（Python） | 原生 async、Pydantic 校验、自动 OpenAPI 文档，适合既有 REST 又有 LLM 流式响应的混合场景 |
| 数据库 | PostgreSQL | 关系完整性 + JSONB 兼顾结构化与半结构化数据（Agent 对话/上下文存储友好） |
| ORM/迁移 | SQLAlchemy 2.x + Alembic | 2.x 类型注解友好、原生 async；Alembic 是 SQLAlchemy 官方迁移工具，闭环 |
| AI SDK | DeepSeek / Doubao / Qwen / MiniMax（多厂商） | 团队重点使用国内厂商模型，接入方式（原生 SDK / OpenAI 兼容端点）待后续 ADR 细化 |
| Agent 编排位置 | 后端内嵌 `backend/app/agents/` 模块 | 首版无独立 Agent 服务的复杂度收益；与 REST 共享数据库连接、鉴权、日志；如未来出现长任务/水平扩展需求再单独拆服务（届时另开 ADR） |
| 后端测试 | pytest + pytest-asyncio | Python 测试事实标准；pytest-asyncio 处理 FastAPI 异步路由与 Agent 协程 |
| 后端代码风格 | Ruff + Black | Ruff 整合 flake8/isort 等，速度快；Black 统一格式化；二者组合是当前 Python 主流 |
| 前端代码风格 | ESLint + Prettier | JS/TS 生态事实标准 |
| 本地编排 | docker-compose（仅 Postgres） | 数据库容器化保证版本一致；前后端本地起服务以保留 HMR/调试器，避免 Docker volume 性能损耗 |
| 生产部署 | Docker（细节待后续 ADR） | 容器化方向已定，k8s vs PaaS 等留给后续 ADR |

## 项目目录

```
backend/                  # FastAPI 应用
  app/
    api/                  # REST 路由
    agents/               # LLM Agent 流程
    models/               # SQLAlchemy 模型
    services/             # 业务逻辑（路由与模型之间）
  alembic/                # 数据库迁移
  tests/
frontend/                 # React + Vite 应用
  src/
    components/           # 通用 UI 组件
    pages/                # 路由级页面
    api/                  # 后端 API client
  tests/
docker-compose.yml        # 仅编排 Postgres
docs/
  adr/                    # 架构决策记录
  design/                 # uiux-designer 产出
```

具体落地由 frontend-dev / backend-dev 在首个 feature 启动时按 PRD 创建。

## 本地开发流程

1. `docker-compose up -d postgres`：起 Postgres 容器，端口暴露给宿主机
2. `cd backend && uvicorn app.main:app --reload`：本地 Python 虚拟环境内运行 FastAPI（含 Agent 流程）
3. `cd frontend && pnpm dev`：本地 Vite dev server，代理后端 API

后端连接串与前端 API base URL 通过各自 `.env.local` 注入（首次实现时由 backend-dev / frontend-dev 在 README 内补充模板，不在本 ADR 规定字段）。

## 本 ADR 不覆盖的决策

- 生产部署形态（k8s vs 云厂商 PaaS vs 自建）
- 可观测性（结构化日志、Tracing、指标采集）
- CI/CD pipeline（lint/test/build/deploy 流水线编排）
- 鉴权与会话方案（JWT/Session/OAuth）
- LLM 调用层的缓存、限速、降级策略
- 推理服务监控告警阈值与成本上限

后续按需以 ADR-001、ADR-002…逐项补齐。

## 后续工作

- frontend-dev / backend-dev 在首个 feature 启动时，参照本 ADR 搭建 `frontend/`、`backend/`、`docker-compose.yml` 骨架
- ml-engineer 在引入 LLM 推理流程前，发起 ADR 补齐推理服务选型 / 监控 / 降级三项
- product-lead 在 PRD 中引用本 ADR 编号（ADR-000）作为技术约束起点

## 版本与查证

> 本 ADR 创建于 2026-04-27，早于 tech-lead 行事原则 #3「先查最新版再决策」。本附录是对该规则的回填，对核心栈版本做正式查证，剩余条目在首个 feature 启动时由对应执行层按"查证 → 写入 lockfile / pyproject.toml → 反向更新本附录"流程补齐。新增技术或大版本升级时，必须按 tech-lead.md ADR 模板的「版本与查证」段单独形成新 ADR，不在本表追加。

**查证基线日期**：2026-04-28（首批核心栈），后续条目由首次落地者补充查证日期。

| 选型 | 选定版本 | 最新稳定版 | 与最新版差距 | 维护状态 | 信息来源（含原文摘录） |
|---|---|---|---|---|---|
| React | 19.2.x（pin `^19.2.5`） | 19.2.5（2026-04-08） | 无 | Active | [react.dev/versions](https://react.dev/versions)、[npmjs.com/package/react](https://www.npmjs.com/package/react?activeTab=versions) — "latest stable: React 19.2.5, released 2026-04-08" |
| Vite | 8.0.x（pin `^8.0.8`，当前解析至 8.0.10） | 8.0.10（2026-03） | 无 | Active（Rolldown 统一打包，2026-03-12 GA） | [vite.dev/blog/announcing-vite8](https://vite.dev/blog/announcing-vite8)、[github.com/vitejs/vite/releases](https://github.com/vitejs/vite/releases) — "Vite 8 stable: 2026-03-12, ships Rolldown as unified bundler" |
| FastAPI | 0.136.x（pin `>=0.136.1,<0.137.0`，理由见下） | 0.136.1（2026-04-23） | 无 | Active；仍在 0.x semver，建议窄范围 pin | [pypi.org/project/fastapi](https://pypi.org/project/fastapi/)、[github.com/fastapi/fastapi/releases](https://github.com/fastapi/fastapi/releases) — "0.136.1 released 2026-04-23, requires Python ≥3.10" |
| Tailwind CSS | v4（latest） | v4（latest） | 无 | Active | [ui.shadcn.com/docs/tailwind-v4](https://ui.shadcn.com/docs/tailwind-v4) — "All shadcn/ui components updated for Tailwind v4 and React 19; CLI can init projects with v4" |
| shadcn/ui | latest（v4 兼容版） | latest | 无；与 Tailwind v4 全量适配 | Active | 同上来源 — "Full support for `@theme` directive and `@theme inline`; HSL→OKLCH non-breaking" |
| SQLAlchemy | 2.0.x（pin `^2.0.49`） | 2.0.49（2026-04-03） | 无（2.1.0b2 仍 beta，故选 2.0 stable line） | Active | [pypi.org/project/SQLAlchemy](https://pypi.org/project/SQLAlchemy/)、[sqlalchemy.org/blog/2026/01/21/sqlalchemy-2.1.0b1-released](https://www.sqlalchemy.org/blog/2026/01/21/sqlalchemy-2.1.0b1-released/) — "2.0.49 released 2026-04-03; 2.1.0b2 (beta) released 2026-04-16" |

**查证待补**（首次落地者负责，方式：写入 lockfile 或 `pyproject.toml`/`package.json` 后回填本表）：

| 选型 | 责任执行层 | 落地触发点 |
|---|---|---|
| pnpm（包管理） | frontend-dev | 首个 feature 创建 `frontend/` 时 |
| React Router、Zustand | frontend-dev | 首个 feature 引入路由/状态时 |
| Vitest、React Testing Library | frontend-dev | 首个 feature 写组件测试时 |
| ESLint、Prettier | frontend-dev | 首个 feature 创建 lint 配置时 |
| pytest、pytest-asyncio | backend-dev | 首个 feature 创建 `backend/tests/` 时 |
| Alembic | backend-dev | 首次数据库迁移时 |
| Ruff、Black | backend-dev | 首个 feature 创建 lint 配置时 |
| PostgreSQL（Docker image tag） | backend-dev | 首次落地 `docker-compose.yml` 时 |
| Docker Compose（生产部署细节） | tech-lead | 启动生产部署 ADR 时 |

**回填规则**：执行层补全任一项时，更新本表对应行的"选定版本/最新稳定版/查证日期/信息来源"，并在 `git commit` message 注明 `docs(adr): backfill ADR-000 verification for [pkg]`，无需新开 ADR。当选定版本与最新稳定版出现 ≥1 个 minor/major 差距时，必须在"与最新版差距"列写明原因与复盘条件，遵循 tech-lead.md 行事原则 #3。
