# zhikong

**Repository Path**: jasydong/zhikong

## Basic Information

- **Project Name**: zhikong
- **Description**: 智能设备控制台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智控 · 智能插座设备管理

智能插座设备管理的 Web 应用。首版聚焦**设备管理 CRUD**,采用可扩展的设备接入层(内置模拟适配器,预留真实硬件接入)。

## 技术栈

- **前端**: React 18 + Vite + TypeScript + Tailwind CSS + React Router
- **后端**: Node.js + Express + TypeScript + better-sqlite3 + Zod
- **共享**: npm workspaces monorepo,共享类型包 `@zhikong/shared`

## 目录结构

```
zhikong/
├─ shared/    # 前后端共享类型 (Device / DeviceStatus ...)
├─ server/    # Express + SQLite 后端
│  └─ src/
│     ├─ db/          # SQLite 初始化 + schema + seed
│     ├─ devices/     # repo / service / routes
│     └─ adapters/    # DeviceAdapter 接口 + Mock + Registry
└─ web/       # React + Vite 前端
   └─ src/{api,components,pages}
```

## 快速开始

```bash
# 安装依赖(monorepo 根)
npm install

# 一键启动前后端
npm run dev
#  后端  → http://localhost:4000
#  前端  → http://localhost:5173 (已代理 /api 到后端)
```

浏览器打开 http://localhost:5173 即可使用。首次启动会自动写入若干示例设备。

### 其他命令

```bash
npm run typecheck   # 全量类型检查
npm run build       # 构建全部
npm run start       # 运行构建后的后端
```

## 功能

- 设备增删改查(CRUD),SQLite 持久化,重启不丢数据
- 列表:搜索(名称/硬件号)、按房间筛选、在线状态徽章、每 15 秒轮询刷新
- 详情:当前功率/电压/电流读数(来自适配器)、设备完整信息
- 表单 Zod 校验;删除前二次确认;空/错/加载态完整
- 模拟适配器生成稳定但有波动的在线状态与功率读数,便于演示

## REST API

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/health` | 健康检查 |
| GET | `/api/devices` | 设备列表(附实时状态),支持 `?q=&room=&type=` |
| GET | `/api/devices/:id` | 设备详情 |
| POST | `/api/devices` | 创建 |
| PUT | `/api/devices/:id` | 更新 |
| DELETE | `/api/devices/:id` | 删除 |
| GET | `/api/devices/rooms` | 房间去重列表 |
| GET | `/api/devices/meta/types` | 设备类型元信息 |

## 设备接入层(可扩展)

`DeviceAdapter` 接口定义设备通信契约。首版仅实现 `getStatus`,内置 `MockDeviceAdapter`。
后续接入真实硬件(如 MQTT)只需:

1. 实现 `DeviceAdapter` 接口(`MqttDeviceAdapter`),补全 `getStatus`(及未来 `turnOn/turnOff/subscribe`)
2. 在 `adapterRegistry` 注册
3. 创建设备时设置 `adapter='mqtt'`

业务层(service/routes)无需改动。

## 范围说明(首版不含,架构已预留)

- 一键开关控制、WebSocket 实时推送、定时/场景、电量统计图表
- `DeviceAdapter` 已留 `turnOn/turnOff/subscribe` 占位,`devices` 表可加列扩展

## 配置

- 后端端口: `PORT` 环境变量(默认 `4000`)
- 前端代理目标: `web/vite.config.ts` 中 `server.proxy./api.target`(默认 `http://localhost:4000`)