本地运行

本页记录本地启动文档站、后端服务和 Flutter App 的最小闭环。命令默认在仓库根目录 D:\Fitdoc_app 下执行。

运行前准备

对象	要求	说明
Node.js	可运行 npm	用于 VitePress 文档站。
Python	可创建虚拟环境	后端依赖由 apps/backend_service/requirements.txt 管理。
PostgreSQL	本地库或可访问的开发库	后端启动和 Alembic 迁移依赖 DATABASE_URL。
Flutter SDK	可运行 flutter pub get	App、Web 调试和安装包构建依赖 Flutter。
环境变量	从 .env.example 复制并填写本地值	不使用生产密钥和生产连接串做本地默认配置。

文档站

cd D:\Fitdoc_app\docs_site
npm install
npm run docs:dev

默认开发服务由 VitePress 启动在本机地址，站点基路径为 /doc-center/：

http://127.0.0.1:5173/doc-center/

构建与本地预览：

npm run docs:build
npm run docs:preview

构建产物位于：

docs_site/.vitepress/dist/

后端服务

cd D:\Fitdoc_app\apps\backend_service
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
alembic upgrade head
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

本地后端健康检查：

curl http://127.0.0.1:8000/health

端口口径：

环境	后端端口	用途
本地开发	8000	uvicorn --reload 调试。
生产 ECS	8001	fitdoc-core.service behind Nginx。

Flutter App

cd D:\Fitdoc_app\apps\flutter_app
flutter pub get
flutter run -d chrome

移动端设备调试：

flutter run -d android

常用环境注入：

flutter run -d chrome `
  --dart-define=APP_ENV=development `
  --dart-define=API_BASE_URL=http://127.0.0.1:8000/api `
  --dart-define=VIDEO_BASE_URL=http://127.0.0.1:8000/static/videos

API_BASE_URL 需要包含 /api 前缀，因为 Flutter client 会在此基础上拼接 /auth、/chat、/sport 等模块路径。

本地验证

检查	命令或入口	预期
文档站构建	npm run docs:build	构建通过。
后端健康检查	curl http://127.0.0.1:8000/health	返回健康状态 JSON。
API 文档面	http://127.0.0.1:8000/docs	FastAPI Swagger UI 可打开。
Flutter 依赖	flutter pub get	依赖解析成功。
Flutter Web	flutter run -d chrome	App 能加载并发起 API 请求。

来源锚点

• AGENTS.md
• docs_site/package.json
• apps/backend_service/requirements.txt
• apps/backend_service/alembic.ini
• apps/backend_service/.env.example
• apps/flutter_app/lib/config/environment_config.dart