# VisualizedGeometry

**Repository Path**: fufuproxy/purecanvas

## Basic Information

- **Project Name**: VisualizedGeometry
- **Description**: 可视化的中学平面几何解题辅助工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-08
- **Last Updated**: 2026-01-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Visualized Geometry

**Visualized Geometry** 是一个用于中学几何学习的可视化工具，支持用户通过图形界面绘制几何图形、查看属性、推导几何关系，并通过 AI 模型获取详细的几何推理过程。

### 🚀 项目目标

* **实时几何绘制与交互**：用户可以创建点、线段、圆等几何图形，实时查看几何属性（如长度、角度、面积）。
* **几何推理与属性计算**：通过 AI 模型，自动推导图形的几何关系并给出代数表达式。
* **高效的开发体验**：采用 **Vue 3 + TypeScript**，构建现代化前端架构，确保代码的可维护性和扩展性。

---

## 🛠️ 技术栈

* **前端框架**：Vue 3 + Composition API + TypeScript
* **状态管理**：Pinia（Vue 3 的官方状态管理库）
* **UI框架**：Tailwind CSS（响应式布局，简洁高效）
* **数学解析**：自定义安全的数学表达式解析器
* **AI 推理模块**：集成推理模型进行几何属性与关系推导（可调用后端 API）
* **构建工具**：Vite（快速开发与构建）

---

## 📂 项目结构

```
/src
  /components   # 存放 Vue 组件
  /core         # 核心功能：数据结构、计算逻辑
  /canvas       # 绘图引擎：Canvas 渲染与交互
  /ai           # AI 推理模块：模型请求与结果解析
  /store        # Pinia 状态管理
  /assets       # 静态资源，如图片、图标等
  /styles       # 样式文件（主要是 Tailwind 配置）
/public
  index.html    # 入口 HTML 文件
/tests
  unit-tests    # 单元测试目录
  integration-tests  # 集成测试目录
```

---

## ⚙️ 本地运行（前后端）

### 环境要求

- Node.js 18+（推荐 LTS）
- Python 3.11+（后端）
- Git

### 一键快速指引

1) 克隆仓库

```bash
git clone https://github.com/your-username/visualized-geometry.git
cd visualized-geometry
```

2) 前端依赖 & 开发服务器

```bash
npm install
npm run dev -- --host --port 5177   # 如端口占用可改成 5173
```

- 前端会把 `/api/*` 代理到 `http://127.0.0.1:8000`，并去掉 `/api` 前缀；确保后端在 8000 端口运行。
- 访问示例：http://localhost:5177

3) 后端依赖 & 服务

```bash
cd backend
python -m venv .venv
./.venv/Scripts/activate    # Windows
# 或 source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
```

4) 必要环境变量（前端放根目录 .env.local，后端放 backend/.env）

根目录 `.env.local` 示例（已与代理匹配）：

```env
VITE_API_BASE_URL=/api
VITE_API_BASE=/api
VITE_REASON_API_URL=/api/ai/ask
VITE_REASON_ALLOW_MOCK_FALLBACK=false
VITE_REASON_API_TIMEOUT_MS=15000
```

后端 `backend/.env` 可从 `backend/.env.example` 复制，至少需要：

```env
APP_ENV=dev
JWT_SECRET=change-me
CSRF_SECRET=change-me-csrf
DATABASE_URL=sqlite+aiosqlite:///./dev.db   # 本地默认即可
REDIS_URL=redis://localhost:6379/0          # 没有 Redis 也能跑，会自动回退内存
```

5) 构建（前端）

```bash
npm run build
```

6) 测试

- 前端：`npm run test -- --watch=false`
- 后端：

```bash
cd backend
pytest
```

### 常见问题

- 404 `/api/auth/login`：确认前端代理未被改动，后端在 8000 端口；前端请求应是 `/api/auth/login`，后端实际收到 `/auth/login`。
- CORS 报错：后端默认允许 `http://localhost:5177` 和 `http://127.0.0.1:5177`。若端口改为 5173，请在 `backend/.env` 的 `CORS_ORIGINS` 加上对应地址或直接使用默认值（config.py 已包含两组端口）。
- AI 调用失败：后端未启动或 `VITE_REASON_ALLOW_MOCK_FALLBACK=false` 时会直接报错；本地可改为 true 体验 mock。

---

## 💡 使用说明

* **创建几何图形**：在画布上点击，选择点、线段或圆进行创建。你也可以输入数学表达式来创建点和圆。
* **查看属性**：点击选中图形后，右侧属性面板将显示图形的属性（如坐标、长度、角度等）。
* **推导几何关系**：通过 AI 推理模块，你可以查看当前图形之间的几何关系（如平行、垂直、相等、共点等），并获取详细的推导过程和代数式表达。
* **保存与加载**：支持将当前场景保存到浏览器本地存储，方便后续加载与编辑。

---

## 🧪 测试

项目使用 **Vitest** 进行单元测试和集成测试。运行以下命令以执行测试：

```bash
npm run test

### AI 接口配置

支持两种配置方式（优先级从上到下）：

1) 直接提供完整接口地址

```
VITE_REASON_API_URL=https://your-host.example.com/api/reason
```

2) 基础地址 + 路径（路径默认 `/api/reason`）

```
VITE_REASON_API_BASE_URL=https://your-host.example.com
VITE_REASON_API_PATH=/api/reason
```

可选参数：

```
VITE_REASON_API_TIMEOUT_MS=8000
VITE_REASON_API_MAX_RETRY=1
VITE_REASON_ALLOW_MOCK_FALLBACK=true
```

在 UI 的 “AI 推理” 面板会显示当前模式徽标（仅 API / API+回退 / 仅 mock）和目标 endpoint，并提供“运行参数”区可临时调整回退开关与重试次数（仅作用当前会话）。

补充：

- 运行参数（回退开关、最大重试）会持久化到浏览器 localStorage，刷新后仍生效，可一键“恢复默认”（.env 中的值）。
- 面板提供“填充示例问题”与“追加示例场景”快捷按钮，便于快速体验。
- 失败时会显示接口状态码与返回体片段，成功时展示最近一次延迟（ms）。
```

### 测试目录

* **/tests/unit-tests**：单元测试
* **/tests/integration-tests**：集成测试

---

## 🌱 贡献

我们欢迎所有贡献！以下是如何贡献的步骤：

1. Fork 这个仓库
2. 创建一个新的功能分支（`git checkout -b feature-branch`）
3. 提交你的改动（`git commit -am 'Add new feature'`）
4. 推送到分支（`git push origin feature-branch`）
5. 提交 Pull Request

---

## 📝 开发日志

我们会为每个功能的开发过程生成日志文档，记录每次功能开发的思路、与 AI 的交互、代码实现以及测试验证。

开发日志将保存在 `docs/dev-log/` 目录，按功能模块进行分类。

---

## 📜 许可证

该项目使用 [MIT 许可证](LICENSE)，请随意使用和修改。

---

## 📣 致谢

感谢 [Vue 3](https://vuejs.org/)、[Tailwind CSS](https://tailwindcss.com/)、[KaTeX](https://katex.org/)、[Vite](https://vitejs.dev/)、[Pinia](https://pinia.vuejs.org/) 和其他开源工具的支持！

---

# ✨ 结语

这是一个为几何学习提供支持的工具，我们希望通过清晰、可交互的界面帮助学生更好地理解几何图形的属性和关系，提升他们的学习体验。感谢你对这个项目的关注与支持！

---