From b88d15698afafc086ce5074a6982dc525c7a915b Mon Sep 17 00:00:00 2001
From: Jacky <adding2003@gmail.com>
Date: Sat, 8 Aug 2026 18:39:17 +0800
Subject: [PATCH] v0.1 : Bible started!

---
 Bible.md | 844 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 844 insertions(+)
 create mode 100644 Bible.md

diff --git a/Bible.md b/Bible.md
new file mode 100644
index 0000000..07de916
--- /dev/null
+++ b/Bible.md
@@ -0,0 +1,844 @@
+文档版本：v0.3 评审稿（核心决策更新版）
+文档状态：部分决策已确认
+更新日期：2026-08-08
+适用范围：Web 生产版，兼顾后续微信小程序
+核心目标：把当前演示系统升级为可运营、可扩展、可监控、可稳定发布的线上产品
+
+---
+1. 执行摘要
+当前仓库已经验证了 MathBTI、数学人物卡、知识内容、互动剧情、数学工具等产品表达，但工程形态仍属于内部 Demo：
+- 后端路由、数据库和 AI 调用集中在单个 Flask 文件。
+- 前端页面、状态和业务规则集中在单个 JavaScript 文件。
+- SQLite 同时承载结构、种子数据和运行时用户数据。
+- 用户成长、抽卡和剧情状态大量依赖 localStorage。
+- 缺少正式账号、权限、数据库迁移、测试、监控和可靠回滚。
+- 产品入口较多，但缺少明确的每日使用主线。
+生产版不继续在当前单文件结构上堆叠功能，但也不另建一套长期并行的新旧系统。项目采用当前仓库内的分阶段重构：先建立 Django 生产骨架和兼容层，再按垂直业务链路替换 Flask 路由、SQLite 和旧前端模块，完成一个阶段即删除对应旧实现。
+生产版的产品主线定义为：
+数学人生是核心体验。MathBTI 帮助用户发现自己的数学人格，四条旗舰人生线让用户体验不同的数学精神，人物 Skill 包持续扩展真实而多样的人生选择；Contest、LaTeX 和内容探索既可独立使用，也服务于人生节点与长期成长。
+本轮已经确认的产品方向：
+暂时无法在飞书文档外展示此内容
+评审建议：
+- 统一剧情引擎与信仰者数学少年线作为生产版第一阶段核心功能。
+- MathBTI 不是孤立测试，而是进入数学人生宇宙的身份仪式。
+- 人物 Skill 包使用统一结构持续生产，首发至少提供可验证的样板。
+- 首版 Contest 以实时 1v1 为主推体验，每日异步赛与其同期交付或紧随其后。
+- 实时范围严格限制为单一匹配模式，不在首版扩展房间赛、淘汰赛和观战。
+- 全年龄用户必须通过水平分层、兴趣选择和个性化首页解决体验冲突。
+- 后端确定改为 Django 模块化单体，数据库确定改为 PostgreSQL。
+- 在当前仓库中实施分阶段重构；每个新模块通过验收后替换并删除对应旧代码。
+
+---
+2. 本次评审目标
+本轮已经确认：
+1. “数学人生宇宙”是生产版核心产品。
+2. MathBTI、四条旗舰线、人物 Skill 包和跨剧本成长属于同一系统。
+3. 信仰者数学少年线是首发旗舰内容。
+4. Contest 以实时多人玩法优先，异步赛同期交付或紧随其后。
+5. 六个一级模块为：首页、数学人生、比赛、工具箱、探索发现、我的。
+6. LaTeX Lab 放入工具箱，并作为工具箱重点能力。
+7. 后端采用 Django 模块化单体。
+8. 数据库采用 PostgreSQL。
+9. 当前仓库进行分阶段重构，不长期并行维护两套产品系统。
+本次后续评审需要形成以下结论：
+1. 实时 1v1 与每日异步赛是否必须在同一次公开发布中交付。
+2. 信仰者主线的章节范围与首轮试玩范围。
+3. 首批人物 Skill、邀请注册方式和试点规模。
+4. 确认详细交付阶段和生产验收标准。
+本次评审不解决具体视觉稿、所有题目内容和每个接口字段。上述内容应在方案通过后进入详细 PRD 与技术设计阶段。
+
+---
+3. 产品定位
+3.1 一句话定义
+葫芦数学是一个面向全年龄数学兴趣用户的“数学人生宇宙”：用户发现自己的数学人格，进入不同数学精神对应的人生故事，在选择、关系、挑战和成长中体验数学如何塑造一个人。
+3.2 核心价值
+- 不把数学简化为刷题和知识点，而是呈现为人生选择、精神气质和理解世界的方式。
+- 用 MathBTI 建立身份认同，让用户获得“这是一种属于我的数学人生”的入口。
+- 用四条旗舰人生线提供深度沉浸，用人物 Skill 包持续扩展真实人生样本。
+- 用短时 Contest 形成明确、可重复的每日行为。
+- 用 LaTeX Lab 降低数学表达门槛，并成为剧情中的真实能力。
+- 用个人档案记录跨剧本成长，而不是只展示静态信息。
+3.3 产品核心循环
+完成 MathBTI 或选择感兴趣的数学人生
+  ↓
+进入旗舰主线或人物 Skill 包
+  ↓
+在不完整信息下做人生选择
+  ↓
+管理能力、时间、关系与机会
+  ↓
+通过 Contest、LaTeX 或推理挑战改变部分结果
+  ↓
+获得结局、数学人物卡和跨剧本成长
+  ↓
+继续另一条人生，或通过每日 Contest 回访
+3.4 非目标
+首个生产版本不做：
+- 开放式论坛、陌生人私信和用户发帖。
+- 现金奖励、充值抽卡和博彩式机制。
+- 四条旗舰人生线同时完整上线。
+- 实时比赛的房间赛、多人混战、淘汰赛、观战等复杂形态。
+- 复杂推荐算法。
+- 同时重制全部历史剧情。
+- 微服务拆分和 Kubernetes 集群。
+
+---
+4. 用户分层
+“全年龄”不能理解为所有用户看到同一套题和同一个排行榜。系统首次使用时应建立轻量用户画像。
+4.1 首次引导
+首次进入需要完成或跳过以下选择：
+暂时无法在飞书文档外展示此内容
+涉及未成年人时，只收集实现分层所需的最少信息，不要求真实学校、真实年龄和真实姓名。
+4.2 赛道分层
+首发建议设置：
+- 入门赛道：基础运算、直观逻辑和轻量数学常识。
+- 标准赛道：初高中通用数学思维和速度挑战。
+- 进阶赛道：高阶逻辑、概率、估算和大学基础数学。
+- Open 赛道：不限制用户水平，用于主题活动。
+用户可以自主切换练习赛道，但正式排行榜应按赛道分别计算。
+
+---
+5. 信息架构
+5.1 一级导航
+首页
+数学人生
+比赛
+工具箱
+探索发现
+我的
+建议保持左侧导航，移动端折叠为底部导航或抽屉导航。
+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 新用户任务
+引导新用户一进来先做mathbti，然后再让他尝试我们四条剧本里的一个
+
+
+---
+6.4 数学人生核心产品方案
+6.4.1 产品结构
+数学人生不是导航中的一个普通内容栏目，而是连接产品其他能力的核心系统。
+身份层：MathBTI 数学人格
+  ↓
+旗舰体验层：信仰者 / 传播者 / 应用者 / 直觉者
+  ↓
+扩展体验层：人物 Skill 人生包 / 特别篇
+  ↓
+互动层：隐藏信息选择 / 资源经营 / 人物羁绊 / 数学挑战
+  ↓
+成长层：五维能力 / 数学精灵 / 卡牌 / 结局图鉴
+6.4.2 MathBTI 的角色
+MathBTI 应从独立测试升级为数学人生的身份入口：
+- 给出用户的数学人格与代表数学家。
+- 推荐最适合开始的旗舰人生线，但不锁定其他路线。
+- 生成初始五维能力倾向。
+- 赠送第一张人物卡，并建立数学精灵。
+- 测试结果影响部分开场对白、推荐顺序和隐藏选项。
+- 用户可以自由重测，但历史身份和人生记录不应被覆盖。
+6.4.3 四条旗舰人生线
+四条路线彼此独立，每条都是约 2 小时、可分章节完成、可重复体验的完整人生线。
+暂时无法在飞书文档外展示此内容
+首发完整打磨“信仰者数学少年线”。另外三条路线在界面中可以展示世界观与开发状态，但不应使用空白大卡占据核心空间；可通过序章、人物预告或短 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 可以反向解锁旗舰线中的信息、人物对话或卡片。
+特别篇
+《葫芦侠行》不应与四大人格路线混在同一层级，可放入“特别篇”：
+- 保留独立世界观和叙事风格。
+- 共享账号、五维能力、卡牌和结局图鉴。
+- 不强行解释为四条真实人生线之一。
+页面视觉优先级
+继续当前人生 / MathBTI 身份入口
+  ↓
+当前悬念、关系与成长
+  ↓
+四条旗舰人生地图
+  ↓
+本期人物 Skill
+  ↓
+特别篇与已完成的人生图鉴
+页面首屏不应再出现大面积不可点击的“敬请期待”卡片。
+
+---
+7. Contest 产品方案
+7.1 每日异步赛
+每日异步赛是重要留存模块，但不是首个上线的比赛形态。它与实时 1v1 共用题库、判分、Rating 和反作弊基础设施，在实时玩法可用后同期交付或紧随其后上线。
+建议基础规则：
+暂时无法在飞书文档外展示此内容
+比赛计时、出题和判分必须由服务端控制。客户端只负责展示和提交答案。
+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 邀请码注册
+首发流程：
+输入邀请码
+  ↓
+设置邮箱或用户名、密码和昵称
+  ↓
+完成注册
+  ↓
+检测并迁移当前游客数据
+需要支持：
+- 单次邀请码。
+- 批量邀请码。
+- 有效期。
+- 最大使用次数。
+- 邀请码分组。
+- 禁用和使用记录。
+密码必须使用成熟密码哈希，不得明文存储。
+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 已确认方案
+Next.js Web
+后续 Taro 小程序
+        │
+        ▼
+Django + Django REST Framework
+├── Accounts
+├── Math Life
+├── Contest
+├── Toolbox / LaTeX Lab
+├── Content
+├── Story
+├── Progression
+├── Engagement
+└── AI Tutor
+        │
+PostgreSQL + Redis + 对象存储
+首期采用模块化单体，不拆微服务。
+11.2 采用 Django 的原因
+本项目生产版的核心需求集中在：
+- 用户、权限和会话。
+- 邀请码注册。
+- 数据库模型和迁移。
+- 题库与内容运营后台。
+- 管理员权限与审计。
+- 表单校验和安全默认值。
+Django 可以直接提供这些基础能力。当前 Flask 代码作为重构期间的数据和行为参考，不再作为生产版目标架构继续扩展。
+11.3 Django 模块化单体结构
+目标工程结构建议为：
+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. 后端模块边界
+暂时无法在飞书文档外展示此内容
+禁止模块绕过服务层随意修改其他模块的数据。
+
+---
+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
+存档必须绑定：
+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 延迟。
+- PostgreSQL 连接与慢查询。
+- 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 第一阶段改造
+PR 合并
+  ↓
+安装依赖
+  ↓
+静态检查与自动化测试
+  ↓
+SSH 到服务器
+  ↓
+备份数据库
+  ↓
+拉取版本
+  ↓
+执行数据库迁移
+  ↓
+收集静态资源
+  ↓
+重启应用
+  ↓
+检查 HTTP 与 WebSocket 健康状态
+  ↓
+健康检查
+  ↓
+失败则回滚
+18.3 推荐最终形态
+- CI 构建带版本号的 Docker 镜像。
+- 镜像推送至私有 Registry。
+- 服务器拉取指定版本。
+- 数据库迁移作为独立步骤执行。
+- HTTP API 和 ASGI WebSocket 服务分别执行健康检查。
+- 应用通过健康检查后切换流量。
+- 保留最近若干版本，可快速回滚。
+18.4 环境
+至少区分：
+- Development
+- Staging
+- Production
+生产数据库不能继续作为 Git 文件提交。
+
+---
+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. 主要风险
+暂时无法在飞书文档外展示此内容
+
+---
+23. 决策记录与剩余问题
+23.1 已确认决策
+1. 数学人生宇宙是生产版核心产品。
+2. MathBTI、四条旗舰线、人物 Skill 包和跨剧本成长构成同一系统。
+3. 信仰者数学少年线是首发旗舰内容。
+4. 比赛模块以实时多人优先；首版限制为 1v1，异步赛同期或紧随上线。
+5. 一级模块为：首页、数学人生、比赛、工具箱、探索发现、我的。
+6. LaTeX Lab 属于工具箱的重点子模块。
+7. 后端采用 Django 模块化单体。
+8. 正式数据库采用 PostgreSQL。
+23.2 首发前必须决策
+1. 实时 1v1 与每日异步赛必须同一次公开发布。
+2. 邀请码注册使用用户名加密码。
+3. 实时比赛冷启动采用邀请码组内约战。
+4. LaTeX 手写识别首版暂缓。
+23.3 后续决策
+1. 人生路线与结局图鉴的展示方式。
+2. 五维能力如何从选择和挑战中增长。
+3. 数学精灵与人生经历、Contest 奖励的具体关系。
+4. 段位名称、赛季周期和 Rating 算法。
+5. 是否提供学校或社团管理视图。
+6. 小程序的启动时间。
\ No newline at end of file