unocha/hid-app

Humanitarian ID Web App version 2

镜像概述和主要用途

本镜像为Humanitarian ID Web App version 2（HIDv2）的Docker化构建，基于Alpine系统，用于简化HIDv2 Web应用的本地开发、测试和部署流程。该应用是人道主义领域的身份识别平台，提供用户管理、服务集成等功能。

核心功能和特性

• 支持多环境配置，可通过--target参数指定不同API环境
• 集成代码规范检查（基于John Papa Angular 1风格指南）
• 提供单元测试（Jasmine+Karma）和端到端测试（Protractor）支持
• 前端使用Sass预处理器，支持样式模块化管理
• 基于Docker Compose实现容器化部署，简化环境一致性维护

使用场景和适用范围

适用于HIDv2 Web应用的开发人员进行本地开发、功能测试、代码质量检查以及部署前验证。

详细使用方法和配置说明

本地运行

前提条件

• Docker for Mac 或对应操作系统的Docker版本
• Node
• Yarn
• Grunt
• Sass

构建应用

1. 克隆仓库：git clone git@github.com:UN-OCHA/hid_app2.git
2. 进入应用目录：cd hid_app2
3. 切换到开发分支：git checkout dev
4. 使用Yarn安装依赖：yarn install
5. 将本地URL添加到hosts文件：
   • macOS：sudo vi /etc/hosts，添加 127.0.0.1 app.hid.vm
6. 运行Grunt任务（通过--target指定API环境）：

   sh
   # 使用本地API示例
   grunt --target=local
   

   可编辑app/config/config.local.js配置各环境端点

运行应用

1. 启动容器：docker-compose up
2. 访问应用：[***]

部署

部署说明参见：https://github.com/UN-OCHA/hid-stack/blob/master/README.md

编码标准

本项目遵循https://github.com/johnpapa/angular-styleguide/tree/master/a1%E3%80%82%E5%8F%AF%E9%80%9A%E8%BF%87%E4%BB%A5%E4%B8%8B%E5%91%BD%E4%BB%A4%E6%A3%80%E6%9F%A5%E4%BB%A3%E7%A0%81%E8%A7%84%E8%8C%83%EF%BC%88%E8%A7%84%E5%88%99%E5%90%8D%E7%A7%B0%E5%8F%82%E8%80%83ESLint plugin README，格式为y123）：

sh
yarn run lint

代码检查在每个PR通过Travis集成自动运行。.eslintrc中部分规则显式设为error，表示存在已知的eslint-disable-line例外情况。若能解决某规则的所有违规，可从.eslintrc中移除该规则。

单元测试

单元测试使用https://jasmine.github.io/%E7%BC%96%E5%86%99%EF%BC%8C%E9%80%9A%E8%BF%87https://karma-runner.github.io/%E8%BF%90%E8%A1%8C%EF%BC%9A

sh
# 安装Karma CLI
yarn global add karma-cli

# 运行一次测试
grunt test

# 文件变更时重新运行测试
grunt test-watch

E2E测试

E2E测试基于Jasmine和Protractor（Angular端到端测试工具）实现。

主机环境安装

sh
# 首次设置：安装E2E工具
yarn global add protractor
webdriver-manager update

需手动安装Java Development Kit (JDK)

环境变量配置

1. 联系Marina获取"Test Accounts on FIS Platforms" Trello卡片访问权限
2. 复制e2e-tests/enviroment.example.js为environment.js
3. 将Trello卡片中的信息手动复制到环境文件（仅需一次设置）

运行测试

确保API和应用容器均已启动并正确配置本地开发环境：

sh
# 按顺序运行所有E2E测试
yarn run protractor

# 运行单个E2E测试套件（套件名称见conf.js）
protractor --suite="my-suite-name" src/e2e-tests/conf.js

本地测试失败处理

• 数据库内容可能不正确，检查测试日志中的字符串不匹配问题（如"Test Admin" vs "Test E2E Admin"），通常获取Staging环境快照可解决

TravisCI测试失败处理

Travis上的测试可能随机失败：

1. 在Staging环境手动复现问题
2. 若可复现，修复代码
3. 若不可复现，尝试重新运行Travis测试，或优化测试健壮性

测试问题解决

测试失败时可能需要手动登录并重置测试所需资源：

以Test E2E User身份：

• 取消收藏"E2e test list - standard"
• 删除"E2e temp list"

以Test Admin E2E User身份：

• 删除"E2e temp mailchimp service"和"E2e temp google service"
• 删除"E2e temp"用户
• 取消验证"Test E2E user"
• 取消与"Test E2E user"的待处理连接

前端

CSS

本项目使用Sass，运行grunt watch可监听文件变化并重建CSS。

样式结构

全局样式

重置样式、网格样式等全局样式应添加至app/common。app/common中（不包含子目录）的所有_*.scss文件会自动添加到CSS构建中。

变量和混合器

变量和混合器需在其他Sass文件前导入，因此应添加至app/common的子目录，并手动导入到app/common/_setup.scss。

组件样式

组件特定样式文件应添加至组件目录（如app/components/my-component/my-component.scss）。app/components中（包含子目录）的所有_*.scss文件会自动添加到CSS构建中。