# k1989cmsv2

**Repository Path**: thomasblog/k1989cmsv2

## Basic Information

- **Project Name**: k1989cmsv2
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-13
- **Last Updated**: 2026-10-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# K1989CMS

> 本项目由 [gitee.com/thomasblog/k1989cms](https://gitee.com/thomasblog/k1989cms) 优化演进而来：在原项目基础上持续迭代——安全加固（XSS/CSP/越权/CSRF 专项治理）、模块重构与集成中心收敛、消费与门禁业务闭环完善、文档与测试体系化，形成当前版本。原项目与本项目均保留迭代演进记录。

企业一体化管理系统：覆盖**门禁通行、就餐消费、人事组织、访客管理、资产管理、第三方平台集成**六大业务线，面向公司/工厂的日常运营与管理场景，统一后台 + 移动端（访客/员工）双端使用。

## 界面预览

| 登录页 | 管理端仪表盘 |
| --- | --- |
| ![登录页](docs/screenshots/01-login.png) | ![管理端仪表盘](docs/screenshots/02-dashboard.png) |

| 访客管理台账 | 资产报表 |
| --- | --- |
| ![访客管理台账](docs/screenshots/03-visitor-list.png) | ![资产报表](docs/screenshots/04-asset-reports.png) |

| 移动端（首页/访客/订餐/我的） |
| --- |
| ![移动端](docs/screenshots/05-mobile.png) |

## 相对原项目（thomasblog/k1989cms）的主要变化

> 以下为 git diff（原仓库 HEAD `a04849d` → 当前 HEAD）实测数据：**1094 个文件变更，新增 229 / 删除 571 / 修改 282 / 重命名 12（+67,377 / −192,061 行）**。

### ① 移除本地依赖，全面转向平台适配器模式

| 移除项 | 规模 | 说明 |
| --- | --- | --- |
| `app/VideoSDK_Win64` / `app/SDK` | −200 | 第三方视频/人脸 SDK 二进制，不再随项目打包 |
| `agents/`（资产采集双端客户端） | 0 | Python + Go 双端资产采集代理：曾误整目录移除（−28），已整体恢复，生成/升级/命令/上报/接收/写入全链路验证通过 |
| `deploy/`（nginx/systemd/windows 脚本） | −9 | 旧部署方式，收敛为 Docker Compose |
| `app/communication/` | −12 | 旧消息模块，被集成中心替代 |
| 旧模板 | −101 | 全部重构重做 |

### ② 新增核心能力

| 新增块 | 规模 | 内容 |
| --- | --- | --- |
| 适配器体系 `services/adapters/` | 15 | 海康门禁/消费、钉钉/企微/飞书 IM、短信 + 统一工厂 |
| 消费业务 `services/consumption/` | 15+ | 账户/菜单/订单/补贴/对账 + 本地/海康/外部三平台模式 |
| 移动端 `user/mobile/` | 20+ | 首页/消费/订单/资产/库存/通知/统计/个人中心 |
| API v2 `routes/api/v2/` | 10 | 独立对外接口层（认证/用户/员工/部门/访客/资产/消费） |
| 安全组件 `utils/` | 8 | TOTP 2FA、PII 加密、数据权限、会话管理、统一错误页 |
| 资产模块 `services/asset/` | 7 | 分类/CRUD/统计/维修保养/调拨 |
| MCP Server `app/mcp/` | 9 | 全新 |
| 门禁联动 | 1 | 员工建档推人脸、离职自动撤权 |
| 验证/审计脚本 `tools/` | 27 | 各轮审计与回归脚本沉淀 |

### ③ 验证

当前测试套件 68 个测试文件（约 1079 个用例），运行方式见 [docs/测试文档.md](docs/测试文档.md)。

## 访问入口

默认本地地址 `http://127.0.0.1:8888`（生产部署后替换为实际域名，详见 [docs/部署文档.md](docs/部署文档.md)）：

| 端 | 入口 | 说明 |
| --- | --- | --- |
| 统一登录 | `/auth/login` | 各端统一登录入口（账号/密码 + TOTP 双因素） |
| 管理端 | `/admin/` | 管理后台仪表盘；访客台账 `/admin/visitors/`、资产报表 `/admin/assets/reports`、消费管理 `/admin/consumption` |
| 用户端（PC） | `/users/visitors/` | 员工访客中心：邀请管理、到访记录 |
| 移动端 | `/m/` | 员工移动端首页；访客审批 `/m/visitor-approvals`、访客邀请 `/m/visitor-invite`、消费 `/m/consumption`、订单 `/m/orders`、资产 `/m/assets`、库存 `/m/inventory`、通知 `/m/notifications`、个人中心 `/m/profile` |
| **访客签到** | `/visitors/public/arrival` | 访客到访确认页（扫码打开，无需登录） |
| 访客签到固定码 | `/visitors/public/arrival?front=1` | 前台/保安室张贴模式：显示签到入口二维码，打印张贴后访客扫码自助确认到访 |
| 访客中心 | `/visitors/public/center` | 访客自助中心（预约查询、通行记录） |
| API 文档 | `/api/docs` · `/admin/api-docs/swagger` | 对外 API 概览 / 内部 API 文档（V2、Agent、工具） |

## 核心能力

| 业务线 | 能力说明 |
| ------ | -------- |
| 门禁通行 | 员工建档自动下发人脸至门禁平台（适配器模式）、访客授权、离职/停用自动撤权、设备权限全局/按人下发 |
| 就餐消费 | 本地与平台两种消费模式、员工钱包、充值、统一交易流水与报表 |
| 人事组织 | 部门/员工管理、第三方 IM 通讯录同步（钉钉/企微/飞书适配器）、员工状态流转联动门禁 |
| 访客管理 | 预约、审批流、到访登记、人脸照片上传授权、移动端访客中心 |
| 资产管理 | 资产台账、出入库、维修保养计划、告警与统计报表（多维度可视化） |
| 集成中心 | 钉钉/企业微信/飞书集成（通讯录同步、消息通知回推、工作台免登）、外部平台接入统一适配层 |

另含：统一通知（站内/IM 多渠道）、审批流、MCP Server、TOTP 双因素认证、操作审计日志、等保测评材料包。

### MCP Server（AI 客户端对接）

系统内置 MCP Server，9 个业务工具（资产查询/统计、部门查询、消费查询、访客查询、待办查询、创建访客、创建通知等），支持三种传输方式：

| 方式 | 端口 | 配置示例 |
| --- | --- | --- |
| stdio | — | 编辑器（Trae/Cursor/Claude Desktop）本地连，填 command + args |
| Streamable HTTP | 8765 | 豆包工作 / WorkBuddy 等 HTTP 连接器，URL `http://host:8765/mcp` |
| SSE | 8766 | 旧版 SSE 客户端，URL `http://host:8766/sse` |

多用户：HTTP / SSE 客户端请求头加 `X-MCP-User-Id: <用户ID>` 即可按用户权限隔离数据。完整配置见 [docs/MCP说明.md](docs/MCP说明.md)。

### EDR 端点安全（资产 Agent 内置）

| 能力 | 说明 |
| --- | --- |
| 策略集中管理与热下发 | 全局 EDR 策略（可疑进程/扩展名/监控目录/哈希黑名单 + 检测开关），经 Agent 心跳通道版本比对增量下发，约 1 个心跳周期全网生效，无需重启 Agent |
| 威胁情报自动更新 | 对接 abuse.ch ThreatFox 免注册情报源（Celery 定时任务 30 分钟拉取，置信度过滤），与管理员手工配置独立存储互不覆盖，失败静默降级 |
| 行为检测 | 基线比对（进程/文件/连接）、SHA256 IOC 比对、持久化项监控（计划任务/服务/Run 键）、勒索诱饵文件、登录失败快检 |
| 远程处置 | 告警中心一键终止进程 / 隔离文件（服务端 + Agent 双重路径校验，拒绝系统目录与关键进程），全程审计 |
| 安全基线 | Agent 定期采集补丁新鲜度/密码策略/SMB 共享/防火墙配置，加权评分入库，资产详情与仪表盘展示 |

## 技术栈

- **后端**：Python 3.12 + Flask + SQLAlchemy（MySQL）+ Celery + Redis
- **前端**：Jinja2 服务端渲染 + Chart.js（管理端报表）+ 移动端适配（响应式/独立移动模板）
- **部署**：Windows 服务化（NSSM：web / celery worker / celery beat）为主线；WSGI（waitress / gunicorn）；Docker Compose 备选（当前存在已知阻断，见部署文档）
- **集成**：适配器模式统一对接海康（门禁/消费平台）、钉钉、企业微信、飞书

## 快速开始

### 本地开发（Windows）

```powershell
.\setup.ps1        # 环境检查 → 依赖 → 配置 → 建库 → 启动（python main.py）
```

### 本地开发（Linux / macOS）

```bash
./setup.sh
```

### 手动步骤

```bash
# 1. 准备虚拟环境与依赖
python -m venv .venv
.venv\Scripts\activate        # Windows；Linux/macOS 用 source .venv/bin/activate
pip install -r requirements.txt

# 2. 配置环境变量
cp .env.example .env          # 按需修改数据库/Redis/密钥等（.env 不入库）

# 3. 初始化数据库（建表 + 默认数据 + 管理员账号）
flask full_setup              # 初始管理员密码见 docs/admin_account_info.md（本地生成，不入库）

# 4. 启动开发服务器（自动拉起 Celery 子进程）
python main.py                # http://127.0.0.1:8888
```

> 入口分工：`main.py` = 开发服务器（自动管理 Celery）；`wsgi.py` = 生产 WSGI 入口（不拉起 Celery，需独立部署 Worker/Beat）。

### 生产部署（Windows 服务化，主线）

使用 [NSSM](https://nssm.cc/) 将 web / Celery Worker / Celery Beat 注册为系统服务（开机自启、崩溃自动拉起、日志轮转、依赖排序），完整命令与运维说明见 [docs/部署文档.md](docs/部署文档.md)。

### Docker Compose 部署（备选）

```bash
cp docs/.env.docker.example .env.docker
docker compose --env-file .env.docker up -d
```

> ⚠️ Docker 形态当前存在已知阻断（基础镜像与依赖版本冲突、Redis 密码校验冲突），修复前请勿使用，详见 [docs/部署文档.md](docs/部署文档.md) 第 8 章。

## 测试

```bash
# 运行全量测试（自动加载 .env 配置）
.venv\Scripts\python.exe -m pytest tests/ -q
```

测试覆盖：消费（本地/平台双模式）、门禁人脸同步（G1/G2/G3）、钱包交易记录、资产报表、集成适配器、安全（XSS/CSP/越权/CSRF）、TOTP 等。详见 [docs/测试文档.md](docs/测试文档.md)。

## 文档

| 文档 | 说明 |
| ---- | ---- |
| [文档中心](docs/文档中心.md) | 文档索引与阅读顺序 |
| [部署文档](docs/部署文档.md) | NSSM Windows 服务化部署（主线）+ 生产核对清单 + Docker 备选 |
| [测试文档](docs/测试文档.md) | 测试环境配置（5 个必需环境变量）与运行指南 |
| [安全等保](docs/安全等保.md) | 等保二级/三级测评材料包（含 EDR 安全能力映射） |
| [技术架构](docs/技术架构.md) | 系统架构、EDR 端到端链路、Celery 任务体系、数据模型 |
| [业务模块说明](docs/业务模块说明.md) | 12 模块全景、EDR 告警与远程处置、平台集成配置、兼容矩阵 |
| [MCP说明](docs/MCP说明.md) | MCP Server 使用说明（stdio / webhook 双通道） |

## 平台集成与联调状态

代码层全部采用**适配器模式**，配置凭证即可切换启用；下表为真实环境联调状态：

| 平台 | 状态 |
| ---- | ---- |
| 企业微信（通讯录同步 + 消息回推） | ✅ 已联调验证可行 |
| 飞书（通讯录/消息/免登） | 框架就绪，按文档配置凭证即可使用 |
| 钉钉（通讯录/工作通知/免登） | 框架就绪，待真实企业账号联调 |
| 海康门禁平台（人脸下发/设备权限） | 适配器已实现，待平台地址与账号联调 |
| 外部消费平台 | 对接桩已预留，待平台方接口文档（当前可用本地模式） |

联调配置见 [docs/业务模块说明.md](docs/业务模块说明.md)。

## 目录结构

```
app/            # 应用主体（路由/服务/模型/任务/适配器/工具）
config/         # 配置（开发/生产/测试）
templates/      # 管理端 + 用户端 + 移动端模板
static/         # JS/CSS/静态资源
tests/          # 测试套件
docs/           # 项目文档（7 篇 + 文档中心 + 截图/业务链路 HTML）
migrations/     # 数据库迁移
scripts/        # 运维脚本（备份/迁移/发布检查）
tools/          # 各轮验证脚本与审计追加脚本（留存）
uploads/        # 运行期上传数据（人脸照片等，不入库）
nginx/          # Nginx 配置
main.py         # 开发服务器入口
wsgi.py         # 生产 WSGI 入口
```

## 说明

- `.env`（密钥/数据库密码等）与 `uploads/`（业务数据）均不入库，由 `.gitignore` 保护；部署时以 `.env.example` 为模板自行配置。
- 数据库无本地默认值（必须显式配置 `DATABASE_URL`，MySQL 8）；生产环境所有密钥必须自行生成，禁止复用任何示例值或历史提交值（详见 `docs/部署文档.md` 密钥安全红线）。