color_full/docs/adr/0001-architecture-stack.md

ADR-0001: 整体技术栈选型

状态: 已决议 日期: 2026-05-20 决策者: 架构评审

---

上下文

构建 AI 驱动的化妆品配方研发智能平台（纯 Web 端），涉及四大核心模块：颜色引擎（广色域渲染）、配方可视化编辑器（拖拽交互 + 实时 AI 反馈）、配方记录管理（结构化存储 + NL 搜索）、配方推演引擎（多方案并行优化）。需对前端框架、图表库、色彩科学库、后端架构、数据库等做出技术选型。

---

决策

1. 前端框架 → React 18 + TypeScript 5.7

候选	优势	劣势	结论
React	生态最丰富；ECharts/D3/color.js 均有 React 绑定；招聘成本最低；TS 成熟	Hooks 学习曲线	✅ 推荐
Vue 3	模板直观；Composition API 类型推导好	ECharts 官方 React 绑定更成熟；D3 + Vue 组合不如 React 灵活	❌
Svelte 5	编译时框架，运行时极小	生态较小；关键库适配风险；社区资源少	❌
SolidJS	性能优于 React；API 相似	社区太小（GitHub stars ~30k vs React ~230k）；生产风险高	❌

决策：React 18 + TypeScript strict mode。React 19 待生态稳定后再升级。

---

2. 构建工具 → Vite 6

候选	优势	劣势	结论
Vite	原生 ESM 开发（毫秒级 HMR）；Rollup 生产打包；零配置开箱；SSR 可选	—	✅ 推荐
Next.js 15	全栈能力；SSR/SSG/ISR	内部工具无需 SSR/SEO；增加复杂度；App Router 学习曲线陡峭	❌
Remix	SSR 优先；Web 标准	同上；社区较 Next.js 小	❌
CRA	—	已停止维护；Webpack 构建慢	❌

决策：Vite 6，SPA 模式。平台为内部工具，无需 SEO/SSR。

---

3. 状态管理 → Zustand 5

候选	优势	劣势	结论
Zustand	极简 API（无 Provider/Reducer）；TS 完美；< 2KB；中间件（persist/immer/devtools）	—	✅ 推荐
Redux Toolkit	完善的 DevTools；团队规范	模板代码多；概念多（slice/thunk/selector）；过度工程化	❌
Jotai	原子化精细更新	原子拆分粒度决策成本高；对中型应用过度	❌
MobX	响应式直观	装饰器语法过时；与 React 18+ 严格模式兼容性问题	❌

决策：Zustand。服务端状态用 TanStack Query，客户端状态用 Zustand，边界清晰。

---

4. 路由 → React Router v7

候选	优势	劣势	结论
React Router v7	最广泛使用；layout routes；v7 类型安全路由；社区资源极丰富	—	✅ 推荐
TanStack Router	编译时类型安全最强	生态较小；与第三方库集成案例少	❌

决策：React Router v7。

---

5. CSS 方案 → Tailwind CSS 4 + CSS Modules

候选	优势	劣势	结论
Tailwind + CSS Modules	Tailwind 处理 80% 日常样式；CSS Modules 处理复杂定制（颜色盘）；零运行时；Tailwind v4 CSS-first 配置	需同时掌握两套语法	✅ 推荐
styled-components	CSS-in-JS，组件级隔离	运行时开销（~14KB）；Server Components 不兼容趋势	❌
Panda CSS	编译时 CSS-in-JS	较新（2024），生态不成熟	❌
Vanilla Extract	类型安全 CSS-in-JS	构建步骤复杂；社区小	❌

决策：Tailwind CSS 4（原子化，处理布局/间距/响应式）+ CSS Modules（处理颜色盘 Canvas 容器、图表交互区等复杂定制场景）。

---

6. UI 行为组件 → Radix UI

候选	优势	劣势	结论
Radix UI	Headless（完全控制样式）；WAI-ARIA 内置；组件粒度合适；与 Tailwind 天配	无预置视觉风格（需要自行设计）	✅ 推荐
Ant Design	开箱即用，组件丰富	企业后台感强；视觉定制困难；不适合创意工具；bundle 大	❌
MUI	Material Design 完整实现	同上；Google 风格固化	❌
shadcn/ui	基于 Radix + Tailwind，复制源码	本质是 Radix 封装；直接 Radix 更灵活	❌

决策：Radix UI 提供 Dialog、Popover、Dropdown、Tabs、Tooltip 等行为组件。视觉层完全自定义，匹配配方研发工具的专业调性。

---

7. 图表可视化 → ECharts 5（主力） + D3.js 7（定制）

