134 lines
4.1 KiB
Markdown
134 lines
4.1 KiB
Markdown
# 本单位访客预约及权限管理系统
|
||
|
||
## 项目概述
|
||
|
||
基于微信小程序的通用权限底座 + 访客预约模块，支持动态角色扩展和模块化功能开发。
|
||
|
||
## 技术栈
|
||
|
||
### 后端
|
||
- 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/ # 静态资源
|
||
```
|