# 数学脑 · 开发需求文档

> 版本：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 生成剧情分支
- [ ] 数据分析看板（学生行为）