候选	雷达图	拖拽饼图	仪表盘	散点图	自定义度	Bundle	结论
ECharts	✅ 内置	✅ resize 事件	✅ 内置	✅ 内置	中	300KB（按需150KB）	✅ 主力
D3.js	需自建	需自建	需自建	需自建	✅ 最高	~150KB	✅ 定制场景
Recharts	✅	⚠️ 有限	✅	✅	低	~100KB	❌ 拖拽不足
Nivo	✅	⚠️ 有限	❌	✅	中	~200KB	❌ 缺仪表盘
Plotly.js	✅	⚠️	✅	✅	中	~3MB	❌ 体积过大
Visx	需自建	需自建	需自建	需自建	高	按需	❌ 开发量大

决策：

• ECharts 处理标准化图表：雷达图（肤感指标）、饼图（成分比例，监听 resize 实现拖拽联动）、仪表盘（稳定性/成本）、散点图（成本-功效 Pareto 前沿）
• D3.js 处理高度定制场景：色相环/颜色盘、配方路径示意图、配方结构树图
• React 绑定使用 echarts-for-react

---

8. 色彩科学 → color.js

候选	色空间	ΔE	Display P3	色域映射	TS 类型	维护者	结论
color.js	Lab/LCH/OKLab/Display P3 + 20+	CIEDE2000/CMC/...	✅	✅	✅ 完备	Lea Verou (W3C CSS WG)	✅ 推荐
chroma.js	Lab/LCH/RGB	CIEDE2000	❌	❌	⚠️ 部分	Gregor Aisch	❌ 缺 P3
culori	Lab/LCH/OKLab	CIEDE2000	⚠️ 有限	⚠️ 有限	✅	Dan Burzo	❌ 社区小
d3-color	Lab/RGB	❌ 无	❌	❌	✅	Mike Bostock	❌ 功能太基础

决策：color.js。唯一同时支持 Display P3 色空间、CIEDE2000 ΔE、色域映射的开源 JS 库。由 CSS Color Level 4 规范编者维护，与浏览器标准对齐。

---

9. 拖拽交互 → DnD Kit

候选	状态	鼠标/触摸/键盘	碰撞检测	TS	维护	结论
@dnd-kit	活跃	✅ 全部	可定制	✅	活跃	✅ 推荐
react-beautiful-dnd	停止维护	鼠标/触摸	内置	⚠️	Atlassian 停止维护（2023）	❌
Pragmatic drag and drop	活跃	✅ 全部	可定制	✅	Atlassian 新项目	⚠️ 太新

决策：@dnd-kit/core + @dnd-kit/sortable。饼图段的拖拽调整比例场景完美匹配，支持自定义碰撞检测算法。

---

10. 数据请求 → TanStack Query 5

候选	优势	劣势	结论
TanStack Query	缓存/重试/乐观更新/无限滚动开箱即用；与 Zustand 分工清晰	—	✅ 推荐
SWR	类似功能	API 不如 TanStack Query 丰富	❌
RTK Query	Redux 集成	绑定 Redux	❌

决策：TanStack Query v5。推荐列表、配方搜索、AI 预测等所有异步请求均通过它管理。

---

11. 后端 → Fastify（BFF 单体）+ 外部 AI API

┌─────────┐     HTTP/SSE     ┌──────────┐     HTTP       ┌──────────┐
│  React   │ ◄─────────────► │ Fastify   │ ◄────────────► │ AI API    │
│  前端    │                  │  BFF 层   │               │ (外部)    │
└─────────┘                  └────┬─────┘               └──────────┘
                                  │
                             ┌────▼─────┐
                             │PostgreSQL │
                             │ + pgvector│
                             └──────────┘

层	技术	职责	理由
BFF	Fastify 5	API 聚合、认证鉴权、文件上传、配方 CRUD、AI API 调用代理、SSE 推送	TS 全栈一致性；Schema 验证内置；性能优于 Express
AI	外部 API	配方预测、配方生成、NL 解析、颜色匹配推荐	无需自建 ML infra；按需调用；模型持续更新
通信	REST + SSE	前端 ↔ BFF REST；AI 预测 SSE 实时推送；BFF ↔ AI API HTTP	SSE 适合单向实时数据流；BFF 统一处理 AI 调用的编排和降级

BFF 框架对比	优势	劣势	结论
Fastify	高性能（~60k req/s）；插件体系；内置 Schema 验证（AJV）；TS 支持；日志（pino）	社区较 Express 小	✅ 推荐
Express	生态最大；中间件极多	性能较低；无内置验证；回调风格	❌
Hono	极快；边缘部署	主要用于 Cloudflare/边缘场景	❌

