diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2da1963
--- /dev/null
+++ b/README.md
@@ -0,0 +1,103 @@
+# 配方研发智能平台
+
+AI 驱动的化妆品配方研发辅助工具（纯 Web 端）。
+
+## 功能模块
+
+| 模块 | 功能 |
+| :--- | :--- |
+| **配方记录** | 创建/编辑/详情/可视化编辑、AI 提取、版本历史与对比、自然语言搜索 |
+| **颜色引擎** | D3.js 交互色相环、Lab/RGB 滑条微调、HEX/RGB/Lab/潘通色号输入、CIEDE2000 ΔE 实时计算、取色棒（EyeDropper API + Canvas 降级）、AI 配色推荐、皮肤材质预览 |
+| **可视化编辑器** | ECharts 环形饼图、成分比例滑条 ±0.1%、AI 实时指标预测（SSE）、雷达图（肤感子维度）、仪表盘（稳定性评分）|
+| **配方推演** | 多约束条件设置（成本/指标/排除成分）、SSE 流式推演、方案卡片实时生成、成本-功效散点图、方案对比表 |
+| **平台** | JWT 认证、项目管理、CSV 导出、全局搜索、深色/浅色主题 |
+
+## 技术栈
+
+- **前端**: React 19 + TypeScript + Vite + Tailwind CSS 4
+- **状态管理**: Zustand + TanStack Query
+- **图表**: ECharts + D3.js
+- **色彩科学**: color.js（CIELAB + Display P3 + CIEDE2000）
+- **后端**: Fastify 5 + TypeScript
+- **数据库**: PostgreSQL 16 + pgvector
+- **ORM**: Prisma 7
+- **AI**: OpenAI / DeepSeek API + Prompt 模板 + 缓存/降级/限流
+- **测试**: Vitest（42 tests）
+
+## 快速开始
+
+### 环境要求
+
+- Node.js 24+
+- pnpm 11+
+- Docker
+
+### 初始化数据库
+
+```bash
+docker compose up -d --build postgres
+cd backend
+pnpm install
+npx prisma migrate deploy
+npx tsx prisma/seed.ts
+```
+
+或一键初始化：
+
+```bash
+bash scripts/init-db.sh
+```
+
+### 启动
+
+```bash
+# 终端 1 - 后端
+cd backend && pnpm dev
+
+# 终端 2 - 前端
+cd frontend && pnpm dev
+```
+
+访问 http://localhost:5173
+
+### AI 配置
+
+进入「设置」页面：
+1. 选择 Mock/Real 模式
+2. 填入 OpenAI / DeepSeek API Key
+3. 点击「测试」验证连通性
+4. 点击「保存配置」
+
+## 项目结构
+
+```
+color_full/
+├── frontend/           # React 前端
+│   └── src/
+│       ├── components/ # 可复用组件
+│       ├── pages/      # 页面组件
+│       ├── layouts/    # 布局
+│       ├── stores/     # Zustand stores
+│       ├── hooks/      # 自定义 hooks
+│       └── lib/        # 工具（色彩/API）
+├── backend/            # Fastify 后端
+│   └── src/
+│       ├── routes/     # API 路由
+│       ├── services/   # 业务逻辑（AI）
+│       └── lib/        # 工具
+├── docker/             # Dockerfile（pgvector）
+├── docs/adr/           # 架构决策记录
+├── .scratch/           # PRD + Issues
+└── scripts/            # 脚本
+```
+
+## 测试
+
+```bash
+cd backend && pnpm test   # 26 tests
+cd frontend && pnpm test  # 16 tests
+```
+
+## License
+
+Private