# 葫芦数学生产版重构方案 > 文档版本：v0.2 评审稿（核心决策更新版） > 文档状态：部分决策已确认 > 更新日期：2026-08-08 > 适用范围：Web 生产版，兼顾后续微信小程序 > 核心目标：把当前演示系统升级为可运营、可扩展、可监控、可稳定发布的线上产品 --- ## 1. 执行摘要 当前仓库已经验证了 MathBTI、数学人物卡、知识内容、互动剧情、数学工具等产品表达，但工程形态仍属于内部 Demo： - 后端路由、数据库和 AI 调用集中在单个 Flask 文件。 - 前端页面、状态和业务规则集中在单个 JavaScript 文件。 - SQLite 同时承载结构、种子数据和运行时用户数据。 - 用户成长、抽卡和剧情状态大量依赖 `localStorage`。 - 缺少正式账号、权限、数据库迁移、测试、监控和可靠回滚。 - 产品入口较多，但缺少明确的每日使用主线。 生产版不继续在当前单文件结构上堆叠功能，但也不另建一套长期并行的新旧系统。项目采用当前仓库内的分阶段重构：先建立 Django 生产骨架和兼容层，再按垂直业务链路替换 Flask 路由、SQLite 和旧前端模块，完成一个阶段即删除对应旧实现。 生产版的产品主线定义为： > 数学人生是核心体验。MathBTI 帮助用户发现自己的数学人格，四条旗舰人生线让用户体验不同的数学精神，人物 Skill 包持续扩展真实而多样的人生选择；Contest、LaTeX 和内容探索既可独立使用，也服务于人生节点与长期成长。 本轮已经确认的产品方向： | 决策项 | 当前选择 | |---|---| | 首发用户 | 全年龄数学兴趣用户 | | 核心产品 | 数学人生宇宙 | | 身份入口 | MathBTI 数学人格 | | 旗舰内容 | 信仰者、传播者、应用者、直觉者四条独立人生线 | | 扩展内容 | 人物 Skill 人生包 | | 首发旗舰线 | 信仰者数学少年线 | | 体验长度 | 旗舰主线约 2 小时；人物 Skill 约 20 分钟 | | 主要互动 | 隐藏信息选择、资源经营、人物羁绊、数学挑战 | | 日常留存行为 | 每日 Contest | | Contest 方向 | 实时 1v1 优先， 每日异步赛同期交付或紧随其后 | | 首发账号 | 邀请码注册 | | 一级导航 | 首页、数学人生、比赛、工具箱、探索发现、我的 | | LaTeX 位置 | 工具箱核心子模块 | | 后端 | Django 模块化单体 | | 数据库 | MySQL 8.0.35 | | 实施方式 | 当前仓库内分阶段重构，不长期并行维护新旧系统 | | 主界面 | 加强行动引导，减少纯功能陈列 | | 工具方向 | LaTeX 手写、编辑与教学升级为重点模块 | | 用户中心 | 可注册、可沉淀、可管理 | 评审建议： - 统一剧情引擎与信仰者数学少年线作为生产版第一阶段核心功能。 - MathBTI 不是孤立测试，而是进入数学人生宇宙的身份仪式。 - 人物 Skill 包使用统一结构持续生产，首发至少提供可验证的样板。 - 首版 Contest 以实时 `1v1` 为主推体验，每日异步赛与其同期交付或紧随其后。 - 实时范围严格限制为单一匹配模式，不在首版扩展房间赛、淘汰赛和观战。 - 全年龄用户必须通过水平分层、兴趣选择和个性化首页解决体验冲突。 - 后端确定改为 Django 模块化单体，数据库确定改为 MySQL 8.0.35。 - 在当前仓库中实施分阶段重构；每个新模块通过验收后替换并删除对应旧代码。 --- ## 2. 本次评审目标 本轮已经确认： 1. “数学人生宇宙”是生产版核心产品。 2. MathBTI、四条旗舰线、人物 Skill 包和跨剧本成长属于同一系统。 3. 信仰者数学少年线是首发旗舰内容。 4. Contest 以实时多人玩法优先，异步赛同期交付或紧随其后。 5. 六个一级模块为：首页、数学人生、比赛、工具箱、探索发现、我的。 6. LaTeX Lab 放入工具箱，并作为工具箱重点能力。 7. 后端采用 Django 模块化单体。 8. 数据库采用 MySQL 8.0.35。 9. 当前仓库进行分阶段重构，不长期并行维护两套产品系统。 本次后续评审需要形成以下结论： 1. 实时 `1v1` 与每日异步赛是否必须在同一次公开发布中交付。 2. 信仰者主线的章节范围与首轮试玩范围。 3. 首批人物 Skill、邀请注册方式和试点规模。 4. 确认详细交付阶段和生产验收标准。 本次评审不解决具体视觉稿、所有题目内容和每个接口字段。上述内容应在方案通过后进入详细 PRD 与技术设计阶段。 --- ## 3. 产品定位 ### 3.1 一句话定义 葫芦数学是一个面向全年龄数学兴趣用户的“数学人生宇宙”：用户发现自己的数学人格，进入不同数学精神对应的人生故事，在选择、关系、挑战和成长中体验数学如何塑造一个人。 ### 3.2 核心价值 - 不把数学简化为刷题和知识点，而是呈现为人生选择、精神气质和理解世界的方式。 - 用 MathBTI 建立身份认同，让用户获得“这是一种属于我的数学人生”的入口。 - 用四条旗舰人生线提供深度沉浸，用人物 Skill 包持续扩展真实人生样本。 - 用短时 Contest 形成明确、可重复的每日行为。 - 用 LaTeX Lab 降低数学表达门槛，并成为剧情中的真实能力。 - 用个人档案记录跨剧本成长，而不是只展示静态信息。 ### 3.3 产品核心循环 ```text 完成 MathBTI 或选择感兴趣的数学人生 ↓ 进入旗舰主线或人物 Skill 包 ↓ 在不完整信息下做人生选择 ↓ 管理能力、时间、关系与机会 ↓ 通过 Contest、LaTeX 或推理挑战改变部分结果 ↓ 获得结局、数学人物卡和跨剧本成长 ↓ 继续另一条人生，或通过每日 Contest 回访 ``` ### 3.4 非目标 首个生产版本不做： - 开放式论坛、陌生人私信和用户发帖。 - 现金奖励、充值抽卡和博彩式机制。 - 四条旗舰人生线同时完整上线。 - 实时比赛的房间赛、多人混战、淘汰赛、观战等复杂形态。 - 复杂推荐算法。 - 同时重制全部历史剧情。 - 微服务拆分和 Kubernetes 集群。 --- ## 4. 用户分层 “全年龄”不能理解为所有用户看到同一套题和同一个排行榜。系统首次使用时应建立轻量用户画像。 ### 4.1 首次引导 首次进入需要完成或跳过以下选择： | 维度 | 可选项 | |---|---| | 当前阶段 | 小学、初中、高中、大学、兴趣玩家 | | 数学水平 | 入门、普通、进阶 | | 兴趣方向 | 口算、概率、几何、逻辑、数学史、数学应用、LaTeX | | 使用目标 | 每日挑战、学习表达、探索内容、体验剧情 | 涉及未成年人时，只收集实现分层所需的最少信息，不要求真实学校、真实年龄和真实姓名。 ### 4.2 赛道分层 首发建议设置： - 入门赛道：基础运算、直观逻辑和轻量数学常识。 - 标准赛道：初高中通用数学思维和速度挑战。 - 进阶赛道：高阶逻辑、概率、估算和大学基础数学。 - Open 赛道：不限制用户水平，用于主题活动。 用户可以自主切换练习赛道，但正式排行榜应按赛道分别计算。 --- ## 5. 信息架构 ### 5.1 一级导航 ```text 首页 数学人生 比赛 工具箱 探索发现 我的 ``` 建议保持左侧导航，移动端折叠为底部导航或抽屉导航。 ### 5.2 导航结构 #### 首页 - 继续当前数学人生 - MathBTI 身份入口 - 四大主题与人物 Skill 推荐 - 当前人生属性、关系和关键选择摘要 - 今日挑战 - 数学精灵与跨剧本成长概览 #### 数学人生 - MathBTI：发现数学人格 - 四大旗舰主题 - 信仰者：数学少年线 - 传播者：待开发 - 应用者：待开发 - 直觉者：待开发 - 人物 Skill 人生包 - 葫芦侠行等特别篇 - 我的存档、结局与人生图鉴 #### 比赛 - 实时竞技 - 今日挑战 - 单人闯关 - 主题周赛 - 排行榜 - 比赛历史 #### 工具箱 - LaTeX Lab - 手写公式 - LaTeX 编辑器 - 模板与符号库 - 分级课程 - 表达挑战 - 我的公式 - 口算练习 - 函数绘图 - 数学符号查询 - 后续数学实验工具 #### 探索发现 - 视频 - 知识卡片 - 数学人物 - 主题筛选 #### 我的 - 个人资料 - MathBTI 身份与数学人格 - 人生存档、结局和关键选择 - 五维能力与人物关系 - 段位和 Rating - 比赛记录 - 错题记录 - 课程进度 - 收藏与历史 - 数学人物卡册 - 账号与安全 ### 5.3 管理后台 管理后台独立使用 `/admin`，不出现在普通用户导航中。 --- ## 6. 首页体验方案 ### 6.1 设计原则 当前首页主要承担功能陈列。生产版首页应优先回答三个问题： 1. 我正在经历哪一段数学人生？ 2. 我现在面对什么选择，为什么值得继续？ 3. 今天还有什么短时行动可以推动成长？ ### 6.2 首页优先级 从上到下建议为： 1. 继续数学人生主卡片，展示当前章节、人物和未解决事件。 2. 新用户显示 MathBTI 或“选择第一条人生”入口。 3. 四大主题和人物 Skill 的个性化推荐。 4. 今日比赛与工具箱中的 LaTeX 表达挑战。 5. 数学精灵、五维能力、卡册和结局图鉴。 6. 个性化内容推荐。 ### 6.3 新用户三步任务 ```text 完成 MathBTI 或选择一条人生 ↓ 完成第一个关键选择 ↓ 看到选择带来的属性、关系或机会变化 ``` 完成后再逐步展示比赛、工具箱、抽卡和完整图鉴，避免首次进入时同时暴露全部功能。 --- ### 6.4 数学人生核心产品方案 #### 6.4.1 产品结构 数学人生不是导航中的一个普通内容栏目，而是连接产品其他能力的核心系统。 ```text 身份层：MathBTI 数学人格 ↓ 旗舰体验层：信仰者 / 传播者 / 应用者 / 直觉者 ↓ 扩展体验层：人物 Skill 人生包 / 特别篇 ↓ 互动层：隐藏信息选择 / 资源经营 / 人物羁绊 / 数学挑战 ↓ 成长层：五维能力 / 数学精灵 / 卡牌 / 结局图鉴 ``` #### 6.4.2 MathBTI 的角色 MathBTI 应从独立测试升级为数学人生的身份入口： - 给出用户的数学人格与代表数学家。 - 推荐最适合开始的旗舰人生线，但不锁定其他路线。 - 生成初始五维能力倾向。 - 赠送第一张人物卡，并建立数学精灵。 - 测试结果影响部分开场对白、推荐顺序和隐藏选项。 - 用户可以自由重测，但历史身份和人生记录不应被覆盖。 #### 6.4.3 四条旗舰人生线 四条路线彼此独立，每条都是约 2 小时、可分章节完成、可重复体验的完整人生线。 | 路线 | 核心精神 | 代表人物 | 体验重点 | |---|---|---|---| | 信仰者 | 为真理本身坚持数学 | 高斯、祖冲之、欧拉、诺特 | 求学、证明、挫折、科研与信念 | | 传播者 | 让更多人理解数学 | 斐波那契、华罗庚、伽罗瓦、Ada | 表达、教育、传播、公众选择 | | 应用者 | 用数学改变现实 | 秦九韶、牛顿、图灵、冯·诺依曼 | 建模、工程、职业、伦理与影响 | | 直觉者 | 看见隐藏结构与联系 | 希帕提娅、赵爽、庞加莱、凯瑟琳 | 洞察、跨界、创造、孤独与突破 | 首发完整打磨“信仰者数学少年线”。另外三条路线在界面中可以展示世界观与开发状态，但不应使用空白大卡占据核心空间；可通过序章、人物预告或短 Skill 提前建立期待。 #### 6.4.4 人物 Skill 人生包 人物 Skill 是围绕一位真实人物、数学家或校友制作的约 20 分钟短篇人生体验。 每个 Skill 包应包含： - 明确的人物身份和真实时代或职业背景。 - 4 至 6 个关键人生节点。 - 至少一次信息不完整的高风险选择。 - 一组有限资源，例如时间、精力、收入、声望或关系。 - 2 至 4 位关键人物关系。 - 至少一个与人物经历相关的数学挑战。 - 2 个以上有意义的结局或人生评价。 - 事实来源、虚构范围和创作者信息。 Skill 包既是内容形态，也是未来的内容生产标准。校友访谈、数学家传记和职业故事都可以进入同一生产管线。 #### 6.4.5 四类核心互动 ##### 隐藏信息选择 - 选择前只提供角色当时能够知道的信息。 - 不直接展示所有属性收益和最优答案。 - 允许通过人物关系、探索和数学能力获得额外情报。 - 结果可以延迟发生，避免每次选择立即结算成数值题。 ##### 属性与资源经营 建议区分两层： - 跨剧本五维能力：眼光、人文、侦探、建模、联结。 - 剧本内资源：时间、精力、金钱、学术进度、声望等。 剧本内资源随一段人生结束而结算；五维能力进入用户长期档案。 ##### 人物关系 - 关系不是单一好感度，应允许信任、竞争、亏欠、合作等不同状态。 - 关键人物能够提供信息、机会、挑战或阻碍。 - 关系变化应通过行为和事件表达，而不仅是显示 `+5`。 ##### 数学挑战 - Contest 可用于考试、竞赛、面试和限时事件。 - LaTeX 可用于证明、论文、书信和教学表达。 - 推理、估算和建模可用于调查或现实决策。 - 挑战结果影响剧情，但失败通常应开启不同路径，而不是简单卡关。 #### 6.4.6 真实与虚构边界 采用“真实骨架 + 虚构剧情”： - 数学知识、专业路径、时代背景和职业机制应尽量真实。 - 角色、对话、事件组合和分支可以戏剧化。 - 涉及真实人物时标记事实来源和艺术加工范围。 - 不把虚构选择包装成真实历史事实。 - 每段人生结束后提供“真实世界中的他们”或延伸阅读。 #### 6.4.7 跨剧本成长 跨剧本成长用于连接不同人生，但不能把选择体验变成单纯刷数值： - 五维能力记录用户体验过的数学方式。 - 人物卡代表遇见和理解过的人，而不是付费稀有度。 - 数学精灵反映长期倾向与经历。 - 结局图鉴记录不同人生选择。 - 特殊身份、卡牌或经历可解锁其他剧本的额外信息和对话。 - 核心结局不能要求重复刷取或付费。 #### 6.4.8 数学人生大厅设计 当前页面以四张等权主题卡为主体，其中三张显示“敬请期待”。这会让核心产品看起来像尚未完成的功能目录，也没有形成继续游玩的动力。 生产版应将该页面设计为“人生大厅”，而不是剧本列表。 ##### 新用户状态 首屏结构建议： 1. 身份引导 Hero：“你会成为怎样的数学人？” 2. 主行动：开始 MathBTI。 3. 次行动：暂不测试，自由选择人生。 4. 四种数学精神的简短预览。 5. 一个可直接试玩的信仰者序章。 6. 人物 Skill 推荐，让用户理解这里不只有一条长剧情。 ##### 回访用户状态 首屏结构建议： 1. “继续你的人生”主卡：当前章节、地点、关键人物、最近选择和预计剩余时间。 2. 当前身份：MathBTI 人格、代表数学家和五维倾向。 3. 当前悬念：展示尚未解决的问题，不提前暴露结果。 4. 当前关系：只展示最关键的 2 至 3 位人物。 5. 主行动：继续旅程。 6. 次行动：回顾路径、切换存档或进入相关挑战。 ##### 四条旗舰线展示 四条线不应继续使用完全相同的空白卡片。建议使用一张“数学人生地图”或具有明显叙事差异的路线卡： - 展示该路线的核心冲突，而不只是数学家名单。 - 展示体验时长、章节进度和已发现结局。 - MathBTI 推荐路线使用“与你最契合”标识。 - 未完成路线提供序章、人物档案或开发预告，不重复堆叠“敬请期待”。 - 不使用强制锁定，用户始终可以自由选择其他路线。 四条路线的入口文案应表达冲突： | 路线 | 示例入口文案 | |---|---| | 信仰者 | 当更快的答案随处可得，你还愿意慢慢证明一件事吗？ | | 传播者 | 发现真理和让别人理解真理，哪一个更重要？ | | 应用者 | 当你的模型能够改变现实，你愿意为结果承担什么？ | | 直觉者 | 当你看见所有人都看不见的结构，如何证明自己没有错？ | ##### 人物 Skill 区 人物 Skill 应成为大厅中的持续内容流： - 每周或每两周推荐一个人物人生。 - 卡片展示人物、时代、核心抉择和约 20 分钟时长。 - 支持按数学家、校友、职业、时代和主题筛选。 - 完成后展示人生路径，而不是只显示“通关”。 - 相关 Skill 可以反向解锁旗舰线中的信息、人物对话或卡片。 ##### 特别篇 《葫芦侠行》不应与四大人格路线混在同一层级，可放入“特别篇”： - 保留独立世界观和叙事风格。 - 共享账号、五维能力、卡牌和结局图鉴。 - 不强行解释为四条真实人生线之一。 ##### 页面视觉优先级 ```text 继续当前人生 / MathBTI 身份入口 ↓ 当前悬念、关系与成长 ↓ 四条旗舰人生地图 ↓ 本期人物 Skill ↓ 特别篇与已完成的人生图鉴 ``` 页面首屏不应再出现大面积不可点击的“敬请期待”卡片。 --- ## 7. Contest 产品方案 ### 7.1 每日异步赛 每日异步赛是重要留存模块，但不是首个上线的比赛形态。它与实时 `1v1` 共用题库、判分、Rating 和反作弊基础设施，在实时玩法可用后同期交付或紧随其后上线。 建议基础规则： | 项目 | 建议 | |---|---| | 题量 | 10 题 | | 时长 | 3 至 5 分钟 | | 正式机会 | 每日 1 次 | | 练习机会 | 不限次数，不进入正式榜 | | 计分 | 正确率优先，其次为用时和难度 | | 赛道 | 入门、标准、进阶、Open | | 反馈 | 总分、逐题结果、耗时、知识标签、解释 | 比赛计时、出题和判分必须由服务端控制。客户端只负责展示和提交答案。 ### 7.2 单人闯关 单人闯关用于非正式练习： - 随时开始。 - 难度逐步提升。 - 连续答对形成连击。 - 错误不会影响正式 Rating。 - 可与数学精灵经验和能力成长关联。 ### 7.3 主题周赛 建议主题： - 口算速度 - 估算 - 概率直觉 - 几何观察 - 逻辑推理 - 数学常识 - LaTeX 表达 主题周赛用于内容运营，不要求首发全部完成。 ### 7.4 排行榜 排行榜分为： - 每日榜 - 周榜 - 赛季榜 - 邀请码小组榜 - 好友榜，后续开放 排行榜默认显示昵称和头像，不显示真实姓名、学校和精确年龄。 排序原则： 1. 正式得分。 2. 正确率。 3. 完成用时。 4. 达成时间。 ### 7.5 实时多人赛 实时多人赛是比赛模块的首发主推玩法。为了控制生产风险，第一版只实现 `1v1 口算竞技`，并与数学人生核心版本一起进入首发范围；每日异步赛可以同批上线，也可以在实时 `1v1` 稳定后紧随上线。 首个实时玩法建议限制为 `1v1 口算竞技`： - Rating 匹配。 - 双方接收同一题目序列。 - 60 秒连续作答。 - 服务端计时和判分。 - 支持断线重连和超时结算。 - 结束后展示双方逐题时间线。 后续再评估多人房间、观战和淘汰赛。 首发明确不做： - 三人及以上同局。 - 自定义房间和房主规则。 - 淘汰赛和大型锦标赛。 - 观战、弹幕和语音。 - 现金或可交易奖励。 ### 7.6 公平与反作弊 首发最低要求： - 正式比赛题目由服务端下发。 - 服务端记录开始、作答和提交时间。 - 正式答案不能随题目一起返回。 - 同一用户、设备和邀请码组进行基础频率限制。 - 对极端用时、重复答案序列和异常高分进行标记。 - 管理员可以隐藏异常成绩并记录操作原因。 - 不把客户端本地分数直接写入排行榜。 --- ## 8. 工具箱与 LaTeX Lab 产品方案 LaTeX Lab 是工具箱中的核心子模块，不单独占用一级导航。工具箱不是零散功能集合，而是用户在数学人生和比赛之外进行数学表达、实验和练习的工作空间。 ### 8.1 手写公式 - 支持鼠标、触控笔和触摸屏。 - 手写轨迹可撤销、重做和清空。 - 将手写内容识别为 LaTeX。 - 展示识别置信度和候选结果。 - 同步展示渲染效果。 - 支持复制、保存和继续编辑。 识别服务需要单独选型，可评估自建模型、Mathpix 或其他 API。正式选型前必须确认成本、隐私和可用性。 ### 8.2 LaTeX 编辑器 - 左侧源码，右侧实时预览。 - 错误位置提示。 - 自动补全括号和常见命令。 - 支持矩阵、方程组和对齐环境。 - 支持导出 PNG、SVG 和源码。 - 自动保存草稿。 ### 8.3 零基础教学 课程建议分层： 1. 上标、下标和基础运算。 2. 分式、根式和括号。 3. 求和、积分、极限。 4. 矩阵和方程组。 5. 多行公式与对齐。 6. 完整数学解答和证明排版。 每课包含： - 概念说明。 - 可运行示例。 - 模仿输入。 - 自动判定。 - 常见错误解释。 ### 8.4 LaTeX 表达挑战 - 根据公式图片输入 LaTeX。 - 根据自然语言要求构造公式。 - 修复错误公式。 - 按准确率和完成时间计分。 - 可作为 Contest 的独立主题赛。 --- ## 9. 账号与“我的” ### 9.1 邀请码注册 首发流程： ```text 输入邀请码 ↓ 设置邮箱或用户名、密码和昵称 ↓ 完成注册 ↓ 检测并迁移当前游客数据 ``` 需要支持： - 单次邀请码。 - 批量邀请码。 - 有效期。 - 最大使用次数。 - 邀请码分组。 - 禁用和使用记录。 密码必须使用成熟密码哈希，不得明文存储。 ### 9.2 游客数据迁移 注册前产生的以下数据应允许迁移： - MathBTI 结果。 - 数学精灵。 - 已有卡牌。 - 剧情存档。 - 本地收藏。 迁移前应展示摘要，由用户确认。迁移完成后以服务端数据为准。 ### 9.3 我的页面 首发必须可用： - 昵称、头像和个人简介。 - 当前赛道、段位和 Rating。 - 连续参赛天数。 - 比赛历史和错题。 - LaTeX 学习进度。 - 我的公式。 - 收藏和浏览记录。 - 数学人物卡册。 - 密码修改。 - 登录设备和退出登录。 - 账号注销。 --- ## 10. 管理后台 ### 10.1 P0 后台能力 - 管理员登录和权限分级。 - 邀请码生成、导出、禁用和使用记录。 - 用户查询、封禁、解封和密码重置。 - MathBTI 题目、人格结果和推荐关系维护。 - 旗舰人生、章节、节点、选项、条件和效果维护。 - 人物、关系类型、剧本资源和结局维护。 - 人物 Skill 创建、校验、预览、发布和版本回滚。 - 剧本节点可达性、引用和存档兼容检查。 - 题目录入、批量导入、标签、难度和答案维护。 - 比赛组卷、预览、定时发布、撤回和结果查询。 - 排行榜异常成绩处理。 - 视频和知识卡片的创建、审核、上下架。 - LaTeX 课程和挑战题维护。 - 管理员操作审计。 ### 10.2 数据看板 首发关注： - 新增注册用户。 - 邀请码转化率。 - MathBTI 完成率和各人格分布。 - 数学人生开始率、章节完成率和主线完成率。 - 关键节点选项分布和退出节点。 - 人物 Skill 开始率、完成率和重玩率。 - 各结局达成率与关系变化。 - 今日 Contest 参与率和完成率。 - D1、D7 留存。 - 各赛道参与人数。 - 每题正确率和平均耗时。 - LaTeX Lab 使用率和课程完成率。 - AI 调用次数、失败率和成本。 --- ## 11. 技术架构建议 ### 11.1 已确认方案 ```text Next.js Web 后续 Taro 小程序 │ ▼ Django + Django REST Framework ├── Accounts ├── Math Life ├── Contest ├── Toolbox / LaTeX Lab ├── Content ├── Story ├── Progression ├── Engagement └── AI Tutor │ MySQL 8.0.35 + Redis + 对象存储 ``` 首期采用模块化单体，不拆微服务。 ### 11.2 采用 Django 的原因 本项目生产版的核心需求集中在： - 用户、权限和会话。 - 邀请码注册。 - 数据库模型和迁移。 - 题库与内容运营后台。 - 管理员权限与审计。 - 表单校验和安全默认值。 Django 可以直接提供这些基础能力。当前 Flask 代码作为重构期间的数据和行为参考，不再作为生产版目标架构继续扩展。 ### 11.3 Django 模块化单体结构 目标工程结构建议为： ```text backend/ ├── manage.py ├── config/ ├── accounts/ ├── math_life/ ├── contest/ ├── latex_lab/ ├── content/ ├── story/ ├── progression/ ├── engagement/ ├── ai_tutor/ ├── admin/ ├── common/ └── tests/ ``` 每个业务模块拥有自己的模型、服务、API、后台配置和测试。跨模块写操作通过显式服务接口完成，不允许在视图层随意跨模块更新数据库。 ### 11.4 实时比赛 - Django Channels 提供 WebSocket。 - Redis 作为 Channel Layer。 - 实时连接与普通 HTTP 可分别部署进程。 - ASGI 服务承载实时连接，普通 HTTP API 与 WebSocket 可以分别扩容。 - 实时比赛上线前必须完成独立压测、断线恢复和异常结算测试。 --- ## 12. 后端模块边界 | 模块 | 责任 | |---|---| | Accounts | 用户、邀请码、登录、权限、设备会话 | | Math Life | MathBTI 身份、旗舰人生、Skill 包、选择结算、关系与存档 | | Contest | 题库、比赛、作答、判分、Rating、排行榜 | | LaTeX Lab | 公式、草稿、课程、练习、识别任务 | | Content | 视频、知识卡片、标签、作者、版权、上下架 | | Story | 剧本、版本、节点、选择、效果、存档 | | Progression | 数学精灵、五维能力、经验、卡牌、任务 | | Engagement | 收藏、历史、阅读完成、行为事件 | | AI Tutor | 模型调用、上下文、限流、审计、成本 | | Operations | 后台配置、公告、审核、数据导出 | 禁止模块绕过服务层随意修改其他模块的数据。 --- ## 13. 核心数据模型 ### 13.1 账号 - `User` - `UserProfile` - `InviteCode` - `InviteCodeUsage` - `UserSession` - `Role` - `AuditLog` ### 13.2 Contest - `Question` - `QuestionVersion` - `QuestionTag` - `Contest` - `ContestQuestion` - `ContestAttempt` - `ContestAnswer` - `ContestScore` - `RatingHistory` - `LeaderboardSnapshot` - `CheatFlag` 题目修改后必须产生版本，历史比赛不能被新内容覆盖。 ### 13.3 LaTeX Lab - `FormulaDocument` - `FormulaRevision` - `LatexCourse` - `LatexLesson` - `LatexExercise` - `LatexAttempt` - `HandwritingRecognitionJob` ### 13.4 剧情与成长 - `MathIdentity` - `Story` - `StoryVersion` - `StoryChapter` - `StoryNode` - `StoryChoice` - `StoryCondition` - `StoryEffect` - `StorySave` - `StoryRun` - `StoryEnding` - `Character` - `UserRelationship` - `SkillPackage` - `UserPet` - `UserAbility` - `Card` - `UserCard` - `RewardTransaction` 存档必须绑定： ```text user_id + story_id + story_version ``` 奖励和卡牌必须通过服务端事务发放。 旗舰人生和人物 Skill 必须共用同一套基础引擎及内容校验规则，但允许通过节点组件扩展各自的特殊玩法。剧本发布前需要自动检查： - 起点和终点是否有效。 - 节点引用是否完整。 - 是否存在不可达节点。 - 条件和效果字段是否合法。 - 是否存在无法退出的意外循环。 - 使用的挑战、人物和资源是否存在。 - 新版本是否能够兼容或明确迁移旧存档。 --- ## 14. API 与状态原则 - API 使用 `/api/v1/` 版本前缀。 - 输入统一校验，错误返回统一结构。 - 所有写操作进行权限校验。 - 正式比赛提交需要幂等键。 - 列表接口默认分页。 - 服务端是用户数据的最终事实来源。 - `localStorage` 只用于游客临时数据、界面偏好和可失效缓存。 - 不允许客户端直接决定积分、Rating、奖励和抽卡结果。 - 前后端共享 OpenAPI 契约和生成类型。 --- ## 15. 安全与合规 生产上线前最低要求： - 所有密钥通过环境变量或密钥管理服务注入。 - 当前已暴露的 AI Key 立即吊销。 - 密码使用成熟密码哈希。 - 登录、注册、AI 和比赛接口具备限流。 - 管理后台启用强密码和双因素认证，条件允许时实施。 - 管理操作保留审计日志。 - 用户上传或输入内容进行长度、格式和安全校验。 - 禁止 `eval` 和动态执行用户输入。 - 为未成年人准备隐私政策和最小数据收集方案。 - 支持用户数据导出和账号注销。 - 视频、图片和文本维护版权来源与下架状态。 --- ## 16. 可观测性与稳定性 ### 16.1 日志 每个请求至少记录： - Request ID - 时间 - 路径和状态码 - 匿名化用户 ID - 响应时间 - 错误类型 - 关键业务 ID 禁止记录密码、Token、完整 AI Key 和敏感个人信息。 ### 16.2 监控 - API 请求量、错误率和 P95 延迟。 - MySQL 8.0.35 连接与慢查询。 - Redis 状态。 - WebSocket 在线连接和断线率。 - Contest 提交成功率。 - AI 请求成功率、延迟和成本。 - 任务队列积压。 ### 16.3 告警 - 5xx 错误率超过阈值。 - 登录或比赛提交连续失败。 - 数据库不可用。 - AI 成本异常增长。 - 部署健康检查失败。 - 实时连接大面积断开。 --- ## 17. 测试要求 ### 17.1 单元测试 重点覆盖： - 邀请码有效性。 - 密码和权限。 - Contest 计分。 - Rating 变化。 - 排行榜排序。 - 题目版本。 - 奖励发放幂等性。 - MathBTI 评分。 - 剧情效果和存档版本。 - LaTeX 练习判定。 ### 17.2 集成测试 - 注册、登录、退出和游客迁移。 - 后台发布题目和比赛。 - 实时匹配、统一发题、服务端判分和 Rating 结算。 - WebSocket 断线重连、超时和重复提交。 - 完整 Contest 作答流程。 - 收藏、历史和个人资料。 - AI 限流与异常降级。 - 数据库迁移。 ### 17.3 E2E 最低覆盖： 1. 邀请码注册、完成 MathBTI 并进入推荐人生。 2. 完成一个关键选择，刷新页面后从正确节点继续。 3. 完成一段人物 Skill 并写入结局和五维成长。 4. 两个测试用户完成实时匹配、整场 `1v1` 和 Rating 结算。 5. 模拟一方断线并恢复，双方得到一致且唯一的比赛结果。 6. 完成今日异步挑战并查看成绩和排行榜。 7. 完成一节 LaTeX 课程并保存公式。 8. 修改个人资料并重新登录，确认身份、存档和记录仍存在。 9. 管理员创建、校验、预览并发布一个人物 Skill。 --- ## 18. Gitea Action 与部署 ### 18.1 现有部署的可复用部分 可以保留： - PR 合并触发。 - SSH 到生产服务器。 - 服务器环境中的进程管理。 - 部署密钥和主机 Secrets。 不建议继续使用生产目录内 `git reset --hard` 后直接重载的方式作为最终方案。 ### 18.2 第一阶段改造 ```text PR 合并 ↓ 安装依赖 ↓ 静态检查与自动化测试 ↓ SSH 到服务器 ↓ 备份数据库 ↓ 拉取版本 ↓ 执行数据库迁移 ↓ 收集静态资源 ↓ 重启应用 ↓ 检查 HTTP 与 WebSocket 健康状态 ↓ 健康检查 ↓ 失败则回滚 ``` ### 18.3 推荐最终形态 - CI 构建带版本号的 Docker 镜像。 - 镜像推送至私有 Registry。 - 服务器拉取指定版本。 - 数据库迁移作为独立步骤执行。 - HTTP API 和 ASGI WebSocket 服务分别执行健康检查。 - 应用通过健康检查后切换流量。 - 保留最近若干版本，可快速回滚。 ### 18.4 环境 至少区分： - Development - Staging - Production 生产数据库不能继续作为 Git 文件提交。 --- ## 19. 迁移策略 采用当前仓库内的分阶段重构，不长期运行两套完整系统。 具体原则： - 在当前仓库新增 `backend/` 和新版前端目录，保留 Git 历史、文档和内容资产。 - Flask 旧实现只用于行为对照和迁移验证，不再新增产品功能。 - Django 按垂直模块逐步接管 URL、数据和用户流程。 - 每个新模块完成数据迁移、回归测试和生产验证后，删除对应 Flask 路由及旧前端逻辑。 - 重构期间只允许一个生产入口和一份权威用户数据，避免双写和长期数据分叉。 - 使用短期兼容适配器读取旧 JSON 或 SQLite 导出数据，不建设长期双系统同步。 ### 阶段 0：当前 Demo 止血 - 吊销并替换已暴露密钥。 - 修复无效依赖版本。 - 修复数据库字段迁移。 - 禁止危险动态执行。 - 对当前生产数据做备份。 ### 阶段 1：生产骨架 - 在当前仓库建立 Django `backend/` 工程和新版前端结构。 - MySQL 8.0.35、Redis 和对象存储。 - 邀请码注册、登录和后台。 - 统一剧情数据模型、版本机制和内容校验器。 - CI、Staging、监控和备份。 ### 阶段 2：第一条垂直切片 ```text 注册 → 首页 → MathBTI 身份 → 信仰者数学少年线第一章 → 关键选择与关系变化 → 存档 → 人生档案 ``` 这一阶段用于验证新的核心体验和剧情引擎，而不是只验证页面迁移。 ### 阶段 3：实时 1v1 比赛骨架 - Django Channels、Redis Channel Layer 和 ASGI 部署。 - 实时匹配、统一发题、服务端计时和判分。 - 断线重连、超时结算和异常退出处理。 - Rating、比赛记录和基础排行榜。 - 完成并发、弱网、断线和作弊场景压测。 - 同一题库和判分服务为每日异步赛预留接口。 ### 阶段 4：信仰者完整线与 Skill 样板 - 完成约 2 小时的信仰者数学少年线。 - 接入隐藏信息、资源、关系和数学挑战。 - 制作至少 2 个约 20 分钟的人物 Skill 样板。 - 完成人生结局、图鉴和跨剧本五维成长。 - 将实时 `1v1` 作为剧情挑战和独立比赛入口接入。 - 开始第一轮真实用户测试。 ### 阶段 5：异步赛与工具箱 - 每日异步 Contest。 - 排行榜和比赛历史。 - LaTeX 编辑器。 - 模板库。 - 第一阶段课程。 - 表达挑战。 - 手写识别技术验证。 若团队资源足够，每日异步赛可以与阶段 3 的实时 `1v1` 同期完成，不得反向阻塞实时首发。 ### 阶段 6：内容与成长 - 视频和知识卡片后台。 - 完善数学精灵。 - 完善人物卡和服务端成长数据。 ### 阶段 7：更多数学人生 - 迁移葫芦侠行。 - 开发传播者、应用者或直觉者下一条旗舰线。 - 建立人物 Skill 内容生产后台。 --- ## 20. 首发范围建议 ### P0 - 邀请码注册和登录。 - 个性化首次引导。 - 行动导向首页。 - MathBTI 身份入口。 - 统一、可版本化的数学人生引擎。 - 约 2 小时的信仰者数学少年线。 - 隐藏信息选择、剧本内资源和人物关系。 - 剧情存档、结局和人生档案。 - 至少 2 个人物 Skill 样板。 - 五维能力、第一版数学精灵和人物卡沉淀。 - 实时 `1v1` 口算竞技。 - 服务端匹配、计时、判分、Rating 和比赛记录。 - WebSocket 断线恢复、异常结算和基础反作弊。 - 实时比赛排行榜。 - 可用的“我的”。 - 剧本、人物、Skill、用户、邀请码、题库和比赛后台。 - 监控、备份、健康检查和回滚。 ### P1 - 每日异步 Contest。 - 入门、标准、进阶三个赛道。 - 每日榜、周榜和邀请码小组榜。 - 比赛历史和基础错题记录。 - LaTeX 编辑器、模板库和首批课程。 - 单人闯关。 - 主题周赛。 - LaTeX 表达挑战。 - 手写识别。 ### P2 - 多人房间、淘汰赛和观战。 - 葫芦侠行迁移。 - 第二条旗舰人生线。 - 人物 Skill 内容生产工具。 - 好友榜和组队赛。 - 复杂赛季活动。 - 小程序客户端。 - 个性化推荐。 --- ## 21. 生产验收标准 ### 产品 - 新用户能在 60 秒内完成注册并进入 MathBTI 或第一条人生。 - 用户能在 3 次点击内继续上次的人生节点。 - 用户完成关键选择后，能理解故事变化，但不能提前看穿所有最优结果。 - 信仰者主线具备完整章节、关系、资源、挑战和多个有意义结局。 - 人物 Skill 可以在约 20 分钟内完成，并提供可回顾的人生路径。 - 两名在线用户能够完成匹配、实时作答、结算和 Rating 更新。 - 一名用户短暂断线后能够回到原比赛，且双方只产生一份一致赛果。 - 用户重新登录后，身份、存档、关系、结局、比赛和课程数据不丢失。 - 运营可以不修改业务代码发布剧本新版本和人物 Skill。 ### 性能 - 常规网络下首页可交互时间不超过 2.5 秒。 - 普通 API P95 不超过 500ms，不含 AI 和手写识别。 - 正常负载下实时答题消息端到端 P95 延迟不超过 300ms。 - 有可匹配玩家时，实时 `1v1` 的 P95 匹配时间不超过 10 秒。 - Contest 提交成功率不低于 99.9%。 - 排行榜生成不阻塞正式成绩提交。 - 剧情选择保存成功率不低于 99.9%。 ### 稳定性 - 部署失败可以自动终止并恢复上一版本。 - 数据库每日自动备份。 - 完成至少一次备份恢复演练。 - 关键错误能够通过监控告警发现。 - HTTP 与 WebSocket 服务均有独立健康检查和告警。 - Staging 环境通过全部核心 E2E 后才能发布。 ### 安全 - 仓库中不存在生产密钥。 - 未登录用户不能读取或修改其他用户数据。 - 客户端不能直接修改正式分数、Rating 和奖励。 - 管理员操作可追溯。 --- ## 22. 主要风险 | 风险 | 等级 | 应对 | |---|---|---| | 全年龄定位导致内容与难度模糊 | 高 | 首次分层、赛道隔离、个性化首页 | | 数学人生同时承载过多玩法导致首发失控 | 高 | 先完整打磨信仰者线，其他三线不同时开发 | | 剧情内容生产成本高 | 高 | 旗舰线与 20 分钟 Skill 分层，建立结构化模板 | | 四类互动系统互相耦合 | 高 | 统一节点契约，玩法组件按需挂载 | | 数学人生与实时比赛同时进入 P0 导致延期 | 高 | 实时首版只做 1v1 口算；异步赛允许紧随上线 | | 实时比赛早期活跃人数不足，匹配等待过长 | 高 | 邀请码分组、机器人兜底或约战时段；首发监控匹配时长 | | 重写周期过长，迟迟无法验证 | 高 | 使用垂直切片，阶段 2 即开始试点 | | 题库质量和数量不足 | 高 | 提前建立题目模板、审核流和版本机制 | | 排行榜诱发作弊 | 中 | 服务端判分、异常检测、管理员复核 | | 手写识别成本和准确率不确定 | 中 | 先完成编辑器，再独立 PoC | | 旧 `localStorage` 数据难迁移 | 中 | 定义一次性迁移协议和用户确认 | | Django 学习或迁移成本 | 中 | 先完成账号、后台和数学人生第一章垂直切片 | | 实时连接稳定性 | 中 | 独立压测、灰度发布、断线恢复 | --- ## 23. 决策记录与剩余问题 ### 23.1 已确认决策 1. 数学人生宇宙是生产版核心产品。 2. MathBTI、四条旗舰线、人物 Skill 包和跨剧本成长构成同一系统。 3. 信仰者数学少年线是首发旗舰内容。 4. 比赛模块以实时多人优先；首版限制为 `1v1`，异步赛同期或紧随上线。 5. 一级模块为：首页、数学人生、比赛、工具箱、探索发现、我的。 6. LaTeX Lab 属于工具箱的重点子模块。 7. 后端采用 Django 模块化单体。 8. 正式数据库采用 MySQL 8.0.35。 9. 在当前仓库中分阶段重构，不长期并行维护新旧系统。 ### 23.2 首发前必须决策 1. 实时 `1v1` 与每日异步赛是否必须同一次公开发布。 2. 信仰者主线的 2 小时目标如何拆分章节和首轮试玩范围。 3. 首批 2 个人物 Skill 选择哪两位人物或校友。 4. 四条旗舰线是否共享同一现实世界，还是仅共享数学精神和成长层。 5. 邀请码注册使用邮箱，还是用户名加密码。 6. 实时比赛冷启动采用机器人兜底、邀请码组内约战还是固定开放时段。 7. LaTeX 手写识别首版采用第三方服务还是暂缓。 8. 首批试点规模和邀请码分组是什么。 ### 23.3 后续决策 1. 人生路线与结局图鉴的展示方式。 2. 五维能力如何从选择和挑战中增长。 3. 数学精灵与人生经历、Contest 奖励的具体关系。 4. 段位名称、赛季周期和 Rating 算法。 5. 是否提供学校或社团管理视图。 6. 小程序的启动时间。 --- ## 24. 建议评审议程 建议会议时长 90 分钟： 1. 10 分钟：确认核心目标和非目标。 2. 20 分钟：确认数学人生宇宙、四条路线与人物 Skill。 3. 15 分钟：确认信仰者主线范围和互动机制。 4. 10 分钟：确认用户分层与首页。 5. 10 分钟：确认 Contest 与 LaTeX 的支撑关系。 6. 10 分钟：确认账号、后台和数据要求。 7. 10 分钟：确认技术架构与迁移方式。 8. 5 分钟：逐项记录决策、负责人和截止时间。 评审结束后应产出： - 决策记录。 - 正式 PRD v1.0。 - 技术设计文档。 - 数据模型和 API 草案。 - 里程碑、负责人和排期。