# QuerySystem

**Repository Path**: hosheil/query-system

## Basic Information

- **Project Name**: QuerySystem
- **Description**: 一个简单的刷网课以及校园跑的查询系统，都对接了第三方接口。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 用户自助查单系统 - 技术文档

## 1. 项目概述

本项目是一个**静态前端 + Serverless 后端**的订单/任务查询系统，部署于 Vercel 平台。

### 1.1 核心功能

| 功能模块 | 描述 |
|---------|------|
| **课程查单** | 用户输入账号查询课程订单状态、进度、备注等信息 |
| **校园跑查询** | 用户输入手机号查询乐动力跑步任务的执行状态和里程数据 |

### 1.2 技术栈

- **前端**: 原生 HTML5 + CSS3 + JavaScript (ES6+)
- **后端**: Vercel Serverless Functions (Node.js)
- **部署**: Vercel + 自定义域名
- **样式**: CSS Variables 实现多主题切换

---

## 2. 项目结构

```
query/
├── index.html              # 课程查单页面
├── run.html                # 校园跑查询页面
├── css/
│   ├── style.css           # 全局样式 + 主题变量
│   └── run.css             # 校园跑页面专用样式
├── js/
│   ├── main.js             # 课程查单前端逻辑
│   └── run.js              # 校园跑查询前端逻辑
├── api/
│   ├── query.js            # 课程查单 API 代理
│   ├── run.js              # 校园跑通用 API 代理（备用）
│   └── run/
│       └── query.js        # 校园跑查询 API（核心）
├── assets/
│   └── icons/
│       ├── logo.png        # 站点图标
│       └── logo.svg        # Logo 矢量图
├── server.js               # 本地开发服务器
├── vercel.json             # Vercel 部署配置
├── package.json            # 项目依赖
└── README.md        # 本文档
```

---

## 3. 前端架构

### 3.1 页面结构

#### index.html - 课程查单
- 输入下单账号和密码 → 调用 `/api/query` → 展示本站订单列表
- 支持查看详情弹窗
- 显示订单状态、进度、备注等

#### run.html - 校园跑查询
- 输入手机号 → 调用 `/api/run/query` → 展示任务卡片
- 显示：任务类型、学校、路线、跑前/跑后里程、账户余量

### 3.2 主题系统

使用 CSS Variables 实现三套主题：

| 主题 | data-theme | 描述 |
|------|------------|------|
| 浅色 | (默认) | 白色背景，蓝色主色调 |
| 暖橙 | warm | 米白背景，橙色主色调 |
| 深色 | dark | 深灰背景，青色主色调 |

**切换方式**：
- 点击右下角主题按钮选择
- 鼠标滚轮快速切换
- 自动保存到 localStorage

### 3.3 响应式设计

- 移动端适配 (max-width: 480px)
- 主题切换器尺寸自适应
- 卡片布局自动调整

---

## 4. 后端 API

### 4.1 课程查单 API

**路径**: `POST /api/query`

**请求体**:
```json
{
  "account": "用户账号",
  "password": "下单时的密码"
}
```

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "orderId": "本站订单ID",
      "productName": "商品名称",
      "courseName": "课程名称",
      "createTime": "提交时间",
      "status": "状态",
      "progress": "进度",
      "remarks": "备注"
    }
  ]
}
```

**实现**: `api/query.js`
- 只代理到本站后端 `POST /public/orders/query`
- 第三方货源调用由本站后端根据订单锁定的货源路由处理，浏览器不直连 XMWK

---

### 4.2 校园跑查询 API

**路径**: `POST /api/run/query`

**请求体**:
```json
{
  "phone": "手机号"
}
```

**响应**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "id": "任务ID",
      "phone": "手机号",
      "submit_time": "提交时间",
      "status": "completed|running|failed",
      "task_type": "每日任务",
      "school": "学校名称",
      "route": "路线名称",
      "mileage_before": 11.47,
      "mileage_after": 15.47,
      "mileage_done": 4.0,
      "balance": 86.0
    }
  ]
}
```

**实现**: `api/run/query.js`

#### 核心流程

```
用户输入手机号
       ↓
后端自动登录管理员账号
       ↓
调用 /getlog 获取所有日志
       ↓
按手机号过滤任务列表
       ↓
调用 /getdetail 获取每条任务详情
       ↓
解析 HTML → JSON
       ↓
返回结构化数据给前端
```

#### 安全设计

| 项目 | 说明 |
|------|------|
| 管理员账号 | 后端私密存储，不暴露给前端 |
| Cookie 缓存 | 1小时有效期，减少登录请求 |
| 环境变量 | 支持通过 `RUN_ADMIN_USERID` / `RUN_ADMIN_PASSWORD` 配置 |

#### HTML 解析规则

从 `/getdetail` 返回的 HTML 中提取：

