# 模板说明
## 包管理工具
`pnpm@10+`
## 脚本命令
| 命令 | 说明 |
| ---------- | ---------------------------------------------- |
| prepare | husky钩子，安装依赖时会自动执行husky的准备工作 |
| dev | 开发指令，环境：dev |
| dev:qa | 开发指令，环境：qa |
| dev:pre | 开发指令，环境：pre |
| dev:prod | 开发指令，环境：prod |
| build | 编译指令（type-check + build-only） |
| test:unit | 单测指令 |
| build-only | 仅编译指令 |
| type-check | ts类型校验 |
| lint | eslint校验 |
| lint:fix | eslint校验（带自动fix） |
## 使用
- 确保你安装了正常的包管理工具
pnpm@10+
- 安装依赖
```
pnpm install
```
- 运行项目
```
pnpm run dev
```
> 你可以自由选择不同的环境指令
- 编译项目
```
pnpm run build
```
## 技术栈及主要依赖说明
主要技术栈：vite + vue3 + vue-router
### 三方依赖说明
| 名称 | 版本 | 作用 | 备注 |
| ------------------------------------------------------------------------------------- | ----- | ------------------------ | --------------------------------------------------------------------------------- |
| [element-plus-cisdi](https://design.cisdigital.cn/plus/zh-CN/guide/installation.html) | 1.0.0 | 基础UI组件库 | element-plus定制版 |
| vue | 3.5+ | UI框架 | |
| pinia | 2+ | 状态管理 | |
| vite | 6+ | 前端开发与构建工具 | |
| eslint | 9+ | 代码格式化，风格统一管理 | 提交校验：husky + lint-staged + eslint
校验规则使用@eslint/config |
| @commitlint/cli | 19+ | commit内容校验 | 提交校验：husky + commitlint
校验规则使用@commitlint/config-conventional@19+ |
| vue-router | 4+ | 路由库 | |
| dayjs | 1.11+ | 时间工具库 | |
| lodash-es | 4+ | 常见工具库 | |
| @vueuse/core | 12+ | 常见hook库 | |
| vitest | 3+ | 单元测试 | |
| echarts | 5+ | 图表库 | |
| vue-i18n | 10+ | 多语言管理库 | |
| unocss | 66+ | 原子类css | |
| husky | 9+ | git hook | |
### 自有依赖说明
| 名称 | 作用 | 备注 |
| -------------------------- | ---------------- | --------------------------------------- |
| @lingshu/icon | icon组件 | 用于接入字体图标 |
| @lingshu/vite-plugin-msw | 本地mock数据模拟 | 通过vite变量`VITE_ENABLE_MOCK`启用/关闭 |
| @lingshu/vite-plugin-share | 共享依赖接入 | 用于接入通用共享依赖 |
| @lingshu/integration-vue3 | 主子应用对接插件 | |
| @lingshu/language-lib | 多语言管理库 | 由于后端支持原因，未完善，后续统一修改 |
| @lingshu/request-lib | 请求库 | axios二封产物 |
| @lingshu/theme-lib | 多主题插件 | |
> 版本建议：若依赖共享则跟随共享版本走，否则以最新版本为准
## 基础目录
```
.
├── .husky/ # 存储Git钩子脚本，用于自定义Git操作行为
├── .vscode/ # 存储Visual Studio Code的配置文件，如代码片段、设置等
├── coverage/ # 存储代码覆盖率报告，用于评估测试的有效性(可能存在)
├── dist/ # 存储构建后的分发文件，通常是生产环境部署的文件
├── node_modules/ # 存储项目依赖的Node.js模块
├── public/ # 存储公共资源文件，如网站图标等
├── src/ # 存储源代码
| ├── api/ # api请求封装
│ ├── assets/ # 存储静态资源文件，如图像、样式表等
│ │ ├── dark # 暗色主题静态资源
│ │ ├── light # 亮色主题静态资源
│ ├── components/ # 存储可复用的Vue组件
│ ├── constants/ # 存储全局常量
│ ├── directives/ # 存储自定义Vue指令
│ ├── hooks/ # 存储自定义Vue钩子函数
│ ├── icons/ # 通用字体图标资源
│ ├── locales/ # 当前库多语言管理以及非自研三方库多语言管理（如：element-plus）
│ ├── router/ # 存储Vue Router的路由配置
│ ├── stores/ # 存储Vuex状态管理的配置
│ ├── styles/ # 存储通用css
│ ├── type-utils/ # 通用ts类型辅助函数
│ ├── types/ # 存储通用ts类型
│ ├── utils/ # 存储工具函数和实用程序
│ │ ├── requestUtils.ts # 请求库工具
│ ├── views/ # 存储页面级别的Vue组件
│ ├── App.vue # 根Vue组件，通常包含整个应用的布局
│ └── main.ts # 入口文件，用于启动和编译Vue应用
├── .env # 存储通用环境变量
├── .env.dev # 存储dev环境变量
├── .env.pre # 存储pre环境变量
├── .env.prod # 存储prod环境变量
├── .env.qa # 存储qa环境变量
├── .gitattributes # Git属性文件，用于设置文件属性和行为
├── .gitignore # Git忽略文件，指定Git不应跟踪的文件和文件夹
├── index.html # HTML入口文件，通常是Web应用的入口页面
├── package.json # 项目配置文件，包含依赖列表、脚本和元数据
├── .npmrc # npm配置文件，用于设置npm的配置选项
├── .nvmrc # nvm配置文件，用于设置node的版本
├── pnpm-lock.yaml # pnpm锁文件，用于确保依赖版本的一致性
├── README.md # 项目自述文件，包含项目介绍、安装和使用指南
├── tsconfig.json # TypeScript配置文件，设置TypeScript的编译选项
├── .env.d.ts # 环境变量的TypeScript声明文件
├── tsconfig.app.json # TypeScript配置文件，用于配置应用程序的编译选项
├── tsconfig.node.json # TypeScript配置文件，用于配置Node.js环境的编译选项
├── tsconfig.vitest.json # TypeScript配置文件，用于配置Vitest测试框架的编译选项
├── vite.config.ts # Vite配置文件，设置Vite构建工具的选项
├── commitlint.config.ts # Commitizen配置文件，设置提交消息的规范
├── eslint.config.mts # ESLint配置文件，设置代码规范和风格
├── uno.config.ts # UnoCSS配置文件，设置UnoCSS的选项
└── vitest.config.ts # Vitest配置文件，设置Vitest测试框架的选项
```
## 接入主应用
to-do
## 环境
### 环境说明
项目模板中预置了多个环境配置文件，可视实际开发情况进行使用
- `.env`：通用环境配置
- `.env.local`: 通用环境配置，但是会被git忽略
- `.env.dev`：dev环境配置
- `.env.pre`：pre环境配置
- `.env.prod`：prod环境配置
- `.env.qa`：qa环境配置
> 运行相应指令即可启动对于环境文件的环境变量
>
> 如：启动 `pnpm run dev:qa`
>
> 可使`.env.qa`文件中的环境变量生效
>
> 更详细的说明可参考：[vite 环境变量](https://vitejs.cn/vite5-cn/guide/env-and-mode.html#env-variables)
### 环境变量说明
**各环境文件配置**
| 属性名称 | 作用 |
| ------------- | --------------------------------------------------- |
| VITE_API_BASE | 请求代理前缀，会在`vite.config.ts`的proxy配置中使用 |
**local本地化配置**
`.env.local`文件不会上传到git仓库，主要用于存放一些在开发过程中需要频繁修改的属性
| 属性名称 | 作用 |
| ---------------- | ------------ |
| VITE_ENABLE_MOCK | 是否开启Mock |
### 本地调试登录
见 [docs/development/local-auth.md](./docs/development/local-auth.md)
## vscode插件
本模板内置推荐项：
| 插件 | 作用 |
| ------------ | ------------------------- |
| unocss | 原子类css的代码提示及补全 |
| eslint | 格式化插件 |
| vitest | 单测插件 |
| vue-official | vue代码提示 |
非内置推荐项：
| 插件 | 作用 |
| ------------------- | --------------------------------------------------------------------------------------------------------------- |
| git-commit-plugin | commit交互式填写工具，可便捷完成commit内容 |
| var-translate-en | 变量命名工具。支持单驼峰、双驼峰、下划线、全大写等格式；支持中译英，英译英；支持阿里等服务提供商的免费百万token |
| vscode-code-to-type | js/json转ts类型定义 |
| code-spell-checker | 单词拼写检查 |
> 相关配置文件放于 `.vscode/extensions.json`和`.vscode/settings.json`中，若需要进一步定制化，可修改其文件配置
## 多主题接入说明
见[ones链接](https://ones.cisdigital.cn/wiki/#/team/SKG3mSQb/space/4W7YLcLr/page/4MCTXeA6)
## 其他说明
- `.gitkeep`文件用于在git仓库中保证目录的留存，实际使用可删除
- views和router目录下存放及使用的一些页面文件属于示例文件，可删除
## to-do
- 多语言发布脚本，引用新的多语言npm库