Archived
245 lines
8.2 KiB
Markdown
245 lines
8.2 KiB
Markdown
# 数学脑 · 开发需求文档
|
||
|
||
> 版本：MVP v6.0 | 更新日期：2023年
|
||
|
||
---
|
||
|
||
## 一、项目概述
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| **产品名** | 数学脑 |
|
||
| **代码名** | miniapp |
|
||
| **类型** | 移动端 SPA（单页应用）Web App |
|
||
| **架构** | Flask（Python 后端） + 原生 HTML/CSS/JS（前端） |
|
||
| **适应端** | iPhone 移动端（390px 宽度，100dvh，safe-area 适配） |
|
||
| **数据库** | SQLite |
|
||
| **AI 引擎** | DeepSeek Chat API |
|
||
|
||
---
|
||
|
||
## 二、技术栈
|
||
|
||
| 层级 | 技术 | 用途 |
|
||
|------|------|------|
|
||
| 后端框架 | Flask 3.x（Python） | 路由、API、数据库管理 |
|
||
| 数据库 | SQLite（SQLite3） | 视频数据、行为日志 |
|
||
| 前端 | 原生 HTML5 + CSS3 + Vanilla JS | SPA 页面切换、视觉小说引擎 |
|
||
| AI 集成 | DeepSeek Chat API | AI 数学助教对话 |
|
||
| 故事数据 | JSON（seed_story.json） | 8 章互动剧情节点树 |
|
||
| 视频数据 | JSON（seed_videos.json）→ SQLite | 54 条专业分区视频 |
|
||
| UI 风格 | 自制设计系统（CSS 变量 + flex/grid） | iPhone 式移动端适配 |
|
||
|
||
---
|
||
|
||
## 三、项目文件结构
|
||
|
||
```
|
||
miniapp/
|
||
├── app.py # Flask 后端主文件
|
||
├── data/
|
||
│ ├── seed_story.json # 8章93节点互动剧情数据
|
||
│ ├── seed_videos.json # 54条专业分区种子视频
|
||
│ ├── miniapp_v3.db # SQLite 数据库
|
||
│ ├── build_story.py # 剧情JSON生成脚本
|
||
│ └── novel/ # 原著小说txt（素材参考）
|
||
│ ├── 葫芦侠行（第一章）.txt
|
||
│ ├── 葫芦侠行（第二章）.txt
|
||
│ ├── ...
|
||
│ └── 框架.txt
|
||
├── static/
|
||
│ ├── css/
|
||
│ │ └── style.css # 全局样式（~1400行）
|
||
│ └── js/
|
||
│ └── app.js # 前端核心逻辑（~550行）
|
||
└── templates/
|
||
└── index.html # SPA 入口页面（~286行）
|
||
```
|
||
|
||
---
|
||
|
||
## 四、后端 API 接口
|
||
|
||
| 路径 | 方法 | 参数 | 返回 | 说明 |
|
||
|------|------|------|------|------|
|
||
| `/` | GET | — | HTML | 返回 SPA 首页 |
|
||
| `/api/videos` | GET | `module`(选填), `discipline`(选填) | `{code, data, disciplines}` | 视频列表 + 学科分类 |
|
||
| `/api/chat` | POST | `{message, student_id}` | `{code, reply, is_fallback}` | AI 对话（DeepSeek） |
|
||
| `/api/story` | GET | — | `{code, data}` | 获取互动剧情 JSON |
|
||
| `/api/log` | POST | `{user_id, action, target}` | `{code, msg}` | 行为日志记录 |
|
||
| `/api/students` | GET | — | `{code, data}` | 学生列表（B端预留） |
|
||
|
||
### 视频数据模型（videos 表）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | INTEGER PK | 自增 |
|
||
| title | TEXT NOT NULL | 视频标题 |
|
||
| module | TEXT | 所属模块（如"数人"） |
|
||
| sub_category | TEXT | 子分类 |
|
||
| discipline | TEXT | 学科（如"人工智能"） |
|
||
| discipline_icon | TEXT | 学科 emoji |
|
||
| video_url | TEXT | 外部视频链接 |
|
||
| description | TEXT | 视频简介 |
|
||
| duration_min | INTEGER | 时长（分钟） |
|
||
| author | TEXT | 作者（学院+姓名） |
|
||
|
||
---
|
||
|
||
## 五、前端架构
|
||
|
||
### 五层设计
|
||
|
||
```
|
||
┌─────────────────────────────────┐
|
||
│ index.html │ ← 结构层：DOM 容器
|
||
├─────────────────────────────────┤
|
||
│ style.css │ ← 表现层：响应式 + 动画
|
||
├─────────────────────────────────┤
|
||
│ app.js │ ← 逻辑层：路由 + 状态 + API
|
||
├─────────────────────────────────┤
|
||
│ seed_story.json │ ← 数据层：剧情节点树
|
||
├─────────────────────────────────┤
|
||
│ Flask API │ ← 服务层：数据库 + AI
|
||
└─────────────────────────────────┘
|
||
```
|
||
|
||
### 核心 JavaScript 模块
|
||
|
||
| 模块 | 函数 | 功能 |
|
||
|------|------|------|
|
||
| **全局状态** | `vnState`, `allVideos`, `storyData` | 应用级状态管理 |
|
||
| **模块切换** | `switchModule()`, `hideAllPanels()` | 四Tab页面切换、DOM显隐 |
|
||
| **发现页面** | `loadVideos()`, `renderVideoList()`, `renderDisciplineGrid()` | 视频流渲染、12学科网格 |
|
||
| **知识页面** | `renderShushuoFeed()`, `updateShushuoHero()` | 知识卡片Feed渲染 |
|
||
| **数学人生** | `navigateVN()`, `buildChoiceButtons()`, `applyVNStats()` | 视觉小说引擎核心 |
|
||
| **AI聊天** | `openChat()`, `sendMessage()`, `quickAsk()` | AI对话弹窗 |
|
||
| **数据持久化** | `saveVNState()`, `loadVNSave()`, `resetVNSave()` | localStorage存档 |
|
||
|
||
---
|
||
|
||
## 六、视觉小说引擎（VN Engine）
|
||
|
||
### 剧情数据模型
|
||
|
||
```json
|
||
{
|
||
"title": "葫芦侠行",
|
||
"start_node": "ch1_start",
|
||
"nodes": {
|
||
"节点ID": {
|
||
"scene": "场景描述文本",
|
||
"character": "说话角色",
|
||
"sprite": "角色立绘URL（可选）",
|
||
"choices": [
|
||
{
|
||
"text": "选项文本",
|
||
"next": "下一节点ID",
|
||
"effects": {
|
||
"shuli": 整数, // 数理根基变化
|
||
"xiayi": 整数, // 侠义声望变化
|
||
"xinzhi": 整数, // 心志韧性变化
|
||
"favorability": { // 角色好感度变化
|
||
"角色名": 整数
|
||
}
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 四属性系统
|
||
|
||
| 属性 | 键名 | 初始值 | 说明 |
|
||
|------|------|--------|------|
|
||
| 📐 数理根基 | `shuli` | 10 | 解锁高阶功法、影响论道胜负 |
|
||
| ⚔️ 侠义声望 | `xiayi` | 10 | 影响NPC态度、武林大会成绩 |
|
||
| 🧘 心志韧性 | `xinzhi` | 10 | 面对挫折的选择余地 |
|
||
| 💕 好感度 | `favorability` | 0（每人） | 触发专属剧情、影响结局 |
|
||
|
||
### 当前剧情规模
|
||
|
||
- **8 章**：初入江湖 → 西部教习 → 数理论道 → 脑学初创 → 报国之路 → 暗流涌动 → 陋室修炼 → 真相之门
|
||
- **93 个交互节点**
|
||
- **8+ 种结局**（真相守望、数理宗师、逍遥江湖、出海远航、悲情英雄、堕落之路、冤狱、虚无）
|
||
|
||
---
|
||
|
||
## 七、UI 设计系统
|
||
|
||
### 色彩系统
|
||
|
||
| 用途 | CSS 变量 | 色值 |
|
||
|------|----------|------|
|
||
| 发现页主色 | `--shuren` | `#F97316`（橙） |
|
||
| 知识页主色 | `--shushuo` | `#3B82F6`（蓝） |
|
||
| 数学人生主色 | `--shusi` | `#10B981`（绿） |
|
||
| 我的页主色 | `--mine` | `#8B5CF6`（紫） |
|
||
| 页面背景 | `--bg` | `#F2F3F7` |
|
||
| 卡片背景 | `--card` | `#FFFFFF` |
|
||
| 主文字 | `--text` | `#1E1E2E` |
|
||
|
||
### 布局规范
|
||
|
||
- **容器宽度**：`min(390px, 100vw)`（iPhone 比例）
|
||
- **桌面端**：居中显示 + `border-radius: 34px` + 阴影（模拟设备壳）
|
||
- **底部 TabBar**：白色半透明玻璃感 + `backdrop-filter: blur(18px)` + safe-area
|
||
- **顶部状态栏**：白色半透明 + 模糊 + `z-index: 50`
|
||
- **字体**：`-apple-system, PingFang SC, Microsoft YaHei`
|
||
|
||
---
|
||
|
||
## 八、部署与运行
|
||
|
||
### 启动命令
|
||
|
||
```powershell
|
||
cd C:\Users\Asus\Desktop\miniapp
|
||
py app.py
|
||
```
|
||
|
||
### 访问地址
|
||
|
||
```
|
||
http://127.0.0.1:5000/
|
||
```
|
||
|
||
### 环境要求
|
||
|
||
- Python 3.12+
|
||
- Flask
|
||
- requests
|
||
- python-docx（素材提取用，非运行时必需）
|
||
|
||
### 数据初始化
|
||
|
||
- 首次启动自动执行 `init_db()` + `load_seed_videos()`
|
||
- 54 条视频数据从 `seed_videos.json` 导入 SQLite
|
||
- 互动剧情从 `seed_story.json` 按需读取
|
||
- 旧数据库可通过改名绕过锁定问题
|
||
|
||
---
|
||
|
||
## 九、待开发需求
|
||
|
||
### P0（核心）
|
||
- [ ] 用户登录系统（OAuth/手机号）
|
||
- [ ] 视频上传与审核后台
|
||
- [ ] 互动剧情章节选择器（允许跳章/读档）
|
||
- [ ] 个人中心真实数据绑定（收藏、观看记录、剧情存档）
|
||
|
||
### P1（增强）
|
||
- [ ] 社交功能（评论、点赞、分享）
|
||
- [ ] 知识页数学小测验
|
||
- [ ] 视觉小说立绘 + 背景图系统
|
||
- [ ] 好感度可视化面板
|
||
- [ ] 多端适配（小程序版本）
|
||
|
||
### P2（远期）
|
||
- [ ] 微服务拆分
|
||
- [ ] 实时协作编辑（多人剧情共创）
|
||
- [ ] AI 生成剧情分支
|
||
- [ ] 数据分析看板（学生行为）
|