初始提交

2026-06-21 10:00:13 +08:00
commit 7a5dc32672
1441 changed files with 266348 additions and 0 deletions
@@ -0,0 +1,82 @@
+
+# FTC 票务系统
+
+[![支持 PR](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://makeapullrequest.com) [![使用 Lua](https://img.shields.io/badge/Made%20with-Lua-blue)]() [![CC:Tweaked](https://img.shields.io/badge/CC%3ATweaked-ComputerCraft-blue)](https://tweaked.cc/) [![Node.js 16+](https://img.shields.io/badge/Node.js-16%2B-green)](https://nodejs.org/) [![Open Source](https://img.shields.io/badge/Open%20Source-%E2%9D%A4-red)]() [![注释：英文](https://img.shields.io/badge/%E6%B3%A8%E9%87%8A-%E8%8B%B1%E6%96%87-blue)]()
+[![MIT 许可证](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+基于 CC:Tweaked 的票务解决方案：售票机与闸机，以及用于站点/线路/票价管理与票务事件日志的 Web 控制台。
+
+## 功能
+- 售票机：界面与语音引导、打印、软盘 TICKET 写入、售票统计上传
+- 闸机：软盘票检、红石控制、状态上传（进站/出站）
+- 控制台：管理站点/线路/票价、查看票务日志/事件、支持在区间中插入站点
+- 每次售票生成唯一票号；打印前检查纸量与出纸槽
+
+## 组件
+- `Lua/TicketMachine/startup.lua`：售票机主程序
+- `Lua/TicketMachine/gate.lua`：闸机主程序（进站/出站）
+- `Lua/TicketMachine/web/server.js`：后端 API
+- `Lua/TicketMachine/web/main.js`：前端主逻辑
+- `Lua/TicketMachine/web/app.js`：前端 API 封装
+- `Lua/TicketMachine/web/console.js`：控制台脚本
+
+## 环境要求
+- 安装 CC:Tweaked 模组的 Minecraft
+- 售票机需要监视器（可选）、音响、打印机与软盘驱动器
+- Web 控制台需要 Node.js 16+ 
+
+## 部署
+### 售票机
+- 编辑 `startup.lua` 中的 `CURRENT_STATION_CODE`
+- 摆放相关外设；如使用中心服务器，配置 `API_ENDPOINT.txt`
+
+### 闸机
+- 编辑 `gate.lua` 中 `CURRENT_STATION_CODE` 与 `GATE_TYPE`（0=进站，1=出站）
+- 摆放相关外设并接好门控红石
+
+### 控制台
+- 安装依赖并启动服务；可在 `web/data/*.json` 或界面中管理数据
+
+## 使用
+- 售票：选择站点、类型与次数，支付后进入打印检查，随后打印并写盘
+- 验票：插入软盘后自动校验并开门；多程票在扣次并更新后自动弹盘
+- 控制台：管理基本数据；在区间 Shift-点击可插入站点
+
+## 开发建议
+- 注释保持英文、简洁；Lua 外设调用建议加 `pcall`
+- Web API 路由在 `/api`，持久化文件位于 `web/data/*`
+
+## 贡献
+- 欢迎提 Issue 与 PR；改动尽量聚焦且最小化，遵循现有风格
+
+## 许可证
+- 使用 MIT 许可；详见 `LICENSE`
+
+## 安装与运行
+
+**前置条件**
+- 安装 `Node.js 16+`（推荐 18+）
+
+**安装依赖**
+- 在项目根目录执行：`npm install`
+
+**启动 Web 控制台**
+- 方式一（根目录）：`node web/server.js`
+- 方式二（进入子目录）：`cd web && node server.js`
+- 默认访问地址：`http://localhost:23333/`（可通过环境变量 `HOST`、`PORT` 覆盖）
+
+**首次配置**
+- 进入“系统设置”，设置 `API 地址`（默认同源 `/api`）。
+- 也可编辑 `web/data/config.json` 中的 `api_base`。
+
+**数据导入/导出**
+- 在控制台界面使用“导入数据 / 导出数据”按钮；导出文件名为 `ftc-ticket-admin-backup.json`。
+
+**设备部署（CC:Tweaked）**
+- 售票机：将 `Lua/TicketMachine/startup.lua` 置于电脑根目录作为开机自启，配置 `CURRENT_STATION_CODE`；按需摆放监视器、音响、打印机、软盘驱动器。
+- 闸机：将 `Lua/TicketMachine/gate.lua` 部署到闸机电脑，设置 `CURRENT_STATION_CODE` 与 `GATE_TYPE`（0=进站，1=出站），接好门控红石。
+- 若使用中心服务器：在设备侧写入 API 基址（如通过 `API_ENDPOINT.txt` 或程序内配置）。
+
+**常见问题**
+- 端口被占用：以 `PORT=8080 node web/server.js` 方式指定端口。
+- 跨域访问：后端已启用 CORS；如需跨源部署，请正确设置 `api_base`。