Getting Started

Getting-Started

最短本地路径：先前端 mock，再按需接后端。

前置

项	建议
Node	与 frontend/package.json 引擎一致（团队常用 Node 20+）
包管理	pnpm（frontend）
Python	3.11+ · 仓根 venv
端口	见下表；冲突时改完同步 docs/agents/port-registry.md

端口

服务	端口	URL
Frontend	3100	http://127.0.0.1:3100
Backend API	8000	http://127.0.0.1:8000
README 预览壳	4173	http://127.0.0.1:4173/preview-readme.html

请用 3100。:3001 容易撞到陈旧 Service Worker 导致白屏。

A. 只跑前端（最快看 Console）

cd frontend
pnpm install
PORT=3100 pnpm dev

Windows PowerShell 可用：

cd frontend
pnpm install
$env:PORT=3100; pnpm dev

打开 http://127.0.0.1:3100/console 。默认 mock，不依赖本地 API。

B. 本地后端

仓根（已建 venv 时先激活）：

python -m uvicorn app.main:app --reload --port 8000

冒烟：

curl http://127.0.0.1:8000/health
pytest

C. 前端接本地 API（real UI 模式）

在 frontend 配置（名称以仓库 env 文档为准）：

变量名	示例
NEXT_PUBLIC_DEMO_MODE	real
NEXT_PUBLIC_API_BASE_URL	http://127.0.0.1:8000

完整表：docs/backend/ENV_VARS.md

D. README 预览壳（可选）

与产品无关，只预览根 README.md 排版：

# 仓根
python -m http.server 4173

→ http://127.0.0.1:4173/preview-readme.html

下一步

• 演示故事：Demo-Walkthrough
• mock / real：Mock-vs-Real-CAW
• 线上 URL：Deploy-and-Live-URLs