radiantone/iddm-ui

Radiant Logic V8 UI

镜像概述和主要用途

Radiant Logic V8 UI 是一个前端开发项目，旨在为Radiant Logic V8提供用户界面开发支持。该项目包含完整的开发流程，从环境配置、依赖安装、开发调试到测试、构建和部署，支持多种开发工具和库，确保开发效率和代码质量。

核心功能和特性

• 灵活的IDE支持：无特定IDE依赖，推荐使用VS Code及配套插件提升开发体验
• 严格的依赖管理：指定Node.js LTS版本（v20.11.1）和npm版本（v10.2.4），避免编译错误
• 完整的开发流程：包含开发、测试、构建、代码检查等全流程命令
• 多环境测试支持：集成Jest单元测试和Cypress端到端测试，支持本地、QA和生产环境
• 代码质量保障：通过ESLint、Stylelint进行代码检查，Husky Git Hooks防止不良提交
• 结构化项目架构：清晰的文件夹结构，便于代码组织和维护

使用场景和适用范围

• 本地开发Radiant Logic V8的用户界面
• 编写和运行单元测试与端到端测试
• 构建生产环境或测试环境的UI包
• 集成CI/CD流程进行自动化测试和构建
• 团队协作开发，确保代码规范和质量

详细的使用方法和配置说明

IDE配置

无特定IDE依赖，可使用任何IDE或文本编辑器，推荐使用VS Code，并安装以下推荐插件：

• Auto Rename Tag
• Babel Javascript Code Spell Checker
• Color Highlight
• DotENV
• ESLint
• Git Blame
• GitLens
• Prettier（启用"Format on Save"）
• Stylelint
• Git Prefix

若要在VS Code中启用保存时自动排序导入，需在VS Code的settings.json文件中添加以下配置：

json
{
  "editor.codeActionsOnSave": {
    "source.fixAll": true,
    "source.organizeImports": true,
    "source.sortMembers": true
  }
}

可使用Git Prefix从分支中提取工单编号并插入提交信息，便于跟踪提交与工单的关联。在settings.json中添加以下配置：

json
{
  "gitPrefix.pattern": ".*(RO-\\d+).*"
}

安装

项目需使用Node.js LTS版本v20.11.1（npm v10.2.4），安装前请确保版本一致，避免编译错误。

sh
npm install

安装完成后会自动运行postinstall脚本，生成Chakra主题类型。

开发

sh
npm start

以开发模式运行应用，启动后可通过http://localhost:3000在浏览器中查看。启动前会运行gen:config-dev生成开发环境配置。

测试

sh
npm test

运行所有测试。

sh
npm run test:watch

以交互模式运行测试观察器，实时监控测试变化。

Cypress测试

sh
npm run cypress:run
npm run cypress:runqa --password='QA NETLIFY密码'
npm run cypress:runprod --password='生产环境NETLIFY密码'

在命令行中运行所有Cypress测试，"run"默认使用本地环境，"runqa"和"runprod"分别对应QA和生产环境。

sh
npm run cypress:open
npm run cypress:openqa --password='QA NETLIFY密码'
npm run cypress:openprod --password='生产环境NETLIFY密码'

在浏览器中打开Cypress实例，针对指定环境进行测试。

若要将测试结果报告至TestRail，需创建cypress.env.json文件并添加以下配置：

json
{
  "testrail": {
    "domain": "",
    "username": "",
    "password": "",
    "screenshots": false,
    "projectId": "",
    "milestoneId": "",
    "suiteId": "",
    "runId": ,
    "runName": "",
    "runIncludeAll": true,
    "closeRun": true
  }
}

代码检查

sh
npm run eslint

运行ESLint检查TS和React/TSX代码。

构建

sh
npm run build

构建生产环境应用至build文件夹，会对React进行生产模式打包并优化性能。构建前运行gen:config-prod生成生产环境配置。构建产物已压缩，文件名包含哈希值，可直接部署。

sh
npm run build:test

与上述构建类似，但使用QA环境配置，构建前运行react-scripts:qa。

CI配置

sh
npm run test:ci

设置CI环境变量为true，以非交互模式运行测试，适用于CI/CD流程。

Git Hooks

通过https://github.com/typicode/husky%E8%AE%BE%E7%BD%AEGit Hooks，防止不良提交和推送。当前配置：

• 提交前运行TS/TSX代码检查
• 推送前运行测试

项目架构

文件夹结构

├── docs (项目附加Markdown文档)
├── public (HTML文件，构建过程中会自动添加编译代码的script标签)
├── src (所有源代码和资源)
    ├── api (API调用代码，包含API客户端、钩子、模型和工具函数)
    ├── assets (图标和logo)
    ├── components (React组件)
       ├── common (通用React组件)
       ├── forms (通用表单组件)
       ├── layout (页面布局组件)
       ├── pages (页面/功能组件)
    ├── config (环境配置)
    ├── hooks (全局React钩子)
    ├── locales (本地化字符串)
    ├── types (全局类型定义)
    ├── utils (非钩子工具函数)

src下的每个子文件夹应包含__tests__文件夹用于存放单元测试，每个源文件对应一个测试文件，命名格式为name.spec.extension（例如Body.spec.tsx）。

开发流程

Ensemble开发流程

编码规范

文档化的规则及说明：

• JS - 由ESLint强制执行
• React/JSX - 由ESLint强制执行
• https://google.github.io/styleguide/jsguide.html#naming-camel-case-defined

文档文件夹

docs文件夹包含特定功能和最佳实践的附加文档：

• 常见问题
• API钩子约定
• API约定
• 图标设置
• 对象构建器
• 任务监控器
• Amplitude分析

核心库

• React - UI库
• Chakra - 样式组件库
• Framer Motion - 动画组件库
• Axios - HTTP客户端
• React Query/Tanstack - 查询状态管理
• React Router - 路由库
• React Hook Form - 表单验证
• https://github.com/stefalda/react-localization - React本地化
• React Dropzone - 文件上传
• Dnd kit - 拖放工具包
• Amplitude Analytics - 分析库
• https://moment.github.io/luxon/api-docs/index.html - 日期时间格式化库

开发工具/库

• Webpack - 模块加载器
• Babel - JavaScript转译器
• Jest - 单元和集成测试
• ESLint - JavaScript和React/JSX静态代码分析
• https://github.com/stylelint/stylelint - CSS/SASS静态代码分析
• https://github.com/typicode/husky - Git提交钩子
• https://github.com/nock/nock - HTTP服务器模拟