```
学校:四川轻化工大学          → school
路线名称:轻工宜宾N1          → route
跑前里程:【11.47】           → mileage_before
跑后里程:【15.47】           → mileage_after
约定余量:【86.0】            → balance
执行成功                     → status: completed
```

---

## 5. 部署配置

### 5.1 Vercel 配置 (vercel.json)

```json
{
  "buildCommand": "",
  "outputDirectory": ".",
  "rewrites": [
    { "source": "/", "destination": "/index.html" },
    { "source": "/api/:path*", "destination": "/api/:path*" }
  ]
}
```

### 5.2 部署命令

```bash
# 生产环境部署
vercel --prod --yes

# 本地开发
node server.js
# 访问 http://localhost:8080
```

### 5.3 自定义域名

1. 在 Vercel Dashboard 添加域名
2. 配置 DNS A 记录指向 Vercel
3. 等待 SSL 证书自动签发

---

## 6. 本地开发

### 6.1 启动开发服务器

```bash
npm install
node server.js
```

### 6.2 访问地址

- 课程查单: http://localhost:8080/index.html
- 校园跑查询: http://localhost:8080/run.html

### 6.3 server.js 功能

本地开发服务器包含：
- 静态文件服务
- `/api/query` 代理
- `/api/run/query` 代理
- 管理员自动登录逻辑

---

## 7. 上游 API 边界

### 7.1 课程查单 API

| 项目 | 值 |
|------|-----|
| URL | `${WK_API_BASE_URL}/public/orders/query` |
| 方法 | POST |
| 参数 | `account`、`password` |

XMWK 的协议、密钥和货源账号只允许存在于统一 Java 后端，不能回退到浏览器或
Vercel 函数直接调用第三方接口。

### 7.2 乐动力 API

| 项目 | 值 |
|------|-----|
| Base URL | https://run.su7.uk |
| 必需 Header | `third-party-bypass: 20251112` |
| 认证方式 | Cookie (通过 /login_next 获取) |

**主要接口**:

| 接口 | 方法 | 说明 |
|------|------|------|
| /login_next | POST | 登录，获取 Cookie |
| /getlog | POST | 获取任务日志列表 |
| /getdetail | GET | 获取单条任务详情 (HTML) |
| /getbalance | GET | 查询余额 |
| /used_check | GET | 查询本月里程 |

---

## 8. 文件说明

### 8.1 前端文件

| 文件 | 作用 |
|------|------|
| `css/style.css` | 全局样式、主题变量、主题切换器、通用组件 |
| `css/run.css` | 校园跑页面专用样式、任务卡片、里程统计 |
| `js/main.js` | 课程查单逻辑、主题切换、Toast 通知 |
| `js/run.js` | 校园跑查询逻辑、任务卡片渲染 |

### 8.2 后端文件

| 文件 | 路径 | 作用 |
|------|------|------|
| `api/query.js` | /api/query | 课程查单代理 |
| `api/run/query.js` | /api/run/query | 校园跑查询（含管理员登录） |
| `api/run.js` | /api/run | 乐动力通用代理（备用） |

---

## 9. 注意事项

### 9.1 安全

- 管理员密码存储在后端，永不暴露给前端
- 建议使用 Vercel 环境变量存储敏感信息
- API 代理避免了前端直接调用第三方接口

### 9.2 性能

- Cookie 缓存减少重复登录
- 最多返回 5 条任务详情
- 最多查询 10 页日志

### 9.3 限制

- Serverless 冷启动会重置 Cookie 缓存
- 第三方 API 速率限制: 60秒/30次请求

---

## 10. 维护指南

### 10.1 更新管理员账号

修改 `api/run/query.js`:
```javascript
const ADMIN_CREDENTIALS = {
    userid: '新账号',
    password: '新密码'
};
```

或设置 Vercel 环境变量:
- `RUN_ADMIN_USERID`
- `RUN_ADMIN_PASSWORD`

### 10.2 修改主题颜色

编辑 `css/style.css` 中的 CSS 变量:
```css
:root {
    --accent-color: #3b82f6;  /* 主色调 */
    --accent-hover: #2563eb;  /* 悬停色 */
}
```

### 10.3 添加新功能

1. 创建新页面 (如 `new.html`)
2. 添加样式 (如 `css/new.css`)
3. 添加逻辑 (如 `js/new.js`)
4. 如需后端，创建 `api/new.js`

---

## 11. 版本历史

| 版本 | 日期 | 更新内容 |
|------|------|----------|
| 1.0 | 2025-11-25 | 初始版本：课程查单功能 |
| 1.1 | 2025-11-26 | 添加校园跑查询功能 |
| 1.2 | 2025-11-26 | 主题切换优化、移动端适配 |

---

*文档生成时间: 2025-11-26*