# playweb

**Repository Path**: YMSK_2_0/playweb

## Basic Information

- **Project Name**: playweb
- **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-01-01
- **Last Updated**: 2026-01-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 自然语言驱动计算网站（playweb）

本项目实现了一个由自然语言驱动的 Web 计算应用，支持加法、乘法、平方三种运算，并通过 AI 对话自动完成：

- 根据对话内容自动切换页面（加法/乘法/平方）
- 自动填充中间区域输入框
- 自动调用后端 API 完成计算并展示结果

技术栈：

- 前端：Vue 3 + Vite + Vue Router + Pinia + Element Plus + Axios
- 后端：FastAPI + Pydantic + Uvicorn
- AI 集成：智谱 AI glm‑4.6（通过官方 Python SDK zai‑sdk）
- 工具链：uv（Python 包和运行管理）、npm（前端构建）

---

## 功能概览

- 左侧：菜单栏（加法 / 乘法 / 平方）
- 中间：当前运算功能页面
  - 加法：两个数字输入框 + 计算按钮
  - 乘法：两个数字输入框 + 计算按钮
  - 平方：一个数字输入框 + 计算按钮
  - 输入验证：非数字给出“请输入有效的数字”提示，阻止请求后端
- 右侧：AI 对话区
  - 支持自然语言输入，如：
    - `加法， 1+2`
    - `乘法， 3*4`
    - `平方， 5^2`
    - `3乘8.25`
    - `3和8.25相乘`
  - 自动：
    - 调用后端 AI 解析接口
    - 切换到对应功能页面
    - 预填中间输入框数值
    - 调用后端运算 API
    - 在对话区和中间页面展示结果

---

## 项目结构

后端和前端分别位于：

- 后端：`backend/`
  - `backend/main.py`：FastAPI 应用入口与路由
  - `backend/schemas.py`：Pydantic 模型与响应结构
  - `backend/ai_parser.py`：本地自然语言解析逻辑（正则）
  - `backend/ai_client.py`：glm‑4.6 客户端封装与自动回退逻辑
- 前端：`frontend/`
  - `frontend/index.html`
  - `frontend/vite.config.ts`：Vite 配置与 API 代理
  - `frontend/src/main.ts`：前端入口
  - `frontend/src/App.vue`：三栏布局与菜单
  - `frontend/src/router/index.ts`：路由配置
  - `frontend/src/store/calculator.ts`：Pinia 全局状态
  - `frontend/src/components/AIChat.vue`：AI 对话组件
  - `frontend/src/views/AddView.vue`：加法页面
  - `frontend/src/views/MultiplyView.vue`：乘法页面
  - `frontend/src/views/SquareView.vue`：平方页面
- 测试：`tests/`
  - `tests/test_math_endpoints.py`：三种运算 API 的单元测试
  - `tests/test_ai_parser.py`：自然语言解析单元测试
  - `tests/test_ai_endpoint_flow.py`：AI 解析到具体计算的端到端测试
  - `tests/conftest.py`：为测试配置项目根路径

---

## 后端设计

### FastAPI 应用

后端应用入口：`backend/main.py`

主要路由：

- `POST /api/add`
  - 请求体：`{"num1": number, "num2": number}`
  - 响应体：`{"result": number, "status": "success"}`
- `POST /api/multiply`
  - 请求体：`{"num1": number, "num2": number}`
  - 响应体：同上
- `POST /api/square`
  - 请求体：`{"num": number}`
  - 响应体：同上
- `POST /api/ai/parse`
  - 请求体：`{"text": string}`
  - 调用 `AIClient.interpret`，优先使用 glm‑4.6 解析，失败时回退到本地正则解析
  - 响应体：`AIParseResult`（见下）
- `POST /api/ai/route`
  - 请求体：`{"text": string}`
  - 只使用本地解析器 `parse_math_query`，不经过 glm‑4.6

全局响应数据模型定义在 `backend/schemas.py` 中：

- `ResultResponse`：运算结果
  - `result: float`
  - `status: "success"`
- `AIParseResult`：AI/本地解析结果
  - `status: "success" | "error"`
  - `operation: "add" | "multiply" | "square" | null`
  - `num1: float | null`
  - `num2: float | null`
  - `num: float | null`
  - `expression: str | null`
  - `message: str | null`（错误信息）

### 自然语言解析逻辑（本地正则）

文件：`backend/ai_parser.py`

- 功能：在不依赖大模型的情况下，通过正则表达式解析常见的数学表达式，包括：
  - 加法：
    - `加法， 1+2`
    - `1+2`
  - 乘法：
    - `乘法， 3*4`
    - `3x4` / `3×4`
    - `3乘8.25`
    - `3乘以8.25`
    - `3和8.25相乘`
    - `3与8.25相乘`
    - `3跟8.25相乘`
  - 平方：
    - `平方， 5^2`
    - `5^2`
    - `5的平方`

