# 本单位访客预约及权限管理系统

## 项目概述

基于微信小程序的通用权限底座 + 访客预约模块，支持动态角色扩展和模块化功能开发。

## 技术栈

### 后端
- Go 1.21 + Gin + GORM (PostgreSQL 16)
- Casbin (gorm-adapter) 动态权限
- JWT 认证
- go-redis + MinIO + RabbitMQ
- Zap + Viper + snowflake

### 前端
- Uniapp (Vue3 组合式 API)
- uView Plus 组件库
- Pinia 状态管理

## 快速开始

### 1. 启动基础设施

```bash
cd sc-lktx-backend
docker-compose up -d
```

### 2. 配置

编辑 `sc-lktx-backend/config/config.yaml`：
- 设置 `admin.openid` 为管理员微信 openid（生产环境务必配置）
- 配置微信 AppID 和 AppSecret

### 3. 启动后端

```bash
cd sc-lktx-backend
go mod tidy
go run ./cmd/server
```

### 4. 启动前端

```bash
cd sc-lktx-mp-frontend
npm install
npm run dev:h5
```

## 默认角色

通用权限底座提供以下内置角色，支持动态增加：

| 角色 | Code | 说明 |
|------|------|------|
| 管理员 | admin | 系统管理员，拥有所有权限 |
| 员工 | employee | 园区正式员工，可审核预约、生成邀请 |
| 非员工 | non_employee | 外包/临时工/合作方等非正式员工 |
| 保安 | guard | 门卫保安，核验进出 |
| 访客 | visitor | 默认角色，可创建预约 |

> **设计说明**：
> - **多角色支持**：一个用户可同时拥有多个角色（如既是员工又是保安）
> - **员工（领导）**：领导不再作为独立角色，而是通过 `Employee.IsLeader` 属性在业务层区分。拥有 `employee` 角色 + `IsLeader=true` 即具备领导权限
> - **动态扩展**：管理员可通过后台管理界面动态创建新角色、分配权限，无需修改代码
> - **通用 Token**：最外层小程序签发 JWT Token（包含所有角色），各功能模块通过 Casbin 中间件验证权限

## 默认模块

| 模块 | Code | 说明 |
|------|------|------|
| 访客预约 | appointment | 访客预约管理 |
| 门禁管理 | gate | 门禁进出管理 |
| 食堂管理 | canteen | 食堂订餐管理（预留） |
| 系统管理 | admin | 系统后台管理 |

## 扩展新模块

1. 后端在 `internal/modules/` 下新建包，实现 Handler
2. 在 `main.go` 路由中注册模块接口，使用 Casbin 中间件挂载权限
3. 管理员在后管界面创建模块并分配权限策略
4. 前端添加对应页面，通过 `userStore.hasRole('xxx')` 控制可见性

### 模块内权限设计模式

```go
// 在 RegisterRoutes 中使用 Casbin 中间件
moduleGroup := r.Group("/module-name")
moduleGroup.Use(middleware.CasbinAuth(enforcer, "module_domain", "resource:action"))
// 管理员在后台添加策略: some_role, module_domain, resource:action, allow
```

### 前端角色判断（动态，无需硬编码）

```typescript
const userStore = useUserStore()
// 通用判断
userStore.hasRole('employee')   // 是否拥有某角色
// 便捷 getter
userStore.isAdmin     // 管理员
userStore.isEmployee  // 员工
userStore.isGuard     // 保安
userStore.isVisitor   // 访客
```

## 项目结构

```
├── sc-lktx-backend/          # 后端 Go 项目
│   ├── cmd/server/main.go    # 入口
│   ├── config/               # 配置文件
│   ├── internal/
│   │   ├── common/           # 公共模块
│   │   │   ├── middleware/   # 中间件
│   │   │   ├── model/        # GORM 模型
│   │   │   ├── response/     # 统一响应
│   │   │   └── utils/        # 工具函数
│   │   ├── modules/          # 业务模块
│   │   │   ├── appointment/  # 访客预约
│   │   │   └── role/         # 角色申请
│   │   ├── auth/             # 认证模块
│   │   ├── admin/            # 管理模块
│   │   └── pkg/              # 基础设施封装
│   └── docker-compose.yml    # Docker 编排
│
└── sc-lktx-mp-frontend/      # 前端 Uniapp 项目
    ├── pages/                # 页面
    ├── store/                # Pinia 状态管理
    ├── utils/                # 工具函数
    └── static/               # 静态资源
```