chairemobilite/evolution

Evolution

Evolution是一个旅行调查平台，其独特之处在于支持旅行日记功能，参与者可记录一天内的所有行程。该平台允许开发灵活的问卷，包含多个任意部分，支持复杂条件、验证、标签和选项，所有这些都可通过脚本使用先前的任何答案。

使用此平台的调查是完整的应用程序，通过TypeScript脚本定义问题和部分。通常，调查应用分为两个独立网站：一个供参与者直接填写问卷，另一个用于管理、监控、验证调查，以及为参与者和电话访问员提供技术支持。

本仓库在example/demo_survey文件夹中包含一个示例旅行调查，可复制此目录并开始编辑自定义调查。

Linux系统依赖安装

Linux安装Node.js

若Linux系统已安装Node.js（18.x或20.x版本），可跳过此步骤。

bash
sudo apt update
sudo apt install nodejs curl
node -v
curl --version
curl -sL https://deb.nodesource.com/setup_20.x -o /tmp/nodesource_setup.sh
sudo bash /tmp/nodesource_setup.sh
sudo apt install nodejs
node -v

Linux安装Yarn

若Linux系统已安装Yarn，可跳过此步骤。

bash
sudo npm install -g yarn
yarn -v

Linux安装PostgreSQL和PostGIS

Linux用户需按以下说明安装依赖。

bash
sudo apt update
sudo apt install postgresql postgis
psql --version

# 为postgres用户创建密码（可选）
sudo -u postgres psql -c "ALTER USER postgres PASSWORD '<密码>'"

Windows系统依赖安装

以下是Windows系统的依赖安装说明：

• 访问https://www.enterprisedb.com/downloads/postgres-postgresql-downloads下载PostgreSQL
• 安装PostgreSQL，过程中需为postgres数据库超级用户设置密码，并确保安装pgAdmin 4和Stack Builder组件，端口可使用5432
• 在PowerShell中运行psql --version验证PostgreSQL版本
• 找到并运行与数据库一起安装的“Stack Builder”程序，选择“Spatial Extensions”部分，选择最新的“PostGIS Bundle”选项，接受默认设置并安装

应用准备与编译

以下是应用准备和编译的步骤：

• 在项目根目录创建.env文件（可复制.env.example文件）并进行项目配置
• 更新.env文件中的Postgres连接字符串，如需使用Google地图，需创建新的Google地图API密钥

env
PG_CONNECTION_STRING_PREFIX = "postgres://postgres:<密码>@localhost:5432/" 
GOOGLE_API_KEY = "<你的GoogleApiKey>"

• git submodule init && git submodule update：获取Transition子模块
• yarn install或yarn：下载应用所需依赖包
• yarn compile：将TypeScript文件转换为JavaScript
• yarn setup：为当前项目设置数据库
• yarn migrate：使用最新更改更新数据库模式
• （可选）yarn create-user：在数据库中创建新用户，该用户可登录Web界面。可通过以下参数以非交互模式运行：yarn create-user --username <用户名> --email <邮箱> --password <明文密码> [--first_name <名> --last_name <姓> --[no-]admin --[no-]valid --[no-]confirmed --prefs <偏好设置JSON字符串>]。例如，创建具有英语偏好的管理员用户：yarn create-user --username admin --email admin@example.org --password MyAdminPassword --admin --prefs '{ "lang": "en" }'

运行示例应用

示例应用包含两个独立应用。本地开发时，参与者应用默认运行在8080端口，管理应用运行在8082端口。每个应用需构建客户端应用并运行服务器。

构建并运行参与者应用

• yarn build:dev或yarn build:prod：分别以开发模式（含完整调试代码）或生产模式（含压缩代码以提升性能）构建客户端应用
• yarn start：启动服务器，监听8080端口

参与者应用可通过http://localhost:8080访问。

构建并运行管理应用

• yarn build:admin:dev或yarn build:admin:prod：分别以开发模式和生产模式构建管理应用
• HOST=http://localhost:8082 yarn start:admin --port 8082：启动服务器并监听8082端口，同时覆盖HOST环境变量以匹配管理应用URL

更新应用

更新应用或切换到可能更改transition子模块的分支时，运行以下命令确保应用正确更新：

bash
# 拉取分支
git checkout main
git pull origin main

# 更新应用
yarn reset-submodules
yarn
yarn compile
yarn migrate

运行应用UI测试

Evolution支持使用Playwright运行UI测试。调查需实现自己的测试，但evolution-frontend在tests/ui-testing文件夹中提供了库。

查看examples/demo_survey/tests文件夹获取UI测试示例。

要为demo_survey应用运行测试，按以下步骤操作：

复制仓库中的配置文件到测试目录，并根据需要修改构建：

bash
cp packages/evolution-frontend/playwright-example.config.ts survey/playwright.config.ts

安装Playwright依赖和浏览器：

bash
yarn test:ui:install-dependencies

（可通过npx playwright install --with-deps firefox等命令指定安装特定浏览器，详见Playwright文档）

启动应用：

bash
yarn build:dev 或 yarn build:prod
yarn start

运行测试：

bash
yarn test:survey

注：在项目定义的test:survey脚本中，需添加LOCALE_DIR环境变量以注册当前项目的翻译。例如，在demo_survey项目中，脚本定义为："test:survey": "LOCALE_DIR=$(pwd)/locales npx playwright test"

每个测试需获取自己的执行上下文。以下是启动应用UI测试的示例：

js
import { test } from '@playwright/test';
import * as testHelpers from 'evolution-frontend/tests/ui-testing/testHelpers';
import * as surveyTestHelpers from 'evolution-frontend/tests/ui-testing/surveyTestHelpers';
import { SurveyObjectDetector } from 'evolution-frontend/tests/ui-testing/SurveyObjectDetectors';

const context = {
    page: null as any,
    objectDetector: new SurveyObjectDetector(),
    title: '',
    widgetTestCounters: {}
};

// 配置测试为串行模式（依次运行）
test.describe.configure({ mode: 'serial' });

// 初始化测试页面并添加到上下文
test.beforeAll(async ({ browser }) => {
    context.page = await testHelpers.initializeTestPage(browser, context.objectDetector);
});

// 打开页面并***登录
surveyTestHelpers.startAndLoginAnonymously({ context, title: '魁北克长途旅行', hasUser: false });

// TODO 添加测试用例

// 测试结束时登出
surveyTestHelpers.logout({ context });