# k1989cms

**Repository Path**: elfbobo_admin_admin/k1989cms

## Basic Information

- **Project Name**: k1989cms
- **Description**: Smart Office & IoT Platform 是一套集成了企业内部管理、物联网设备控制、人员组织管理于一体的综合性智能办公平台。系统采用模块化单体架构，通过统一身份认证实现"一套账号，通行所有业务与硬件"的目标，构建企业级数字底座。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-20
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# K1989CMS 智能办公平台

<div align="center">

![K1989CMS Logo](https://img.shields.io/badge/K1989CMS-智能办公平台-blue)
![Python](https://img.shields.io/badge/Python-3.8+-green)
![Flask](https://img.shields.io/badge/Flask-2.3.3-red)
![License](https://img.shields.io/badge/License-MIT-yellow)
![Status](https://img.shields.io/badge/Status-Active-success)

[![Gitee](https://img.shields.io/badge/Gitee-仓库-orange)](https://gitee.com/thomasblog/k1989cms)
[![Stars](https://gitee.com/thomasblog/k1989cms/badge/star.svg?theme=dark)](https://gitee.com/thomasblog/k1989cms/stargazers)
[![Forks](https://gitee.com/thomasblog/k1989cms/badge/fork.svg?theme=dark)](https://gitee.com/thomasblog/k1989cms/members)

让企业管理更智能、更高效！

</div>

---

## 📖 项目简介

K1989CMS 是一个基于 **Flask** 构建的企业级智能办公平台管理系统。它采用模块化设计，集成了资产管理、设备监控（IoT）、消费系统、访客管理、组织架构等核心业务模块，并提供强大的第三方系统集成能力，为企业提供一站式数字化管理解决方案。

本系统支持高性能的设备通信（TCP/UDP/WebSocket），并内置了完善的后台任务处理机制和监控告警功能。

### ✨ 核心特性

- 🏢 **全生命周期资产管理** - 覆盖采购、入库、领用、调拨、维修、报废全流程
- 📡 **多协议设备通信** - 支持 TCP/UDP/WebSocket，海量设备接入
- 🍽️ **智能消费系统** - 多餐厅/窗口管理、菜品菜单、订单支付、账户补贴
- 👤 **访客预约管理** - 在线预约、员工审批、白名单管理、签到记录
- 👥 **组织架构管理** - 树形结构、员工管理、权限控制（RBAC）
- 📊 **第三方平台集成** - 企业微信、钉钉、飞书等平台数据同步
- 🔐 **多层次安全防护** - JWT认证、API Key、数据加密、IP白名单
- 📈 **实时监控告警** - Prometheus监控、设备状态监控、系统性能监控

---

## 🚀 快速开始

### 环境要求

- **Python**: 3.8+
- **Redis**: 6.0+
- **MySQL**: 5.7+ 或 PostgreSQL
- **操作系统**: Windows / Linux / macOS

### 安装步骤

1. **克隆项目**

```bash
git clone https://gitee.com/thomasblog/k1989cms.git
cd k1989cms
```

2. **创建虚拟环境**

```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
.\venv\Scripts\activate   # Windows
```

3. **安装依赖**

```bash
pip install -r requirements.txt
```

4. **配置环境变量**

```bash
cp .env.example .env
# 编辑 .env 文件，配置数据库连接、Redis 密钥等
```

5. **初始化数据库**

```bash
# 方式一：使用 Flask CLI（推荐）
flask init

# 方式二：使用 main.py（会自动检查并初始化）
python main.py
```

6. **启动服务**

```bash
# 方式一：使用 main.py（推荐，支持自动数据库初始化）
python main.py

# 方式二：使用 Flask CLI 开发模式
flask run

# 方式三：使用 Flask CLI 生产模式
flask runserver

# 方式四：使用 Gunicorn（生产环境推荐）
gunicorn -c deploy/gunicorn.conf.py main:app
```

**启动方式说明**：
- `python main.py`：推荐方式，会自动检查数据库连接，如果表结构不存在会自动初始化
- `flask run`：标准的 Flask 开发服务器
- `flask runserver`：生产模式服务器，启用多线程
- `gunicorn`：生产环境推荐，性能更优

### 访问系统

- **Web 界面**: http://localhost:5000
- **管理后台**: http://localhost:5000/admin
- **用户中心**: http://localhost:5000/users
- **API 文档**: 查看路由文件获取接口信息


## 命令行工具

项目提供了丰富的命令行工具，用于管理应用、数据库和系统配置。

### 数据库管理命令

```bash
# 初始化数据库（创建表结构和默认数据）
flask init

# 重置数据库（危险操作，会删除所有数据）
flask reset

# 完整数据库设置（创建数据库、表结构、默认数据）
flask full_setup
```

### 应用运行命令

```bash
# 运行开发服务器
flask run

# 运行生产服务器（启用多线程）
flask runserver

# 直接使用 main.py 启动（推荐，支持自动初始化）
python main.py
```

### 其他命令

```bash
# 检查数据一致性
flask check_consistency
```

**命令说明**：
- `flask init`：初始化数据库表结构和默认数据（角色、管理员用户）
- `flask reset`：重置数据库，删除所有数据并重新初始化（需要确认）
- `flask full_setup`：完整的数据库设置流程，包括创建数据库、表结构、默认数据
- `flask check_consistency`：检查用户和员工数据的一致性
- `python main.py`：启动应用，会自动检查数据库连接和表结构，如果需要会自动初始化

**自动初始化功能**：
使用 `python main.py` 启动应用时，系统会自动执行以下检查：
1. 检查数据库连接是否正常
2. 检查数据库表结构是否存在
3. 如果表结构不存在，自动执行完整的数据库初始化
4. 初始化成功后，管理员密码会记录在 `docs/admin_account_info.md` 文件中

---

## 📁 项目结构

```
k1989cms/
├── agents/                      # 后台代理服务
│   ├── data_sync_agent.py       # 数据同步代理
│   ├── device_monitor_agent.py  # 设备状态监控代理
│   ├── device_sdk.py            # 设备 SDK
│   └── edr_engine.py            # EDR 引擎
├── app/
│   ├── communication/           # 设备通信模块（核心IoT模块）
│   │   ├── tcp_udp_server.py    # TCP/UDP 服务端
│   │   ├── websocket_server.py  # WebSocket 服务端
│   │   ├── heartbeat_service.py # 心跳检测服务
│   │   └── protocol_parser.py   # 协议解析器
│   ├── models/                  # 数据模型
│   ├── routes/                  # 路由与视图
│   │   ├── admin/               # 管理员后台路由
│   │   ├── api/                 # RESTful API 路由
│   │   ├── auth/                # 认证路由
│   │   ├── user/                # 用户端路由
│   │   ├── visitor/             # 访客路由
│   │   └── ...
│   ├── services/                # 业务逻辑层
│   ├── tasks/                   # Celery 异步任务
│   └── utils/                   # 工具类
├── config/                      # 配置文件
├── docs/                        # 项目文档
├── static/                      # 静态资源
├── templates/                   # 模板文件
│   ├── admin/                   # 管理后台模板
│   ├── user/                    # 用户端模板
│   └── ...
├── tests/                       # 测试代码
├── main.py                      # 应用入口
├── requirements.txt             # 依赖列表
└── README.md                    # 项目说明
```

---

## 🛠️ 技术栈

### 后端技术

| 技术 | 版本 | 说明 |
|------|------|------|
| **Python** | 3.8+ | 后端开发语言 |
| **Flask** | 2.3.3 | Web 框架 |
| **SQLAlchemy** | 2.0.23 | ORM 数据库访问 |
| **MySQL** | 8.0+ | 关系型数据库 |
| **Redis** | 7.0+ | 缓存、消息队列 |
| **Celery** | 5.3.4 | 异步任务调度 |
| **Gunicorn** | - | WSGI 服务器 |
| **JWT** | - | JSON Web Token 认证 |
| **WebSocket** | - | 实时双向通信 |
| **Alembic** | - | 数据库迁移 |

### 前端技术

| 技术 | 版本 | 说明 |
|------|------|------|
| **Bootstrap** | 5.3+ | UI 框架 |
| **jQuery** | 3.6+ | JavaScript 库 |
| **DataTables** | - | 表格组件 |
| **Chart.js** | - | 图表组件 |
| **SweetAlert2** | - | 弹窗组件 |

---

## 📡 API 文档

### 认证方式

系统使用 **JWT (JSON Web Token)** 进行身份认证。

请求需在 Header 中携带 Token：

```http
Authorization: Bearer <your_token>
```

### 常用接口

| 模块 | 接口路径 | 方法 | 说明 |
|------|----------|------|------|
| **认证** | `/api/v1/auth/login` | POST | 用户登录 |
| **资产** | `/api/v1/assets` | GET | 获取资产列表 |
| **设备** | `/api/v1/devices` | GET | 获取设备列表 |
| **用户** | `/api/v1/users` | GET | 获取用户列表 |
| **组织** | `/api/v1/departments/tree` | GET | 获取部门树 |

### WebSocket 连接

设备可通过 WebSocket 连接到服务器进行实时通信：

```javascript
// 设备端连接示例
const ws = new WebSocket('ws://localhost:5000/ws');

// 订阅设备特定消息
ws.send(JSON.stringify({
    action: 'subscribe',
    room: 'device_001'
}));
```

---

## 📊 核心功能模块

### 🏢 资产管理

- **硬件资产管理**：资产增删改查、生命周期管理、二维码管理
- **软件资产管理**：许可证管理、安装记录、使用统计
- **资产监控**：状态监控、告警管理、使用统计
- **资产维护**：维护计划、维护记录、维护提醒
- **资产转移**：转移申请、转移审批、转移记录

### 📡 设备管理

- **设备注册与配置**：设备注册、配置编辑、配置下发
- **设备监控与告警**：实时监控、历史数据、告警列表
- **设备控制**：远程控制、指令下发、状态查询
- **设备认证**：设备认证、权限管理、访问控制

### 👤 访客管理

- **访客预约**：在线预约、预约审批、预约记录
- **访客邀请**：访客邀请、邀请管理、邀请记录
- **访客通行**：通行记录、通行统计、通行报表
- **访客通知**：通知发送、通知记录、通知统计
- **白名单管理**：白名单创建、白名单编辑、白名单删除

### 🍽️ 消费管理

- **消费记录**：消费查询、消费统计、消费报表
- **消费账户**：账户余额、账户充值、账户明细
- **消费补贴**：补贴规则、补贴发放、补贴统计
- **消费支付**：支付方式、支付记录、支付统计
- **餐厅管理**：餐厅管理、窗口管理、菜品管理

### 👥 组织架构

- **部门管理**：部门树、部门编辑、部门删除
- **员工管理**：员工列表、员工详情、批量导入导出
- **多源同步**：同步配置、同步日志、同步状态

### 🔐 系统管理

- **用户管理**：用户列表、用户详情、用户编辑
- **角色管理**：角色列表、角色详情、权限分配
- **权限管理**：权限树、权限配置、权限测试
- **系统配置**：基本设置、安全设置、通知设置
- **操作日志**：日志查询、日志详情、日志导出
- **系统监控**：监控仪表板、性能图表、告警管理
- **数据备份**：备份列表、备份恢复、备份策略

### 📊 平台集成

- **第三方平台集成**：企业微信、钉钉、飞书等平台集成
- **组织架构同步**：部门同步、员工同步、通讯录同步
- **消息推送**：消息模板、消息发送、消息统计
- **单点登录**：OAuth 2.0、JWT令牌、会话管理

### 🤖 Agent 管理

- **Agent 配置**：配置模板、配置管理、配置下发
- **Agent 生成**：安装包生成、生成记录、下载管理
- **Agent 监控**：状态监控、日志查看、性能监控

**Agent 功能说明**：
- 支持多种设备类型的 Agent 部署
- 提供配置模板管理，支持批量配置下发
- 支持设备状态实时监控和日志收集
- 提供 Agent 安装包自动生成功能

### 📱 二维码服务

- **二维码生成**：访客二维码、资产二维码、设备二维码
- **二维码管理**：二维码列表、状态管理、有效期管理
- **二维码验证**：二维码扫描、二维码验证、验证记录

### 🔌 API 集成管理

- **API 密钥管理**：密钥生成、密钥管理、密钥权限
- **API 访问控制**：IP 白名单、访问频率、访问日志
- **API 文档**：接口文档、接口测试、接口版本
- **API 监控统计**：调用统计、错误统计、性能统计

### 📈 报表分析

- **报表生成**：报表模板、报表生成、报表导出
- **报表调度**：定时任务、调度管理、执行记录
- **报表分发**：分发配置、分发记录、分发统计
- **数据可视化**：图表展示、数据钻取、数据对比

### 📡 设备通信（IoT）

- **多协议支持**：TCP/UDP/WebSocket/HTTP
- **设备认证**：设备注册、认证、权限管理
- **心跳检测**：设备在线状态监控
- **消息广播**：支持向设备群发消息
- **重连机制**：自动重连和连接管理

### 🔐 安全防护

- **JWT 认证**：基于 Token 的身份认证
- **API Key 管理**：第三方应用访问控制
- **数据加密**：敏感数据加密存储
- **IP 白名单**：访问 IP 限制
- **操作日志**：完整的操作审计日志

### 📊 系统监控

- **Prometheus 监控**：性能指标采集
- **设备监控**：设备状态监控和告警
- **系统性能监控**：CPU、内存、磁盘监控
- **告警管理**：告警规则配置和通知

---

## 👤 用户端功能

用户端提供普通员工使用的功能模块，包括：

### 导航菜单

| 菜单项 | 路径 | 功能说明 |
|--------|------|----------|
| 首页 | `/users/` | 用户仪表盘，显示概览信息 |
| 资产管理 | `/assets/` | 查看个人资产、申请资产 |
| 盘点管理 | `/inventory/` | 盘点任务、盘点历史 |
| 消费管理 | `/consumption/` | 消费记录、钱包充值 |
| 访客管理 | `/visitors/` | 创建访客邀请、查看邀请记录 |
| 设备管理 | `/devices/` | 设备申请、设备监控 |
| 门禁记录 | `/user/access/records` | 查看个人通行记录 |
| 报表统计 | `/statistics/` | 数据统计报表 |
| 二维码扫描 | `/qrcode/scan` | 扫描二维码功能 |

---

## 🔧 配置说明

### 环境变量配置

项目使用 `.env` 文件管理环境变量，从 `.env.example` 复制并修改：

```bash
cp .env.example .env
```

主要配置项包括：

```bash
# 应用配置
FLASK_ENV=development              # 运行环境：development/production
SECRET_KEY=your-secret-key-here    # 应用密钥（生产环境必须修改）
HOST=127.0.0.1                     # 监听地址
PORT=5000                          # 监听端口
DEBUG=True                         # 调试模式

# 数据库配置
DB_HOST=localhost                  # 数据库主机
DB_PORT=3306                       # 数据库端口
DB_NAME=k1989cms                   # 数据库名称
DB_USER=root                       # 数据库用户名
DB_PASSWORD=123456                 # 数据库密码

# Redis 配置
REDIS_URL=redis://localhost:6379/0  # Redis 连接地址

# JWT 配置
JWT_SECRET_KEY=your-jwt-secret      # JWT 密钥（生产环境必须修改）
JWT_ACCESS_TOKEN_EXPIRES=3600       # 访问令牌过期时间（秒）
JWT_REFRESH_TOKEN_EXPIRES=86400     # 刷新令牌过期时间（秒）
```

### ⚠️ 数据库配置注意事项

#### MySQL 存储引擎配置（重要）

**问题说明**：
- 系统使用 SQLAlchemy 定义了大量的外键约束来保证数据完整性
- MySQL 的 `MyISAM` 存储引擎**不支持外键约束，建议使用InnoDB引擎**

**检查当前配置**：
```bash
mysql -u root -p -e "SHOW VARIABLES LIKE 'default_storage_engine';"
```

**预期结果**：
```
+------------------------+--------+
| Variable_name          | Value  |
+------------------------+--------+
| default_storage_engine | InnoDB |
+------------------------+--------+
```

---

## 📊 监控与日志

### Prometheus 监控

系统内置 Prometheus 监控端点，用于采集性能指标：

```bash
curl http://localhost:5000/prometheus/metrics
```

### 日志配置

系统日志默认保存在 `logs/app.log`，支持按日期切割。

---

## 🔐 安全建议

1. **环境变量**：生产环境务必修改 `SECRET_KEY` 和数据库密码
2. **HTTPS**：启用 HTTPS 加密传输，防止数据泄露
3. **访问控制**：配置 Redis 访问密码，并使用防火墙限制 IP 访问
4. **API 限制**：在 Nginx 或代码层配置请求频率限制 (Rate Limiting)

---

## 🤝 贡献指南

我们欢迎任何形式的贡献！

### 贡献流程

1. **Fork** 本仓库
2. 创建功能分支：`git checkout -b feature/new-feature`
3. 提交更改：`git commit -am 'Add new feature'`
4. 推送到远程：`git push origin feature/new-feature`
5. 提交 **Pull Request**

### 代码规范

- 遵循 [PEP 8](https://www.python.org/dev/peps/pep-0008/) 代码规范
- 添加适当的注释和文档字符串
- 编写单元测试
- 确保所有测试通过

---

## 📄 许可证

本项目基于 **MIT** 许可证开源。

---

## 🧪 测试

项目使用 pytest 进行单元测试和集成测试。

### 运行测试

```bash
# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/test_auth_service.py

# 查看测试覆盖率
pytest --cov=app --cov-report=html
```

---

## 🚀 部署

### 生产环境部署

详细部署说明请参考 [运维文档](./docs/运维文档/部署运维文档.md)。

#### 1. 环境准备

```bash
# 安装系统依赖
sudo apt-get update
sudo apt-get install python3.8 python3-pip mysql-server redis-server nginx
```

#### 2. 安装项目依赖

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

#### 3. 配置环境变量

```bash
cp .env.example .env
vim .env
```

**生产环境重要配置**：
```bash
FLASK_ENV=production
SECRET_KEY=<生成强密钥>
JWT_SECRET_KEY=<生成强密钥>
DEBUG=False
```

#### 4. 初始化数据库

```bash
mysql -u root -p -e "CREATE DATABASE k1989cms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
flask full_setup
```

#### 5. 配置 Gunicorn

参考 `deploy/gunicorn.conf.py` 配置文件。

#### 6. 配置 Nginx

配置反向代理和静态文件服务。

---

## 📞 技术支持

### 项目地址

- **Gitee**: https://gitee.com/thomasblog/k1989cms
- **问题反馈**: https://gitee.com/thomasblog/k1989cms/issues

---

## 📚 文档

详细文档请查看 [docs](./docs) 目录：

- [产品需求文档](./docs/产品需求文档/)
- [技术设计文档](./docs/技术设计文档/)
- [开发文档](./docs/开发文档/)
- [运维文档](./docs/运维文档/)
- [代码规范](./docs/代码规范/)
- [操作手册](./docs/操作手册/)

---

## 📋 更新日志

### v2.3.3 (2026-04-28)

#### 修复问题

- **BUG-001**: 修复访客审批功能异常（API URL路径错误）
- **BUG-002**: 修复员工端创建访客邀请失败（允许无employee记录的用户创建邀请）
- **BUG-005**: 修复用户端门禁记录页面404错误（蓝图URL前缀配置）
- **BUG-007**: 修复通行记录页面加载失败（模板block名称和API字段名错误）
- **BUG-008**: 添加用户端导航菜单门禁记录入口

#### 功能优化

- 完善用户端导航菜单，添加门禁记录入口
- 优化 `login_required` 装饰器，支持识别包含 `/api/` 的路径
- 完善通行记录API字段映射

---

<div align="center">

**K1989CMS** - 让企业管理更智能、更高效！

Made with ❤️ by K1989 Team

</div>