AI API 调用设计（详见 ADR-0002）：

BFF 作为 AI API 的统一网关，负责：

• 编排：组合多次 API 调用（如"先解析 NL 查询 → 再向量搜索 → 组合 prompt → 生成推荐"）
• 降级：API 超时或失败时返回缓存结果或降级提示
• 限流：保护 API 额度，控制并发
• 缓存：相似查询复用结果，减少 API 调用
• SSE 流式：配方推演等长耗时场景，BFF 转发 AI API 的 streaming 响应

AI 能力	调用方式	说明
配方指标预测	Prompt + 历史数据（few-shot）	将成分列表和比例作为 context，LLM 预测肤感/稳定性/成本
NL 搜索解析	LLM → 结构化查询 → pgvector	LLM 将自然语言转为过滤条件 + 向量搜索
配方生成/推演	LLM with constraints	给定约束条件，LLM 生成候选配方方案
颜色推荐	LLM + 色彩库	结合色差计算和 LLM 推理推荐色浆组合
成分标签提取	LLM 结构化提取	从配方文本中提取 INCI 名称、比例、工艺参数

---

12. 数据库 → PostgreSQL 16 + pgvector

候选	结构化	向量搜索	JSONB	全文搜索	运维	结论
PostgreSQL + pgvector	✅	✅ IVFFlat/HNSW	✅	✅	成熟	✅ 推荐
MongoDB	⚠️ 文档型	✅ Atlas Vector	✅	⚠️	成熟	❌ 配方强关系
Elasticsearch	❌	⚠️ 需插件	❌	✅	复杂	❌ 过度
Neo4j	❌ 图	⚠️	❌	❌	小众	❌ 过度

决策：PostgreSQL 16 + pgvector。

• 配方是强结构化数据（成分→相→配方→版本，经典关系模型）
• pgvector 0.7+ 支持 HNSW 索引，NL 搜索和相似配方匹配性能优秀
• JSONB 处理灵活的工艺参数和元数据
• 一个数据库同时满足关系查询 + 向量搜索 + 全文搜索，运维简单
• 配方版本管理利用 PostgreSQL 的 MVCC + 时间戳快照

---

13. 对象存储 → MinIO

决策：MinIO（S3 兼容），存储参考图片、导出文件。本地部署，S3 API 可无缝迁移到云。

---

14. 部署 → Docker Compose（开发）+ K8s（生产）

服务	端口	职责
Nginx	80/443	静态资源、反向代理、SSL 终结
Fastify BFF	3001	API 聚合、认证、文件上传、AI API 代理
PostgreSQL	5432	配方数据 + 向量
MinIO	9000	对象存储
Redis（可选）	6379	缓存、Session、AI 响应缓存

开发环境：Docker Compose 一键启动所有服务（无需 AI 依赖，BFF 可 mock AI API） 生产环境：Kubernetes，仅 4 个核心服务，显著降低运维复杂度

---

后果

正向

• React + Vite + Zustand + TanStack Query 形成轻量高效的现代前端栈
• ECharts + D3.js 组合覆盖标准化图表和定制可视化全场景
• color.js 唯一满足 Display P3 + CIEDE2000 需求的色彩库
• AI 通过外部 API 调用，无需自建 ML 基础设施，运维简单
• 仅 4 个核心服务（Nginx + BFF + PostgreSQL + MinIO），部署轻量
• PostgreSQL + pgvector 单一数据库减少运维复杂度

风险和缓解

风险	缓解
color.js 仍为 Beta（v0.x）	锁定版本；Delta E 逻辑简单，必要时可自实现 CIEDE2000
DnD Kit 维护节奏慢	API 稳定，核心功能完备；锁定版本
AI API 延迟 / 不可用	BFF 层缓存 + 降级策略；关键路径设置超时（详见 ADR-0002）
AI API 调用成本	缓存相似查询；Prompt 压缩优化；使用 cheaper 模型做预处理
pgvector HNSW 索引构建耗时	配方数据量级可控（万级），索引构建秒级

需要关注但未在本次决议的

• CI/CD 流水线（GitHub Actions / GitLab CI）
• 监控和日志（Sentry + Grafana + Loki）
• 认证方案（JWT + OAuth2 / LDAP 企业对接）
• 测试框架细节（在实现阶段决策）

---

参考

• PRD: .scratch/formula-rd-platform/PRD.md
• CSS Color Level 4: https://www.w3.org/TR/css-color-4/
• color.js: https://github.com/color-js/color.js
• pgvector: https://github.com/pgvector/pgvector