# 家长到校参观邀请系统

面向学校老师和受邀家长的移动端 H5 项目。老师可向家长发送校园参观邀请，家长通过邀请链接查看到访时间、地点、联系人及注意事项，并完成到访确认。

## 项目目标

- 为老师提供清晰、统一的家长到校邀请入口
- 向家长展示参观安排和到访须知
- 支持邀请身份校验、访问控制及到访状态管理
- 为后续接入分享、签到、消息提醒和访问数据统计保留扩展能力

## 技术栈

- Vue 3 + TypeScript
- Vite 6
- Vue Router 4
- Pinia + `pinia-plugin-persistedstate`
- Axios
- UnoCSS

## 环境要求

- Node.js `>= 22.11.0`
- pnpm `>= 9.13.2`

可执行以下命令检查本地 Node.js 环境：

```bash
pnpm run check-env
```

## 本地开发

1. 安装依赖：

```bash
pnpm install
```

2. 在项目根目录创建 `.env.local`：

```dotenv
VITE_SECRET_KEY=replace-with-a-random-value
```

`VITE_SECRET_KEY` 用于本地持久化数据的加密。所有 `VITE_` 变量都会进入前端产物，不能用于保存服务端密钥或其他高敏感凭证。

3. 启动开发服务器：

```bash
pnpm run dev
```

默认访问地址为 `http://localhost:5173`。

## 常用命令

| 命令                        | 说明                       |
| --------------------------- | -------------------------- |
| `pnpm run dev`              | 启动本地开发服务器         |
| `pnpm run build`            | 执行类型检查并构建生产产物 |
| `pnpm run preview`          | 本地预览生产构建           |
| `pnpm run check-env`        | 检查 Node.js 版本          |
| `pnpm run upload`           | 执行项目部署脚本           |
| `pnpm run build-and-upload` | 构建并部署项目             |

运行部署命令前，需要先根据目标环境检查 `upload.sh` 中的服务器地址、部署目录、私钥及通知配置。

## 目录结构

```text
src/
├── api/          # 请求封装与鉴权处理
├── components/   # 通用组件
├── router/       # 路由配置、权限控制与页面缓存
├── store/        # Pinia 状态及持久化配置
├── utils/        # 通用工具
├── views/        # 业务页面
├── App.vue       # 根组件
└── main.ts       # 应用入口
```

## 开发约定

- 无需登录或身份校验的页面配置在 `src/router/publicRoutes.ts`
- 需要身份或角色控制的页面配置在 `src/router/privateRoutes.ts`
- 业务状态统一放在 `src/store`，可复用业务逻辑优先拆分为组合式函数
- 小型 SVG 图标放入 `public/icons`，通过 `SvgIcon` 组件使用
- 生产代码提交前至少执行一次 `pnpm run build`