'init'

2026-06-29 17:34:59 +08:00
commit fe3ad20fe2
271 changed files with 51767 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,133 @@
+# 本单位访客预约及权限管理系统
+
+## 项目概述
+
+基于微信小程序的通用权限底座 + 访客预约模块，支持动态角色扩展和模块化功能开发。
+
+## 技术栈
+
+### 后端
+- 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/               # 静态资源
+```