Merge pull request 'Hotfix buttonerror' (#12) from hotfix-buttonerror into main

Reviewed-on: http://117.72.28.96:8765/Jacky/Hulumath-Web-Demo/pulls/12
This commit was merged in pull request #12.
This commit is contained in:
2026-08-08 18:52:17 +08:00
2 changed files with 463 additions and 4 deletions
+207 -4
View File
@@ -1,5 +1,208 @@
# Hulumath-Web-Demo
# 葫芦数学 · Hulu Math
Hulumath Web Demo Version
2026.8.8.15:58
nimaaaaaaaa
Flask 单体应用,提供网页端 + MathBTI 数学人格测试。一个 `app.py` 包含路由、API、数据库、大模型对接。
## 快速开始
```bash
# 1. 安装依赖
py -m pip install -r requirements.txt
# 2. 启动服务
py app.py
# 3. 浏览器访问
# http://127.0.0.1:5000/ → 自动跳转 /web(桌面端网页)
# http://127.0.0.1:5000/mathbti → MathBTI 数学人格测试
# http://127.0.0.1:5000/math_teen → 数学少年线独立剧本页
```
## 目录结构
```
Hulumath-Web-Demo/
├── app.py # Flask 后端主文件(路由 + API + SQLite + DeepSeek 对接)
├── requirements.txt # Python 依赖
├── vercel.json # Vercel 部署路由配置
├── templates/ # Jinja2 模板
│ ├── desktop.html # 网页端(桌面布局,引用 desktop.css + desktop.js
│ ├── mathbti.html # MathBTI 数学人格测试页(引用 mathbti.css + mathbti.js
│ └── math_teen.html # 数学少年线独立播放页(自包含,无外部 CSS/JS)
├── static/ # 静态资源
│ ├── css/
│ │ ├── desktop.css # 网页端样式
│ │ └── mathbti.css # MathBTI 页样式
│ ├── js/
│ │ ├── desktop.js # 网页端逻辑
│ │ └── mathbti.js # MathBTI 页逻辑
│ └── img/
│ └── mathematicians/ # 16 位数学人物肖像图片(0000~1111.png
├── data/ # 运行时数据(SQLite + 种子 JSON
│ ├── miniapp_v3.db # SQLite 数据库(用户、收藏、历史、知识卡片)
│ ├── seed_videos.json # 视频种子数据(54 条)
│ ├── seed_story.json # 葫芦侠行剧本数据(8 章 93 节点)
│ ├── seed_simulator.json # 数学专业模拟器剧本数据
│ ├── seed_mathbti.json # MathBTI 测试题目 + 16 种结果数据
│ └── seed_alumni.json # 数学校友访谈数据
├── docs/ # 内容创作文档(不是运行时依赖)
│ ├── 数学少年线_story.json # 数学少年线剧本数据(被 app.py 直接读取)
│ ├── novel/ # 小说原稿(葫芦侠行 8 章 txt + 设定)
│ ├── 产品文档/ # PRD、需求、开发记录
│ └── 会议记录/ # 需求评审纪要
└── scripts/ # 构建/导出脚本
├── build_mathbti.py
├── build_story.py
├── export_mathbti_doc.py
└── export_mathematicians_docx.py
```
## data/ 下的 JSON 文件说明
这些是应用运行时通过 API 读取的种子数据。`app.py` 在启动时根据路径加载它们。
| 文件 | 对应 API 路由 | 用途 | 数据结构概要 |
|------|-------------|------|-------------|
| `seed_videos.json` | `/api/videos` | 发现页视频列表 | 数组,每条含 id/title/author/discipline/video_url/duration_min 等 |
| `seed_story.json` | `/api/story` | 葫芦侠行互动剧本 | `{title, start_node, nodes: {node_id: {scene, character, choices: [{text, next, effects}]}}}` |
| `seed_simulator.json` | `/api/simulator` | 数学专业模拟器 | 同 story 结构,属性为 gpa/interest/skill |
| `seed_mathbti.json` | `/api/math_personality` | MathBTI 测试题+结果 | `{axes, clans, questions, results: {binary_code: {name, clan, stats5, ...}}}` |
| `seed_alumni.json` | `/api/alumni` | 数学校友访谈 | `{alumni: [{id, name, major, four_years: {nodes}}], meta}` |
> **注意**`数学少年线_story.json` 在 `docs/` 目录下,不在 `data/`。`app.py` 第 37 行直接指向 `docs/数学少年线_story.json`。
## docs/ 目录说明
`docs/` 是内容创作区,**不影响应用运行**(除了数学少年线剧本文件被直接读取)。
- `docs/novel/` — 葫芦侠行的小说原稿和设定文档(txt/md/docx
- `docs/产品文档/` — 产品需求文档、PRD、开发记录
- `docs/会议记录/` — 需求评审会议纪要
- `docs/数学少年线_story.json` — 数学少年线互动剧本数据,**被 app.py 直接读取**API `/api/story/math_teen` 返回此文件内容
### 在新项目中复用 docs/
如果你想在新项目里使用这些内容:
1. **互动剧本**:复制 `docs/数学少年线_story.json``data/seed_story.json` 到新项目,按 `{start_node, nodes: {id: {scene, character, choices}}}` 格式读取即可。前端用 JS 根据 `currentNode` 渲染 `scene` 文字和 `choices` 按钮即可。
2. **MathBTI 数据**:复制 `data/seed_mathbti.json`,包含 4 轴 12 题 + 16 种结果(含数学家小传、五维能力值、肖像图路径)。
3. **小说原稿**`docs/novel/第0X章.txt` 是纯文本,可直接用于任何文本展示场景。
## scripts/ 脚本说明
这些脚本用于**生成种子 JSON** 或**导出 Word 文档**。在项目根目录运行。
### build_mathbti.py — 生成 MathBTI 种子数据
将硬编码的题目、4 轴、4 族、16 种结果写入 `data/seed_mathbti.json`
```bash
py scripts/build_mathbti.py
# 输出: data/seed_mathbti.json
# 打印: OK: seed_mathbti.json generated, 16 results, 4 clans
```
> 脚本内用 Python dict 写死全部数据,`json.dump` 输出。修改题目/结果后重跑即可刷新 `data/seed_mathbti.json`。
### build_story.py — 生成葫芦侠行剧本
根据大纲原文构建 8 章 93 节点的互动剧情 JSON。
```bash
py scripts/build_story.py
# 输出路径写死在脚本末尾(第 1006 行),需手动改为你的项目路径
```
> 脚本提供 `N(node_id, scene, character, choices)` 和 `C(text, next, shuli, xiayi, xinzhi)` 两个辅助函数来逐节点构建故事。**输出路径硬编码在脚本中**,复制到新项目后需修改 `out_path`。
### export_mathbti_doc.py — 导出 Word 设定文档
将 16 位数学家设定导出为 Word 文档。
```bash
py scripts/export_mathbti_doc.py
# 输出: scripts/万理之城_设定圣经.docx
# 依赖: python-docx
```
### export_mathematicians_docx.py — 导出数学家小传 Word
将 16 位数学家小传 + 六维雷达数据导出为 Word。
```bash
py scripts/export_mathematicians_docx.py
# 输出路径硬编码在脚本第 528 行,需手动修改
# 依赖: python-docx
```
> **注意**:两个导出脚本的输出路径是硬编码的绝对路径,复制到新项目后需要修改脚本中的路径。
## 在新项目中使用
### 最小化移植(只要网页端)
1. 复制 `app.py``templates/desktop.html``static/css/desktop.css``static/js/desktop.js``data/` 目录
2. `py -m pip install flask requests`
3. `py app.py`
### 只要互动剧本引擎
剧本数据格式是通用的 JSON,任何语言都能读:
```python
import json
with open('seed_story.json', 'r', encoding='utf-8') as f:
story = json.load(f)
current_node = story['start_node'] # 例如 'ch1_start'
node = story['nodes'][current_node]
print(node['scene']) # 场景文字
print(node['character']) # 说话人
for choice in node.get('choices', []):
print(choice['text']) # 选项文字
print(choice['next']) # 下一节点 ID
print(choice.get('effects', {})) # 属性变化
```
前端渲染逻辑参考 `static/js/desktop.js` 中的 `loadStory()``rSN()` 函数。
### 只要 MathBTI 测试
1. 复制 `templates/mathbti.html``static/css/mathbti.css``static/js/mathbti.js``data/seed_mathbti.json`
2. MathBTI 前端是自包含的,只需能 fetch 到 `seed_mathbti.json` 即可运行
## 环境要求
- Python 3.12+
- Flask 3.x
- requestsDeepSeek AI 对话用)
- python-docx(仅 scripts/ 导出 Word 用)
## API 路由一览
| 路由 | 方法 | 说明 |
|------|------|------|
| `/` | GET | 重定向到 `/web` |
| `/web` | GET | 桌面端网页 |
| `/mathbti` | GET | MathBTI 测试页 |
| `/math_teen` | GET | 数学少年线独立剧本页 |
| `/api/videos` | GET | 视频列表 |
| `/api/knowledge` | GET | 知识卡片列表 |
| `/api/knowledge/<id>` | GET | 单个知识卡片详情 |
| `/api/story` | GET | 葫芦侠行剧本数据 |
| `/api/story/math_teen` | GET | 数学少年线剧本数据 |
| `/api/simulator` | GET | 模拟器剧本数据 |
| `/api/alumni` | GET | 校友访谈数据 |
| `/api/math_personality` | GET | MathBTI 题目+结果数据 |
| `/api/math_personality/calculate` | POST | 计算数学人格结果 |
| `/api/chat` | POST | AI 数学助教对话(对接 DeepSeek |
| `/api/favorites` | GET/POST/DELETE | 收藏管理 |
| `/api/history` | GET/POST | 观看历史 |
| `/api/user/profile` | GET/POST | 用户资料 |
| `/api/user/stats` | GET | 用户统计 |
| `/api/simulator/save` | GET/POST | 模拟器存档 |
| `/data/<filename>` | GET | 直接访问 data/ 下的 JSON 文件 |
+256
View File
@@ -0,0 +1,256 @@
# 新项目复用教程
> 假设你要开一个新仓库,做一个类似的"Python(原Flask)+ 互动剧本 + 人格测试"项目。本教程告诉你从这个老仓库拿什么、怎么拿、怎么改。
---
## 一、先搞清楚这个项目有哪几块可复用
| 模块 | 核心文件 | 能干嘛 |
|------|---------|--------|
| **Flask 后端骨架** | `app.py` | 路由、API、SQLite、gzip 压缩、静态缓存 |
| **互动剧本引擎** | `data/seed_story.json` + `desktop.js` 中的 story 相关函数 | 读取 JSON 剧本 → 前端渲染场景文字 + 选项按钮 + 属性变化 |
| **MathBTI 人格测试** | `data/seed_mathbti.json` + `templates/mathbti.html` + `mathbti.css/js` | 12 题测出 16 种结果,前端自包含可独立部署 |
| **卡片/抽卡系统** | `desktop.js` 中的 card/gacha 相关函数 | 16 张人物卡,读知识卡片攒抽卡次数,保底机制 |
| **内容构建脚本** | `scripts/build_*.py` | 用 Python dict 生成种子 JSON |
| **Word 导出脚本** | `scripts/export_*.py` | 把人物设定导出为 docx |
| **小说/设定原稿** | `docs/novel/*.txt` | 纯文本,可直接喂给任何文本处理流程 |
---
## 二、新项目规划建议
### 场景 A:做一个新互动剧本项目(最常见)
你只需要:**Flask 骨架 + 剧本引擎 + 剧本数据**。
```
new-project/
├── app.py # 从老项目复制,改掉路径和 API key
├── data/
│ └── my_story.json # 你的新剧本(照着老格式写)
├── templates/
│ └── index.html # 从 desktop.html 简化,或自己写
├── static/
│ ├── css/
│ └── js/
└── requirements.txt
```
### 场景 B:做一个人格/心理测试项目
你只需要:**MathBTI 前端 + 数据格式**。
```
new-project/
├── data/
│ └── seed_mytest.json # 你的测试题+结果(照 mathbti 格式写)
├── templates/
│ └── test.html # 从 mathbti.html 改
├── static/
│ ├── css/
│ └── js/
└── scripts/
└── build_mytest.py # 从 build_mathbti.py 改
```
### 场景 C:纯内容搬运(不要代码)
你只需要 `docs/``data/*.json` 里的文本和数据,用自己的技术栈重新实现前端。
---
## 三、逐步操作
### Step 1 — 拿 Flask 骨架
从老项目复制 `app.py`,然后改这几处:
```python
# 1. 改 DeepSeek API Key(第 83 行附近)
DEEPSEEK_API_KEY = "你的key"
# 2. 改数据路径(第 30~40 行)
# 删掉你不需要的路径变量,加上你自己的
DATA_DIR = os.path.join(BASE_DIR, "data").replace("\\", "/")
MY_STORY_PATH = os.path.join(DATA_DIR, "my_story.json").replace("\\", "/")
# 3. 改路由(第 258 行起)
# 删掉不需要的 @app.route,加上你自己的
@app.route("/")
def index():
return render_template("index.html")
# 4. 改 API 函数
# 照着 api_story() 的写法,load 你的 JSON 返回给前端
```
### Step 2 — 拿剧本引擎
**数据格式**(这是最关键的,任何语言都能读):
```json
{
"title": "我的剧本",
"start_node": "ch1_start",
"nodes": {
"ch1_start": {
"scene": "场景描述文字。用 \\n 换行。",
"character": "旁白",
"choices": [
{
"text": "选项A的文字",
"next": "ch1_choice_a",
"effects": { "str": 5 }
},
{
"text": "选项B的文字",
"next": "ch1_choice_b",
"effects": { "str": -3 }
}
]
},
"ch1_choice_a": {
"scene": "你选了A之后的故事...",
"character": "NPC",
"choices": [...]
}
}
}
```
**前端渲染逻辑**(从 `desktop.js` 提取的核心循环):
```javascript
let storyData = null;
let currentState = { currentNode: null, stats: {} };
async function loadStory() {
const r = await fetch('/api/story');
storyData = (await r.json()).data;
const start = storyData.start_node;
const node = storyData.nodes[start];
renderNode(start);
}
function renderNode(nodeId) {
const node = storyData.nodes[nodeId];
if (!node) return;
currentState.currentNode = nodeId;
localStorage.setItem('my_story_save', JSON.stringify(currentState));
// 渲染场景文字
document.getElementById('scene').textContent = node.scene || '';
// 渲染说话人
document.getElementById('character').textContent = node.character || '';
// 渲染选项按钮
const choicesEl = document.getElementById('choices');
choicesEl.innerHTML = '';
for (const choice of (node.choices || [])) {
const btn = document.createElement('button');
btn.textContent = choice.text;
btn.onclick = () => makeChoice(choice);
choicesEl.appendChild(btn);
}
// 没有选项 = 故事结束
if (!node.choices || node.choices.length === 0) {
choicesEl.innerHTML = '<div>故事结束</div>';
}
}
function makeChoice(choice) {
// 应用属性变化
if (choice.effects) {
for (const key in choice.effects) {
currentState.stats[key] = (currentState.stats[key] || 0) + choice.effects[key];
}
}
// 跳到下一节点
renderNode(choice.next);
}
```
**HTML 骨架**
```html
<div id="stats"></div>
<div id="character"></div>
<div id="scene"></div>
<div id="choices"></div>
```
### Step 3 — 拿剧本构建脚本
`scripts/build_story.py` 复制,它提供了两个辅助函数让你不用手写 JSON:
```python
# N(node_id, 场景文字, 说话人, 选项列表)
# C(选项文字, 下一节点ID, 属性变化...)
N("ch1_start", "你站在路口。", "旁白", [
C("往左走", "ch1_left", str=5),
C("往右走", "ch1_right", str=-2),
])
```
在脚本末尾改输出路径后运行 `py scripts/build_story.py` 就会生成 JSON 文件。
### Step 4 — 拿 MathBTI 测试
1. 复制 `templates/mathbti.html``static/css/mathbti.css``static/js/mathbti.js``data/seed_mathbti.json`
2. 前端逻辑在 `mathbti.js` 里,读 JSON → 逐题渲染 → 算 4 轴分数 → 映射到 16 种结果(4 位二进制)
3. 如果你要改题,直接改 `data/seed_mathbti.json`,或用 `scripts/build_mathbti.py` 重新生成
### Step 5 — 拿 Word 导出脚本
`scripts/export_*.py``python-docx` 把设定文字导出为 Word。复制后改两处:
- 脚本内的内容文字(硬编码在 Python dict/string 里)
- 输出路径(脚本末尾,硬编码的绝对路径)
```bash
py -m pip install python-docx
py scripts/export_mathbti_doc.py
```
---
## 四、内容文件怎么搬
| 你要什么 | 从哪拿 | 怎么用 |
|---------|-------|--------|
| 葫芦侠行剧本(8 章 93 节点) | `data/seed_story.json` | 直接当 JSON 读,格式见上 |
| 数学少年线剧本(85 节点) | `docs/数学少年线_story.json` | 同上格式,但属性名不同(shuli/xiayi/xinzhi |
| MathBTI 全套数据(4 轴 12 题 16 结果) | `data/seed_mathbti.json` | 前端 fetch 后渲染问卷 |
| 模拟器剧本 | `data/seed_simulator.json` | 同剧本格式,属性为 gpa/interest/skill |
| 校友访谈数据 | `data/seed_alumni.json` | 线性叙事,four_years.nodes 数组 |
| 16 位数学家肖像图 | `static/img/mathematicians/` | 文件名是 4 位二进制(0000~1111.png |
| 小说原稿 | `docs/novel/第0X章.txt` | 纯文本,随便用 |
| 人物设定文档 | `docs/novel/数学家小传_*.md` | Markdown,随便用 |
---
## 五、新项目清单
开新仓库时按这个清单走:
- [ ] 复制 `app.py`,改掉 API key、数据路径、路由
- [ ] 复制 `requirements.txt`,删掉不需要的包
- [ ]`data/` 目录,放你的 JSON 种子数据
- [ ]`templates/` 目录,放你的 HTML 模板
- [ ]`static/css/``static/js/`,放样式和脚本
- [ ] 如果有剧本,照 Step 2 的格式写 JSON,或用 `build_story.py` 生成
- [ ] 如果有 Word 导出需求,复制 `scripts/export_*.py` 改内容
- [ ] `py app.py` 启动,浏览器验证
---
## 六、常见坑
1. **旧 Flask 进程占端口**:改完代码后页面不更新?`Get-Process python | Stop-Process -Force` 杀掉旧进程再重启。
2. **剧本 JSON 里的中文**:文件编码必须是 UTF-8`json.load(f)` 时加 `encoding='utf-8'`
3. **build_story.py 输出路径**:脚本末尾的 `out_path` 是硬编码绝对路径,换机器必改。
4. **math_teen 故事文件位置**`数学少年线_story.json``docs/` 不在 `data/``app.py` 第 37 行直接指向 docs 目录。
5. **localStorage 存档**:前端用 localStorage 保存剧本进度,key 名在 JS 里定义(如 `mb_story_save`),换项目时注意别冲突。
6. **静态资源缓存**HTML 里引用 CSS/JS 带 `?v=数字` 版本号,改了前端代码后递增这个数字,否则浏览器用缓存。