Demo

2026-08-08 15:49:06 +08:00
parent e7dce1680a
commit 0a7207fa0e
76 changed files with 22779 additions and 0 deletions
@@ -0,0 +1,244 @@
+# 数学脑 · 开发需求文档
+
+> 版本：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 生成剧情分支
+- [ ] 数据分析看板（学生行为）