aaronkw/humanbase-react

HumanBase前端开发环境镜像

镜像概述

本镜像提供HumanBase应用的完整前端开发环境，包含Node.js、Yarn等依赖工具，支持本地开发、状态机可视化、代码规范检查及后端服务集成，适用于开发人员构建、测试和调试HumanBase前端应用。

核心功能

• 本地开发支持: 提供Node.js、Yarn安装指南及项目依赖配置步骤。
• CORS解决方案: 针对Chrome/Safari浏览器的跨域限制解除方法。
• XState可视化: 支持本地或远程状态机可视化工具，便于状态逻辑调试。
• 代码质量保障: 集成ESLint自动修复、pre-commit钩子，确保代码规范。
• SEEK功能集成: 通过SSH隧道访问Princeton SEEKRPC服务，支持SEEK功能本地测试。
• 调试界面: 提供#debug路由的调试面板，支持状态图表查看和Cookie清除。
• 自动化测试: 基于Jest框架的单测与全量测试支持。

使用场景

• HumanBase前端应用的日常开发与调试。
• XState状态机逻辑的可视化分析与验证。
• 集成Princeton SEEKRPC服务的功能测试。
• 代码规范与质量检查。

配置说明

开发环境准备

1. 参考humanbase-docker-dev仓库README.md完成HumanBase基础设置。
2. 安装Node.js: https://nodejs.org/en/download
3. 安装Yarn: https://classic.yarnpkg.com/lang/en/docs/install/
4. 本地测试与静态分析配置:
   • 进入项目目录: cd <path>/humanbase-docker-dev/node/humanbase-react
   • 安装依赖: yarn install

CORS限制解除

• Chrome: 在~/.bash_profile添加别名，启动允许CORS的Chrome实例:

  bash
  alias getchrome='open -n -a /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --args --user-data-dir="/tmp/chrome_dev_test" --disable-web-security'
  

• Safari: 启用开发者菜单，选择"Disable Cross-Origin Restrictions"。

XState可视化工具（推荐）

1. 克隆仓库: git clone https://github.com/statelyai/xstate-viz.git
2. 进入目录: cd xstate-viz
3. 安装依赖: yarn install
4. 启动本地服务: yarn run start -p 3421

SEEK功能本地使用

通过SSH隧道连接Princeton SEEKRPC服务器:

bash
ssh -L 9090:0.0.0.0:9090 nebulus -l <你的账户名>

输入密码后即可使用本地SEEK功能。

调试界面

在浏览器地址栏添加#debug访问调试面板，支持状态图表可视化、Cookie清除等功能。

Docker部署示例

yaml
# docker-compose.yml片段
services:
  node:
    image: docker.xuanyuan.run/aaronkw/humanbase-react
    volumes:
      - ./humanbase-react:/app
    ports:
      - "3000:3000"
    command: yarn start

启动服务:

bash
docker compose up -d node

查看日志:

bash
docker compose logs --tail=200 -f node

进入容器:

bash
docker compose exec node bash

自动化测试

• 全量测试: yarn run test
• 单套件测试: yarn run test whatsNewMachine
• 更新快照: yarn run test -- -u
• 启用日志: yarn run test -- --useStderr=true

XState入门指南

（完整内容请参考原文档，以下为核心摘要） XState是状态机管理工具，用于处理复杂UI逻辑。本镜像支持XState可视化，通过调试面板可查看状态流转、事件触发及副作用执行。

提示与故障排除

• 维护通知: 修改LandingPage.js中的startDate/endDate及maintenanceWarning变量，自动显示维护通知。
• API文档: 访问http://localhost:8000/api/docs/查看API文档。
• 容器日志: 使用docker compose logs查看所有容器日志，或docker compose logs -f node跟踪Node服务日志。