# hsping

**Repository Path**: calabchen/hsping

## Basic Information

- **Project Name**: hsping
- **Description**: 慧扫评系统前端
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-08
- **Last Updated**: 2025-11-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 慧扫评 (hsping)

这是一个用于答题卡（OMR）管理的前端 UI 与处理脚本仓库。仓库包含：

- Vue + DHTMLX Suite 前端（位于 `resources/js/`）
- OMR 生成与处理脚本（位于 `resources/code/`）
- 示例资源与帮助文档（若干 Markdown 文件，详见下方链接）

## 功能概览

- 系统布局与导航：`Layout`、`Toolbar`、`Sidebar`、`Tabbar`，支持主题切换（浅色/深色/自动）。
- 主要页面（板块）：`Home`、`Class`、`Test`、`About`，每个板块包含对应的 Grid、Toolbar、ContextMenu（实现位于 `resources/js/components/`）。
- 扫描（OMR）工作流：在 `Home` 选择测试 → 点击 `扫描答题卡` → 加载学生列表和可视化图片链接。
- 上传与处理：支持手动上传答题卡图片并调用后端接口 `/api/upload-omr` 和 `/api/process-omr` 执行识别。相关前端代码在 `resources/js/app.vue`。
- 子行（subRow）与预览：Grid 支持 subRow 可视化。为兼容当前安装的 `dhx-suite`，Expand 操作在可用时会在新标签页打开可视化图片（简单可靠）；代码中也实现了基于选择的 expand/collapse 逻辑与若干回退策略以提高兼容性。
- 班级管理：支持创建/编辑/删除班级与学生；学生展示使用 `DataView` 模块。
- 测验管理：编辑测验并可下载生成的答题卡图片（前端调用 `/api/generate-omr-card`）。
- OMR 识别器：`resources/code/process_omr.py` 会检测定位块、识别填涂气泡、计算题目与总分，并输出 JSON 与可视化 PNG 到 `results/`。

## 输出位置说明

- 结果 JSON：`results/results_*.json`（包含每位学生的识别详情与评分）。
- 可视化图片：`results/visualization_*.png`（答题卡上标注正确/错误答案与总分）。
- 说明：Web 服务通常把 `public/` 作为静态资源根目录。如果希望通过浏览器直接访问 `/results/...`，请确保把可视化图片放到 `public/results/`（复制或配置服务器）。示例：

```bash
mkdir -p public/results
cp results/visualization_*.png public/results/ || true
```

## 克隆与快速配置（macOS / zsh）

1) 克隆仓库并进入目录：

```bash
git clone <your-repo-url> hsping
cd hsping
```

2) 前端（Node.js / npm）

```bash
# 安装依赖
npm install

# 启动开发服务器（Vite）
npm run dev
```

3) 后端（Laravel） - 本地开发：

```bash
# 启动本地 PHP 开发服务器（可选）
php artisan serve
```

4) Python 虚拟环境与依赖（OMR 脚本）

```bash
# 在项目根创建并激活虚拟环境（推荐名称 .venv）
python3 -m venv .venv
source .venv/bin/activate

# 升级 pip 并安装 requirements（脚本依赖位于 resources/code/requirements.txt）
python3 -m pip install --upgrade pip
pip install -r resources/code/requirements.txt
```

5) 快速运行 OMR 处理（示例）：

```bash
python3 resources/code/process_omr.py \
	--image omr_output/omr_card_*.png \
	--key resources/asset/2022年12月02日小测_key.json
```

(更多快速测试命令见 `docs/OMR_GUIDE.md`)

## 常用开发命令

- 启动前端： `npm run dev`
- 启动后端（本地）： `php artisan serve`
- 运行 OMR 处理： `python3 resources/code/process_omr.py ...`

## 重要说明 / 已知行为

- `dhx-suite` 版本在 `package.json` 中指定（示例：`dhx-suite: ^9.2.1`）。部分 `dhx` 版本可能未包含 `expand`/`collapse` API，为兼容性考虑，前端实现了选择驱动的 expand/collapse 与简单回退策略（在可用时会在新标签页打开可视化图片以确保可靠预览）。
- 如果你需要在 Grid 内联显示 subRow 可视化，请确保 `public/results/` 下有可访问的 PNG，然后我可以把扩展逻辑改为内联渲染（而不是打开新标签）。

## 重要文件（参考）

- 前端入口： `resources/js/app.vue`
- UI 组件： `resources/js/components/boardHome.js`、`boardClass.js`、`boardTest.js`
- OMR 脚本： `resources/code/process_omr.py`、`omr_circle_generator.py`、`omr_rect_generator.py`
- 说明文档（合并版）： `docs/OMR_GUIDE.md`（包含快速命令、测试流程与详细说明）。

---

如果你希望我把其它 Markdown 文档也一并翻译为简体中文（例如 `PROCESS_OMR_GUIDE.md`、`QUICK_TEST.md`），或把 `results/visualization_*.png` 自动复制到 `public/results/`，请告诉我我帮你执行。谢谢！