# doors

**Repository Path**: kdisi_admin/doors

## Basic Information

- **Project Name**: doors
- **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-03-22
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# doors

门禁管理与设备调试服务，包含 Go 后端和 React 前端。

项目当前覆盖的核心能力：

- 门禁设备管理、远程开门、在线状态统计
- 人员管理、群组管理、设备白名单同步
- 通行记录查询、导出、趋势统计、最新记录回看
- 异常上报落库与筛选
- 系统账号、角色、权限与操作日志
- `SK2001` 设备调试与未读记录同步

## 架构概览

- 后端：Go + Gin + Gorm + SQLite
- 前端：React + Vite + Tailwind CSS
- 数据存储：SQLite 双库
  - 配置库：`doors/config.db`
  - 运行库：`doors/runtime.db`

后端默认监听：

- 服务地址：`http://127.0.0.1:7666`
- 健康检查：`http://127.0.0.1:7666/healthz`

前端开发服务器默认监听：

- 开发地址：`http://127.0.0.1:8082`
- 代理规则：`/doors -> http://127.0.0.1:7666`

前端使用 `hash` 路由。构建后由后端直接托管，常用访问地址：

- 登录页：`http://127.0.0.1:7666/#/login`
- 首页：`http://127.0.0.1:7666/#/`
- 设备调试页：`http://127.0.0.1:7666/#/device/debug`

## 环境要求

- Go
- Node.js `^20.19.0 || >=22.12.0`
- npm `>=10`
- Python 3

## 快速开始

标准启动方式：

```bash
make restart
```

常用命令：

```bash
make build      # 构建前端和后端
make start      # 启动服务
make stop       # 停止服务
make restart    # 重建并重启
make status     # 查看服务状态和监听端口
make health     # 检查健康状态
make logs       # 查看最近日志
```

`make restart` 会执行这些动作：

1. 构建前端 `web/dist`
2. 构建后端二进制 `.run/doors`
3. 停止 8082 上的前端开发服务
4. 停止旧的后端进程
5. 启动新的后端进程并做健康检查

进程管理脚本见 [scripts/run_doors.py](scripts/run_doors.py)，默认运行文件位于 `.run/`：

- 二进制：`.run/doors`
- PID：`.run/doors.pid`
- 日志：`.run/doors.log`

## 配置

默认配置文件是 [config.yml](config.yml)：

```yaml
server:
  host: 0.0.0.0
  port: 7666
  mode: release

sqlite:
  configPath: ./doors/config.db
  runtimePath: ./doors/runtime.db
```

直接运行后端时，建议显式传入配置文件：

```bash
go build -o .run/doors .
./.run/doors -config ./config.yml
```

数据库初始化逻辑位于 [store/db.go](store/db.go)。服务启动时会自动执行 `AutoMigrate`，并兼容旧配置中的 `sqlite.path` 单库模式。

## 本地开发

后端单独启动：

```bash
go run . -config ./config.yml
```

前端单独启动：

```bash
cd web
npm install
npm run dev
```

前端开发模式会把 `/doors` API 请求代理到本地后端 `7666` 端口，配置见 [web/vite.config.js](web/vite.config.js)。

## 主要功能

### 设备与人员

- 门禁设备增删改查
- 远程开门
- 人员增删改查
- 群组管理与成员维护
- 人员同步到设备
- 从设备回读人员并保存到本地
- 群组批量同步到多台设备

### 通行记录

- 记录分页查询
- 记录导出
- 最新记录回看
- 个人通行历史查询
- 统计汇总与趋势图
- 记录详情查看
- 异常上报筛选

记录接口入口：

- 设备主动上报：`POST /doors/getrecord`
- 管理端查询：`GET /doors/record/list`

`/doors/getrecord` 对关键字段会做校验。非法请求或保存失败的上报会以异常记录形式写入库中，并带上 `errorReason`，方便在总览页和记录页统一排查。

### 系统账号与权限

- 登录接口：`POST /auth/login`
- 当前用户：`GET /doors/auth/me`
- 修改本人密码：`POST /doors/auth/password`
- 系统账号管理
- 角色管理
- 权限控制
- 操作日志

后端受保护接口使用 Bearer Token 鉴权，路由定义见 [router/auth.go](router/auth.go) 和 [router/router.go](router/router.go)。

### 设备调试

设备调试页面位于 `/#/device/debug`，当前 UI 同时展示 `FACE01` 和 `SK2001` 两种型号入口。

当前实际接入的是 `SK2001` UDP 调试能力，已支持：

- `0x94` 搜索控制器
- `0x96` 设置网络参数
- `0x8E` 设置事件参数
- `0x20` 查询控制器状态
- `0x30` 同步控制器时间
- `0xB0` 读取指定索引刷卡记录
- 基于 `recordIndex` 的未读记录同步

`FACE01` 目前仍保留为界面占位，尚未接入真实协议。

相关实现：

- 后端入口：[service/device_debug.go](service/device_debug.go)
- 协议类型：[service/sk2001_debug_types.go](service/sk2001_debug_types.go)
- UDP 传输：[service/sk2001_debug_transport.go](service/sk2001_debug_transport.go)
- 报文解析：[service/sk2001_debug_parse.go](service/sk2001_debug_parse.go)
- 记录同步：[service/sk2001_debug_records.go](service/sk2001_debug_records.go)
- 前端应用入口：[web/src/app/App.jsx](web/src/app/App.jsx)
- 前端主容器：[web/src/pages/accesscontrol/AccessControlPage.jsx](web/src/pages/accesscontrol/AccessControlPage.jsx)
- 前端调试页：[web/src/pages/accesscontrol/DeviceDebugPage.jsx](web/src/pages/accesscontrol/DeviceDebugPage.jsx)

## 目录结构

- [api](api)：HTTP 接口层
- [router](router)：路由注册与权限中间件
- [service](service)：业务逻辑
- [entity](entity)：数据模型
- [store](store)：SQLite 初始化与迁移
- [internal](internal)：公共工具、鉴权、响应封装
- [web](web)：前端页面与构建配置
- [scripts](scripts)：运行脚本

## 验证与排障

运行后端测试：

```bash
go test ./...
```

检查服务：

```bash
make status
make health
```

查看日志：

```bash
make logs
```

如果后端能启动但页面打不开，先确认 `web/dist/index.html` 是否存在；构建产物由 [main.go](main.go) 直接托管。