解析流程：

1. 预处理输入字符串（去空格、处理中文逗号）
2. 识别操作类型（加法/乘法/平方）
3. 使用正则提取数字
   - 加法：`(-?\d+(?:\.\d+)?)\+(-?\d+(?:\.\d+)?)`
   - 乘法：
     - 符号形式：`(-?\d+(?:\.\d+)?)[x\*×](-?\d+(?:\.\d+)?)`
     - 中文形式：`X乘Y`、`X乘以Y`、`X和Y相乘` 等
   - 平方：
     - `(-?\d+(?:\.\d+)?)\^2`
     - `(-?\d+(?:\.\d+)?)(?:的)?平方`
4. 生成 `AIParseResult`，失败时携带清晰的错误信息：
   - 无法识别运算类型
   - 无法从表达式中解析出足够的数字

### AIClient 与 glm‑4.6 集成

文件：`backend/ai_client.py`

职责：

- 封装智谱 AI 官方 SDK `ZhipuAiClient`
- 调用 glm‑4.6 模型解析用户输入
- 将模型输出转为本项目的 `AIParseResult`
- 出现网络错误、超时或输出异常时，自动回退到本地解析器 `parse_math_query`

初始化：

- API Key 读取顺序：
  - `ZAI_API_KEY` 或 `AI_API_KEY`
- 模型名称：
  - 环境变量 `GLM_MODEL`，默认 `"glm-4.6"`

文本预处理：

- 统一处理中文空格与标点
- 限制文本长度，控制资源消耗

Prompt 设计：

- AI 扮演“数学表达式解析助手”，输出严格 JSON 形式：

  ```jsonc
  {
    "operation": "add|multiply|square",
    "num1": number | null,
    "num2": number | null,
    "num": number | null,
    "expression": string
  }
  ```

- 示例中包含：
  - `"加法， 1+2"`
  - `"乘法， 3*4"`
  - `"平方， 5^2"`
  - `"3乘8.25"`
  - `"3和8.25相乘"`

调用方式：

- 使用官方 SDK 同步方法 `client.chat.completions.create`，通过 `anyio.to_thread.run_sync` 在后台线程中执行，并用 `anyio.fail_after` 控制超时。

回退机制：

- 只要 glm‑4.6 调用失败、超时、输出 JSON 不合法或字段不符合预期，就自动调用 `parse_math_query` 使用本地正则逻辑完成解析。

日志记录：

- 记录调用开始、原始输出、解析后的结构化结果
- 不记录敏感信息（如 API Key）

---

## 前端设计

前端工程位于 `frontend/`，使用 Vite + Vue 3。

### 构建与运行

`frontend/package.json` 中：

- `npm run dev`：开发模式
- `npm run build`：生产构建
- `npm run preview`：预览生产构建

Vite 开发服务器端口：5173  
代理配置：`frontend/vite.config.ts`

- 将 `/api/*` 请求代理到 `http://127.0.0.1:8000`（后端 FastAPI）

### 布局与导航

`frontend/src/App.vue`：

- 使用 Element Plus 的 `el-container` 实现三栏布局：
  - 左侧 `el-aside`：菜单（加法/乘法/平方）
  - 中间 `el-main`：`<router-view />`，展示当前功能页面
  - 右侧 `el-aside`：AI 对话组件 `AIChat`
- 左侧菜单与 `vue-router` 集成，切换路由：
  - `/add`
  - `/multiply`
  - `/square`

路由定义：`frontend/src/router/index.ts`

### 状态管理：Pinia

文件：`frontend/src/store/calculator.ts`

状态字段：

- `result`：最近一次计算结果
- `lastOperation`：最近一次运算类型
- `loading`：是否正在调用后端
- `error`：错误消息
- `presetAdd` / `presetMultiply` / `presetSquare`：
  - 用于从 AI 对话传递“预填输入值”到中间页面

关键方法：

- `calculateAdd(num1, num2)` → 调用 `/api/add`
- `calculateMultiply(num1, num2)` → 调用 `/api/multiply`
- `calculateSquare(num)` → 调用 `/api/square`
- `setAddPreset(num1, num2)` / `setMultiplyPreset(num1, num2)` / `setSquarePreset(num)`：
  - 为对应页面设置预填输入

### 功能页面

#### 加法页面（AddView）

文件：`frontend/src/views/AddView.vue`

- 两个输入框，通过 `v-model` 绑定 `num1Input` / `num2Input`
- 使用 `watch` 实时校验输入是否为有效数字
- `isValid` 计算属性控制按钮是否可点击
- `onCalculate` 调用 `store.calculateAdd`
- 监听 `store.presetAdd`，在有预设值时自动填入输入框并清空预设

#### 乘法页面（MultiplyView）

文件：`frontend/src/views/MultiplyView.vue`

- 与加法页面结构相同，调用 `store.calculateMultiply`
- 监听 `store.presetMultiply` 以支持 AI 预填

