# Nomo Web

基于 React + TypeScript + Vite 的 H5 前端项目。

## 环境要求

- Node.js >= 18.20.7
- pnpm >= 9

## 快速开始

```bash
pnpm install --frozen-lockfile
pnpm dev
```

浏览器访问控制台输出的本地地址即可。

## 脚本说明

| 命令 | 说明 |
|------|------|
| `pnpm dev` | 本地开发（使用 `.env.localdev` + `.env`） |
| `pnpm build` | 生产构建（等价于 `build:prod`） |
| `pnpm build:dev` | 开发模式构建（`.env.development`） |
| `pnpm build:prod` | 生产模式构建（`.env.production`） |
| `pnpm build:test` | 测试环境构建（`.env.test`） |
| `pnpm preview` | 预览构建产物（使用 localdev 模式） |
| `pnpm lint` / `pnpm lint:fix` | ESLint 检查 / 自动修复 |
| `pnpm stylelint` / `pnpm stylelint:fix` | 样式检查 / 自动修复 |

## 环境配置

通过不同 `.env` 文件区分环境，Vite 按 **mode** 加载：

| 文件 | 何时加载 |
|------|----------|
| `.env` | 始终加载（公共默认） |
| `.env.localdev` | `pnpm dev` / `pnpm preview`（`--mode localdev`） |
| `.env.development` | `pnpm build:dev` |
| `.env.production` | `pnpm build` / `pnpm build:prod` |
| `.env.test` | `pnpm build:test` |
| `.env.local` | 本地覆盖，除 test 外都会加载（一般不提交） |

需在环境文件中配置的变量见 `.env` 内注释或项目文档。

## 技术栈

- **框架**：React 18、TypeScript
- **构建**：Vite 6、pnpm
- **UI**：Ant Design 5、Tailwind CSS、SCSS/Less
- **路由**：React Router 7
- **状态**：基于 Context + Hooks 的 Model 方案（类 Umi max）
- **国际化**：i18next（zh-CN / en-US / fa-IR）
- **请求**：Axios 封装（`src/utils/request`）
- **图标**：@iconify/react + 自定义 SVG 转 Iconify 插件
- **规范**：ESLint、Prettier、Stylelint、Commitlint、Husky、lint-staged

## 项目结构

```
├── build/              # Vite 构建相关（插件、工具）
├── public/             # 静态资源
├── src/
│   ├── assets/         # 资源
│   │   └── iconify/    # 单色 single-color、多色 multi-color 图标
│   ├── components/     # 公共组件
│   ├── config/         # 应用与请求配置（含 request 拦截器、错误处理）
│   ├── defines/        # 枚举与常量
│   ├── hooks/          # 公共 Hooks
│   ├── i18n/           # 国际化配置
│   ├── layouts/        # 布局
│   ├── locales/        # 多语言文案（zh-CN、en-US、fa-IR）
│   ├── models/         # 全局状态 Model
│   ├── pages/          # 页面（按页面分目录）
│   ├── router/         # 路由配置
│   ├── services/       # API 接口（按模块分目录）
│   ├── styles/         # 全局样式
│   ├── utils/          # 工具与 request 封装
│   ├── App.tsx
│   └── main.tsx
├── types/              # 全局类型与 env 类型
├── index.html
├── vite.config.ts
└── package.json
```

## 开发规范摘要

- 严格 TypeScript，遵循项目 ESLint/Prettier 配置
- 提交信息使用 Conventional Commits
- 组件：函数组件 + Hooks；样式优先 Tailwind，必要时 SCSS/Less
- 用户可见文案全部走 `locales`，禁止在代码中硬编码
- 常量与枚举放在 `src/defines/`，请求在 `src/services/` 按模块组织
- 新页面：在 `src/pages/` 下建目录、在 `routes` 与 `locales` 中注册

## 状态管理（Model）

- Model 定义在 `src/models/`，通过 `createModel(hook, name)` 创建。
- 在组件中：`const user = userModel.useModel()`，使用返回的状态与方法。
- 根组件已通过 `autoImportModels` 注入所有 Model 的 Provider。

详见 `src/utils/model/` 与现有 `userModel`、`dialogModel`、`userConfigModel` 实现。

## 图标

- 单色图标：放入 `src/assets/iconify/single-color/`，会转为 `currentColor`，可用 `className` 控制颜色。
- 多色图标：放入 `src/assets/iconify/multi-color/`，保留原色。
- 使用：`import icon from '@/assets/iconify/single-color/xxx.svg'`，再 `<Icon icon={icon} />`（@iconify/react）。

## 多语言

- 文案在 `src/locales/` 下按语言分目录（zh-CN、en-US、fa-IR），每语言含 common、components、menus、pages 等模块。
- 组件内：`const { t } = useTranslation();`，`t('key')` 或带命名空间的 key。
- 禁止在页面/组件中写死中文或英文字符串。

## 请求与接口

- 请求封装：`src/utils/request`，基础配置与拦截器在 `src/config/request/`（认证、加解密、错误处理）。
- 接口按模块放在 `src/services/`，每模块可有 `typings.d.ts` + `index.ts`。
- 调用：`import { fetchXxx } from '@/services/xxx'`，错误由统一错误处理兜底，可选 `skipErrorHandler` 自行处理。

## 本地存储

- `src/utils/localUtils`、`src/utils/sessionUtils` 提供 `createLocalTools` / `createSessionTools`，支持按 key/value 加密与命名空间。
- 通过环境变量配置加密密钥与存储命名空间，敏感数据建议开启加密选项。

## 部署

- 构建产物在 `dist/`，将对应环境（如 test/production）的构建结果部署到静态服务器或 CDN 即可。
- 多环境通过上述 `build:dev` / `build:test` / `build:prod` 与对应 `.env.*` 区分。