dimagi/formplayer

FormPlayer

概述

FormPlayer是一个基于Spring Framework开发的RESTful XForm录入服务。通过用户恢复和http://dimagi.github.io/xform-spec/%EF%BC%8CFormPlayer%E6%94%AF%E6%8C%81%E9%80%9A%E8%BF%87JSON%E8%B0%83%E7%94%A8%E5%92%8C%E5%93%8D%E5%BA%94%E8%BF%9B%E8%A1%8C%E8%A1%A8%E5%8D%95%E5%BD%95%E5%85%A5%EF%BC%88%E8%AF%A6%E8%A7%81%E4%B8%8B%E6%96%87%EF%BC%89%E3%80%82%E8%BF%99%E4%BA%9B%E6%96%87%E4%BB%B6%E9%80%9A%E5%B8%B8%E7%94%B1https://www.github.com/dimagi/commcare-hq%E6%9C%8D%E5%8A%A1%E5%99%A8%E5%AE%9E%E4%BE%8B%E6%89%98%E7%AE%A1%E3%80%82FormPlayer%E4%BE%9D%E8%B5%96https://www.github.com/dimagi/commcare-core%E5%BA%93%EF%BC%88%E4%BD%9C%E4%B8%BA%E5%AD%90%E4%BB%93%E5%BA%93%E5%8C%85%E5%90%AB%EF%BC%89%EF%BC%8C%E5%B9%B6%E9%80%9A%E8%BF%87gradle%E6%9E%84%E5%BB%BA%EF%BC%88%E5%90%AB%E5%8C%85%E8%A3%85%E5%99%A8%E6%96%87%E4%BB%B6%EF%BC%89%E3%80%82

核心功能和特性

• RESTful API：提供基于HTTP的JSON接口，支持XForm表单的录入与交互
• 多数据库支持：通过Redis缓存会话实例，Postgres存储会话实例，为每个恢复用户构建SQLite数据库
• CommCare集成：依赖CommCare-core库，与CommCareHQ服务器无缝协作
• 灵活构建：支持含测试或不含测试的构建方式，提供持续测试模式
• API文档自动生成：通过SpringFox插件生成Swagger API文档

使用场景和适用范围

适用于需要集成XForm表单录入功能的CommCareHQ环境，支持本地开发、Docker容器化部署及生产环境服务，满足表单数据采集、会话管理和用户数据隔离需求。

详细使用方法和配置说明

依赖环境

• Java (OpenJDK 8)
• Redis（用于缓存会话实例）
• Postgres（用于存储会话实例）
• SQLite（为每个恢复用户构建数据库）

构建与运行

基础步骤

1. 克隆仓库

   bash
   $ git clone https://github.com/dimagi/formplayer.git
   

2. 下载子模块依赖

   bash
   $ git submodule update --init --recursive
   

3. 创建属性文件

   bash
   $ cp config/application.example.properties config/application.properties  # 根据需要更新属性（默认值适用于本地运行）
   

   特别注意：确保server.port值与CommCareHQ的localsettings.py中FORMPLAYER_URL的端口一致。

4. 创建数据库 运行以下命令创建formplayer数据库（执行后需输入密码，本地运行时使用CommCareHQ本地Postgres用户的密码，可在localsettings.py的DATABASES部分找到）：

   bash
   $ createdb formplayer -U commcarehq -h localhost  # 根据需要更新连接信息（默认值适用于本地运行）
   

   若Postgres运行在Docker中，需在Docker shell中执行，可通过CommCareHQ仓库的./scripts/docker bash postgres命令进入。

运行命令

• 含测试运行

  bash
  $ ./gradlew build && java -jar build/libs/formplayer.jar
  

• 不含测试运行

  bash
  $ ./gradlew assemble && java -jar build/libs/formplayer.jar
  

• 测试命令

  bash
  $ ./gradlew test
  
  # 运行单个测试
  $ ./gradlew :test --tests tests.NewFormTests.testNewForm
  
  # 持续测试模式
  $ ./gradlew test -t
  

• Linux构建注意事项：有时需运行

  bash
  $ gradle wrapper
  

故障排除

• "Could not resolve project :commcare"
  运行git submodule update --init

• 编译错误（如"no suitable constructor found for OutputFormat(Document)"）
  可能是Java版本错误，执行java -version应显示1.8。解决方法：

  • 安装OpenJDK 8
  • 配置gradle使用新Java：
    • 更新~/.gradle/gradle.properties，添加org.gradle.java.home=/JDK_PATH
    • 或在gradle命令后附加-Dorg.gradle.java.home=/JDK_PATH

在IntelliJ中运行

为支持断点调试和源码关联，建议使用IntelliJ IDE：

1. 下载IntelliJ IDE
2. 打开IntelliJ，选择"导入项目"
3. 导航到克隆的formplayer仓库，选择根目录下的build.gradle
4. 取消勾选"使用自动导入"和"为空内容根自动创建目录"，勾选"使用gradle包装器"
5. 点击"确定"

注：也可使用Android Studio，步骤同上。

保持application.properties更新

application.example.properties可能会新增必要配置，更新代码后若遇错误，可运行：

bash
diff -u config/application{.example,}.properties

缺失的配置行以-开头。

在Docker中运行

若需将FormPlayer作为CommCare HQ的Docker服务运行，从CommCare HQ仓库执行以下步骤：

1. 检查是否为Mac系统，若是，直接按照上文构建和运行步骤操作。
2. 正常启动CommCare HQ的Docker服务：scripts/docker up（仅服务）或scripts/docker runserver（HQ及服务）。
3. 运行scripts/get_webhost，将输出添加到/etc/hosts（Linux用户可执行scripts/get_webhost | sudo tee -a /etc/hosts）。
4. 若本地运行Django版CommCare HQ：
   1. 更新localsettings.py：FORMPLAYER_URL = 'http://localhost:8010'和BASE_ADDRESS = 'webhost:8000'
   2. 启动Django：./manage.py runserver 0.0.0.0:8000
5. 此后通过[***]

贡献指南

• 普通PR：仅修改Formplayer仓库代码时，在单独分支提交PR至Formplayer。

贡献commcare代码变更

Formplayer依赖commcare-core仓库，该仓库master分支不稳定，Formplayer使用formplayer分支。子模块libs/commcare应始终指向formplayer分支。

更新CommCare版本

将Formplayer更新至CommCare新版本（如2.34→2.35）时，需从commcare_X.Y分支向formplayer分支提交PR。QA完成后合并PR并更新Formplayer子模块。

API文档

FormPlayer通过Spring的Swagger插件https://github.com/springfox/springfox%E8%87%AA%E5%8A%A8%E7%94%9F%E6%88%90API%E6%96%87%E6%A1%A3%E3%80%82%E5%90%AF%E5%8A%A8%E6%9C%8D%E5%8A%A1%E5%99%A8%E5%90%8E%EF%BC%8C%E8%AE%BF%E9%97%AE%60http://localhost:8080/swagger-ui.html#/%60%EF%BC%88%E6%A0%B9%E6%8D%AE%E5%AE%9E%E9%99%85%E4%B8%BB%E6%9C%BA%E5%92%8C%E7%AB%AF%E5%8F%A3%E8%B0%83%E6%95%B4%EF%BC%89%E6%9F%A5%E7%9C%8B%E6%96%87%E6%A1%A3%E3%80%82