# 访客预约系统（管理端 + 后端）

模块化单体：**Spring Boot 3 + MyBatis-Plus + Sa-Token**，管理前端 **Vue3 + Vite + Element Plus**。数据库脚本在 `backend/src/main/resources/db/migration/`，**需自行在 MySQL 中按 `V1`、`V2`… 顺序手动执行**。小程序端由其他团队对接 `/api` 契约。

## 环境要求

- **JDK 17+**（Spring Boot 3 必需）
- **Node.js 18+**
- **MySQL 5.7/8.0**（创建库 `appointment`）
- **Redis 6+**（Sa-Token 使用 **独立连接** `sa-token.alone-redis`，默认库索引 `1`）

### Sa-Token 独立 Redis

会话与 token 持久化走 **`sa-token-alone-redis`**，与业务侧将来可能使用的 `spring.data.redis` **互不影响**。

| 环境变量 | 说明 | 默认 |
|----------|------|------|
| `SATOKEN_REDIS_HOST` | Redis 地址 | `127.0.0.1` |
| `SATOKEN_REDIS_PORT` | 端口 | `6379` |
| `SATOKEN_REDIS_PASSWORD` | 密码（无则留空） | 空 |
| `SATOKEN_REDIS_DATABASE` | 逻辑库（建议单独给 token） | `1` |

本地可执行：`docker compose up -d redis`（见仓库根目录 `docker-compose.yml`）。

## 后端

```bash
cd backend
# 修改 src/main/resources/application.yml 中数据源
# 首次部署请在库 appointment 中手动执行 db/migration 下 SQL（按版本号顺序）
mvn spring-boot:run
```

- API：`http://localhost:8080/api`
- OpenAPI：`http://localhost:8080/swagger-ui/index.html`

### 双登录体系（重要）

| 端 | 路径前缀 | 认证方式 | 说明 |
|----|-----------|----------|------|
| **平台管理后台** | `/api/auth/login`、除 `/api/mini/**` 外的受保护接口 | `sys_user` **用户名+密码**（BCrypt） | 与小程序密码**不共用** |
| **微信小程序** | `/api/mini/auth/login`、`/api/mini/**` | `wx.login` 的 **js_code** + 手机号按钮的 **phoneCode** → 服务端 **code2session**、**access_token**、**getuserphonenumber** | 分 **访客** / **员工**（`loginIntent`）；`WECHAT_MINI_STUB=false` 且配置 `app-id`/`secret` 时走真微信 |

- 员工首次使用小程序：需在 **`mp_user`** 中写入 `user_type=EMPLOYEE`、**`dept_id`**、**`dept_leader_flag`**（0/1，是否部门负责人）及与微信一致的手机号；与 **`sys_user` 无任何绑定**（由运维 SQL 或后续管理功能维护）。
- 访客首次：`loginIntent=VISITOR` 时若无记录会自动注册为访客。
- 两类 token 均可放在请求头 **`Authorization`**，但**不可混用**（分别由 `StpUtil` 与 `StpLogic("mini")` 校验）。

**小程序登录请求体示例**：`{ "wxCode": "<wx.login>", "phoneCode": "<getPhoneNumber 回调 e.detail.code>", "loginIntent": "VISITOR" }`。

### 默认账号（`V1__init.sql` 等脚本中的种子数据）

| 用户     | 密码       | 说明                          |
|----------|------------|-------------------------------|
| admin    | password   | 管理员                        |
| handler  | password   | 经办人（一级审批）            |
| leader   | password   | 部门负责人（二级）+ 经办角色  |

> 密码哈希为常见测试值（`password`），**生产环境必须重置**。

### RabbitMQ（可选）

默认已排除 `RabbitAutoConfiguration`，无 MQ 时仍可启动；导出接口会仅打日志并返回 `taskId`。接入 MQ 时删除 `application.yml` 中的 `spring.autoconfigure.exclude` 对应项并启动 Rabbit。

## 前端（管理后台）

```bash
cd frontend-admin
npm install
npm run dev
```

浏览器访问 `http://localhost:5173`，登录后走 Vite 代理调用后端。

## 模块与分层

- 包根：`com.sinata.appointment`
- **Controller** 仅入参/返回，**禁止**直接注入 Mapper
- 业务在 `*ApplicationService`，审批编排见 `ApprovalEngineService`
- 统一响应：`Result` / `ResultUtil`；实体基类：`BaseEntity`

## 文档

- [安全与性能基线](docs/SECURITY-PERF.md)