#### 平方页面（SquareView）

文件：`frontend/src/views/SquareView.vue`

- 单输入框，支持实时数字校验
- 调用 `store.calculateSquare`
- 监听 `store.presetSquare` 自动填入来自 AI 的数字

### AI 对话组件

文件：`frontend/src/components/AIChat.vue`

功能：

- 展示用户与系统的对话消息
- 输入多行文本，自然语言描述所需的计算
- 调用后端 AI 解析接口 `/api/ai/parse`
- 根据解析结果：
  - 设置 Pinia 中的预填数据 `preset*`
  - 调用相应的计算方法
  - 跳转到对应路由
  - 在对话中展示表达式与计算结果

处理流程：

1. 用户点击“发送” → 发送 `POST /api/ai/parse`，请求体为 `{ text }`
2. 后端返回 `AIParseResult`，包括 `operation`、`num1`、`num2` 或 `num`
3. 根据 `operation`：
   - `add` → 设置 `presetAdd`，调用 `calculateAdd`，路由跳转 `/add`
   - `multiply` → 设置 `presetMultiply`，调用 `calculateMultiply`，路由跳转 `/multiply`
   - `square` → 设置 `presetSquare`，调用 `calculateSquare`，路由跳转 `/square`
4. 在对话区域追加系统消息，格式类似：
   - `表达式 3乘8.25，结果为 24.705`

---

## 浮点精度说明

由于使用 IEEE 754 浮点数进行运算，对于某些小数，内存中的表示无法完全等于数学上的值，例如：

- `6.235` 的平方数学上是 `38.875225`
- 实际计算可能得到 `38.87522500000001`

这是浮点数表示造成的常见现象。本项目当前保留了 Python 的原始浮点结果，如果需要，可以在后端或前端增加统一的格式化或四舍五入逻辑控制显示精度。

---

## 运行与开发

### 环境准备

- Python 3.8+
- Node.js（建议 18+）
- 安装 uv（Python 包和运行管理工具）
- 安装前端依赖（在 `frontend/` 目录）
- 安装 zai‑sdk（智谱官方 Python SDK）

后端依赖可以通过 `uv` 和现有虚拟环境管理，前端依赖通过 `npm` 安装。

### 配置环境变量

在项目根目录下配置 `.env` 或系统环境变量，常用变量包括：

- `ZAI_API_KEY`：智谱 AI API Key
- `AI_API_KEY`：备用 API Key（如已使用，可保留）
- `GLM_MODEL`：glm 模型名称，默认 `glm-4.6`

### 启动后端

在项目根目录：

```bash
uv run uvicorn backend.main:app --reload --port 8000
```

访问 `http://127.0.0.1:8000/docs` 查看自动生成的 API 文档，并可在线调试 `/api/add`、`/api/multiply`、`/api/square`、`/api/ai/parse` 等接口。

### 启动前端

在 `frontend/` 目录：

```bash
npm install
npm run dev
```

默认访问地址：`http://localhost:5173/`

确保后端已经在 `8000` 端口运行，以便前端通过 Vite 代理访问 `/api/*`。

---

## 测试

后端测试使用 `pytest`，通过 `uv` 运行：

在项目根目录：

```bash
uv run pytest
```

当前测试内容：

- 基本运算接口：
  - `/api/add`、`/api/multiply`、`/api/square` 正确返回结果
- 自然语言解析：
  - `"加法， 1+2"` → add, num1=1, num2=2
  - `"乘法， 3*4"` → multiply, num1=3, num2=4
  - `"平方， 5^2"` → square, num=5
  - `"3乘8.25"` → multiply, num1=3.0, num2=8.25
  - `"3和8.25相乘"` → multiply, num1=3.0, num2=8.25
  - 非法表达如 `"3和相乘"` 能够返回 `status="error"` 且带有错误消息
- 端到端流程：
  - 调用 `/api/ai/parse` 解析表达式，再调用 `/api/add` 完成计算，确保链路正常

---

## 可扩展方向

本项目已实现一个完整的“自然语言 → 结构化解析 → 页面联动 → 后端计算”的闭环。后续可以在此基础上进行扩展：

- 支持更多运算类型：
  - 减法、除法、幂运算、求余等
  - 复杂表达式（如“(1+2)*3”、“3乘8.25再加2”）
- 丰富自然语言解析：
  - 加入更多中文表达变体
  - 利用 glm‑4.6 的函数调用能力，直接让模型返回结构化结果
- 增强结果格式化：
  - 为所有浮点结果设置统一精度或格式
  - 显示分步骤计算过程
- 前端体验优化：
  - 为计算结果增加历史记录
  - 支持键盘快捷操作与无障碍访问

该项目适合作为“自然语言驱动前后端协同 + 大模型集成”的教学示例或进一步扩展为更复杂的数学助手应用。