先说几个核心判断。整个过程并不依赖手写代码，而是通过自然语言描述业务需求，让AI来生成项目结构、数据模型、API接口，甚至是D3.js的族谱图渲染。这样一来，环境配置与接口联调这类耗费时间的工作，基本都能跳过。

先搭骨架：用Cursor一句话生成项目结构

新建一个空文件夹，在Cursor中打开它，然后按Cmd+K（Mac）或Ctrl+K（Win）唤出Composer，输入这样一段话：

“用React+TypeScript+Vite搭建族谱管理App前端，用Flask+Python 3.11做后端API，数据库用SQLite，要求所有接口返回JSON，支持CORS，前端路由按成员列表/添加成员/族谱图三页组织。”

大概90秒后，Cursor会自动生成完整的目录结构，包括src/、backend/、pyproject.toml、vite.config.ts等文件。整个过程不需要手动执行npm init或pip install。如果手动搭建，至少需要2小时，而且容易漏配Vite别名或Flask静态路径。

定义数据模型：让AI写出带约束的Schema

有两种方式可以完成这一步。

方法一：在Composer中继续输入：“根据族谱业务，生成Prisma schema（如果用PostgreSQL）或SQLite表结构SQL（如果用本地SQLite）。字段必须包含：id、name、gender、birth_date、death_date、father_id、mother_id、spouse_id、notes。要求father_id/mother_id/spouse_id均为可空外键，birth_date为TEXT格式（ISO8601），并加注释说明每个字段用途。”

方法二：直接在backend/app.py同级新建models.py，对AI说：“写一个Python类Member，用dataclass实现，含上述全部字段，birth_date和death_date类型为Optional[str]，所有ID字段类型为Optional[int]，加type hints和__repr__。”

字段注释不能跳过。后续AI生成CRUD逻辑时，会依赖这些语义信息判断“mother_id是否允许为0”或“notes要不要做XSS过滤”。漏写注释，可能导致接口返回空字符串却不报错。

连通前后端：自动补全API调用与错误处理

第一步：在前端src/lib/api.ts中，对AI说：“生成一个useMembers hook，用React Query v5，包含getMembers()、addMember()、updateMember(id)三个函数。addMember接收{name, gender, birth_date}对象，自动序列化为JSON并POST到/backend/members；失败时toast提示具体错误信息，不是笼统的‘请求失败’。”

第二步：在backend/main.py中，对AI说：“写一个POST /members接口，接收JSON body，校验name非空、birth_date符合YYYY-MM-DD格式，插入SQLite后返回201和新member对象。若校验失败，返回400和{‘error’: ‘xxx’}。”

第三步：回到前端，在addMember成功回调里加一句：na vigate(`/member/$ {data.id}`)。这一步不能省。否则用户点击“添加”后页面没有反应，会误以为功能失效。

渲染族谱图：用D3.js轻量集成

在src/components/FamilyTree.tsx中，对AI说：“用D3.js v7渲染树状族谱图，数据源来自useMembers返回的members数组，节点显示name和birth_date，连线用斜线，支持缩放和平移。不用力扣式复杂交互，只要能看清三代以内直系关系。”

AI会生成一个带useEffect + useRef的组件。关键点在于：需要把d3.select('#tree-container')改成d3.select(containerRef.current)，否则热更新时SVG元素残留会导致重绘错乱。

最后在App.tsx里添加：

高度设为h-96是硬性要求——D3需要明确尺寸才能计算布局，设置min-h-96会失效。

一键部署：本地打包+Vercel托管+SQLite只读挂载

执行npm run build，进入dist/文件夹，把整个dist内容拖进Vercel Dashboard新建项目。Framework Preset选择“Vanilla”，点击Deploy即可。

后端部署另走一路：用Railway.app新建Python项目，上传backend/全部文件。在Settings里把启动命令改为gunicorn -b :8000 main:app。Volumes中挂载128MB磁盘，路径设为./db/。启动后，访问Railway分配的URL，确认GET /members返回[]。

前端通过Vercel环境变量NEXT_PUBLIC_API_BASE设置为Railway后端地址。代码里不能写死http://localhost:5000，否则上线后所有请求都会返回404。