§1 产品定位与改造范围
1.1 产品简介
网报小程序是面向 K12 教培场景的家长与学生在线报名系统，提供选课、报名、支付等核心功能。本次原生改造将现有 Webview 套壳 H5 逐步替换为微信原生小程序实现。
1.2 小程序矩阵
网报当前存在两个小程序 + 一个 H5 端，共享同一套后端服务和用户体系：
| 终端 | 名称 | 默认城市 | 城市切换 | 说明 |
|---|
| 小程序 1 | 卓越悦学 | 广州 | 可切换（按配置） | 主力小程序，覆盖广州及其他城市 |
| 小程序 2 | 卓越优学 | 深圳 | 不可切换（锁定深圳） | 深圳专属，因资金监管要求独立 |
| H5 | 网报 H5 | 按配置 | 按配置 | 历史版本，原生改造后逐步废弃 |
两个小程序仅 openID 不同，unionId 统一打通，用户数据完全共享。
城市与小程序绑定规则
- 卓越悦学可展示多城市课程，但切换到深圳时不显示深圳课程
- 深圳课程仅在卓越优学中展示
- 判断逻辑：首页城市与当前小程序是否存在绑定关系 → 有绑定则显示该城市课程，无绑定则不显示
- 卓越优学小程序城市切换开关固定关闭，默认值锁定为「深圳」，后台不可配（前端硬编码锁定）
1.3 Tab 结构
| Tab | 说明 |
|---|
| 首页 | 运营推荐入口 |
| 选课 | 课程筛选与报名 |
| 我的 | 个人中心、订单、设置 |
无购物车 Tab。购物车入口在首页搜索栏右侧图标及选课/详情页。
1.4 术语表
| 术语 | 定义 |
|---|
| 学员 | 实际上课的孩子，一个家长可绑定多个学员（多孩） |
| 家长 | 小程序操作者，微信登录主体 |
| 城市 | 学员所在城市，决定可报课程和活动范围 |
| 年级 | 学员当前就读年级，与城市共同决定后台配置维度 |
| TMS | 顾问端管理系统，可生码让家长扫码支付 |
| 成单人 | 促成订单成交的归属人（顾问或家长自主） |
| 追随 | 学员从上一季续报到下一季的报名行为 |
§2 身份体系与登录规则
2.1 登录方式
微信一键登录（手机号快捷登录），获取 unionId 实现多端打通。
2.2 登录态持久化
- Token 存储在本地 Storage，每次启动校验有效性
- Token 过期后静默刷新，刷新失败则引导重新登录
- 退出登录清除 Token 和本地缓存的学员信息
2.3 登录拦截规则
| 场景 | 是否拦截 |
|---|
| 浏览首页/选课列表 | 不拦截，允许游客浏览 |
| 加入购物车 | 拦截，拉起登录 |
| 进入购物车/下单/支付 | 拦截 |
| 查看我的订单/个人中心 | 拦截 |
| 切换学员 | 拦截 |
| 查看课程详情 | 不拦截 |
| 点击专属顾问 | 不拦截（跳转企微） |
| 分享页面 | 不拦截 |
2.4 多孩关系
- 一个家长（微信账号）可绑定多个学员
- 切换学员后，全局「城市+年级」随之变更，所有页面数据刷新
- 学员上限：[待确认]
2.5 城市初始化规则
首页初始城市确定规则（终端 × 登录态）
| 终端 | 已登录 + 已绑学员 | 已登录 + 未绑学员 | 未登录 |
|---|
| 卓越悦学（广州） | 读取学员所属城市 | 定位成功→定位城市；失败/拒绝→默认广州 | 定位成功→定位城市；失败/拒绝→默认广州 |
| 卓越优学（深圳） | 锁定深圳 | 锁定深圳 | 锁定深圳 |
用户手动切换城市后，本地存储锁定，冷启动后仍优先使用用户上次手动选择的城市（优先级：手动选择 > 学员城市 > 定位 > 默认广州）。
年级默认值
| 状态 | 默认年级 |
|---|
| 已登录 + 已绑学员 | 读取学员绑定年级 |
| 已登录 + 未绑学员 | 默认高一 |
| 未登录 | 默认高一 |
2.6 网报内部跳转免登录 一期
网报小程序跳转以下目标时基于统一登录态免登录打开（2026-07-22 确认口径）：
| 跳转路径 | 状态 |
|---|
| 网报小程序 → 网报小程序 | ✅ 已实现 |
| 网报小程序 → 入学诊断 | ✅ 已实现 |
| 网报小程序 → 调课、转班、课表 | ⚠️ 需复测（小程序上暂无入口，可先挂入口） |
| 网报小程序 → 转介绍 H5 | ✅ 已实现 |
跨小程序静默登录（如跳转拼团、希望之星）不在一期/二期范围，需目标小程序改造对接后另行排期。
§3 数据规则通则
3.1 配置维度
所有按城市+年级配置的模块，其内容展示由后台按「城市 + 年级」维度配置决定。
3.2 刷新时机
以下任一动作触发当前页面全部模块按新的「城市 + 年级」重新加载：
- 切换学员（多孩切换）
- 手动切换年级
- 手动切换城市
- 下拉刷新
3.3 缓存策略
- 各页面模块不做本地缓存，每次触发刷新动作均实时请求接口获取最新数据
- 各模块如有特殊缓存需求，在对应模块 PRD 中单独标注
3.4 分页规则
| 页面/模块 | 分页策略 |
|---|
| 首页各模块 | 一次性全量加载，无分页、无"加载更多" |
| 选课列表/班级列表 | 分页加载（下拉触底加载更多） |
| 我的订单列表 | 分页加载 |
| 其他列表类 | 默认分页，具体在对应模块标注 |
3.5 排序通则
除各模块另有标注外，展示顺序统一按后台配置顺序排列（从上到下/从左到右）。列表类页面的排序规则在各模块 PRD 中定义。
3.6 数量限制通则
除各模块另有标注外，数据量由后台配置决定（后台配几个展示几个），无前端硬编码上限。
§4 状态通则
4.1 登录态×数据态矩阵
| 状态组合 | 通用表现 |
|---|
| 已登录 + 有数据 | 正常展示模块 |
| 已登录 + 无数据 | 隐藏该模块（不占位） |
| 未登录 + 有数据 | 正常展示（交互可能触发登录拦截） |
| 未登录 + 无数据 | 隐藏该模块 |
| 服务降级 | 隐藏该模块 |
各模块如有例外（如始终展示、占位显示等），在模块 PRD 中单独说明。
4.2 空状态
| 场景 | 表现 |
|---|
| 列表为空（如订单、购物车） | 展示空状态插图 + 引导文案 |
| 模块无数据（首页子模块） | 隐藏模块，不占位 |
| 搜索无结果 | 展示"暂无搜索结果"空状态页 |
4.3 显示开关
后台可配置模块级显示/隐藏开关，关闭后前端直接不渲染该模块。
§5 交互通则
5.1 加载态
| 场景 | 表现 |
|---|
| 页面首次打开 | 全局 loading 动画（居中旋转），接口并行请求，全部完成后统一渲染 |
| 下拉刷新 | 自定义下拉动画，刷新完成后动画收起 |
| 切换学员/年级/城市 | 全局 loading 遮罩，数据刷新完毕后关闭 |
| 按钮提交（下单/支付） | 按钮置灰 + loading 状态，防重复提交 |
- 无骨架屏设计，不做模块级占位渲染
- 首次加载期间用户不可交互（loading 遮罩阻断）
5.2 Toast
- 操作成功/失败的轻提示，居中显示，1.5s 后自动消失
- 不阻断用户操作
5.3 弹窗层级
| 层级 | 类型 |
|---|
| 最高 | 系统授权弹窗（微信原生） |
| 高 | 营销弹窗、强制更新弹窗 |
| 中 | 业务确认弹窗（删除、取消订单等） |
| 低 | 底部弹出面板（筛选、选择器） |
同一层级弹窗不叠加，后来的排队等待。
5.4 页面跳转
- 同小程序内页面：使用 navigateTo（保留返回栈）
- Tab 页切换：使用 switchTab
- H5 页面：使用 web-view 组件（仅支持 HTTPS，域名需在小程序管理后台配置业务域名白名单）
- 跳转外部小程序：使用 navigateToMiniProgram（无需提前关联，微信会弹窗要求用户确认）
- 跳转关联公众号文章：web-view 直接打开已关联公众号的文章链接（支持非同主体，需完成关联配置；无需配置业务域名）
- 返回：navigateBack
5.5 手势
- 全局支持下拉刷新
- 列表页支持上拉加载更多（分页场景）
- 左滑返回：系统默认行为，不拦截
5.6 防重复提交
- 提交类按钮（下单、支付、加入购物车）点击后立即置灰 + loading
- 接口返回前不可再次点击
- 接口报错后恢复按钮可点状态
5.7 全局返回规则 一期
所有页面返回（导航栏返回箭头 / 物理返回 / 左滑返回）统一遵循：从哪个页面进入，即返回到哪个页面（按页面栈原路返回，不做跨层跳转）。
| 示例场景 | 正确返回行为 |
|---|
| 购物车 → 课程详情 → 点击返回 | 返回购物车（而非班次列表） |
| 选课列表 → 班次列表 → 课程详情 → 返回 | 逐级返回：课程详情 → 班次列表 → 选课列表 |
| 分享链接直接进入课程详情 → 返回 | 无上级页面栈时返回小程序首页 |
2026-07-26 修订：旧版小程序存在返回链路错误（如从购物车进入课程详情后返回却进了班次列表），新版统一按本规则实现，原有与本规则冲突的返回链路描述一律以本节为准。
§6 异常与兜底通则
6.1 网络异常
| 场景 | 处理方式 |
|---|
| 全页无网络 | 展示全局网络异常页（含重试按钮） |
| 接口异常统一 Toast 文案 | 统一使用"网络异常，请重试"（2026-07-28 测试评审确认，全端公用） |
| 下拉刷新失败 | Toast 提示"刷新失败，请重试"，保留当前数据 |
| 加载更多失败 | Toast 提示，保留已加载数据，可重试 |
6.2 接口报错
| 场景 | 处理方式 |
|---|
| 单模块接口超时/报错 | 隐藏该模块，不展示错误提示（静默降级） |
| 关键接口失败（登录/支付） | 展示错误弹窗，引导重试 |
| 全部接口失败 | 展示全局异常页 |
6.3 图片加载失败
显示默认占位色块（不显示裂图图标）。
6.4 文本超长
单行截断 + 省略号（各模块内有特殊规则的另行标注）。
6.5 排队页
高并发场景下展示排队等候页面，含预估等待时间和自动重试机制。
各模块如有特殊异常处理（与通则不同），在该模块 PRD 的「异常与兜底」中单独说明。
§7 埋点通则
7.1 埋点工具
神策数据（Sensors Analytics）SDK 接入。
7.2 通用事件
| 事件类型 | 事件名 | 说明 |
|---|
| 页面浏览 | $PageView | 所有页面自动采集 |
| 元素点击 | $Click | 可交互元素自动采集 |
| 小程序启动 | $MPLaunch | 含场景值、来源参数 |
| 小程序退出 | $MPHide | — |
7.3 各模块埋点方式
- 各模块 PRD 中按需定义业务自定义事件
- 命名规范：
模块名_动作名（如 home_banner_click）
- 通用属性：城市、年级、学员ID、登录态
§8 技术约束
8.1 性能指标
| 指标 | 目标 |
|---|
| 首页首屏时间 | ≤ 1.5s |
| 页面切换响应 | ≤ 300ms |
| 接口超时阈值 | 10s |
8.2 兼容性
- 微信版本：≥ 7.0.0
- 基础库版本：≥ 2.25.0
- 适配机型：iPhone 6s 及以上、主流 Android 机型
8.3 安全与隐私
- 敏感信息（手机号、姓名）脱敏展示
- 接口通信 HTTPS
- 用户隐私协议授权前置
8.4 灰度与回切
- 支持按城市/用户比例灰度发布
- 异常时可快速回切至 H5 版本
§9 双端差异矩阵
卓越悦学与卓越优学在城市、课程、配置维度存在显著差异，本节统一汇总两端差异点，作为各业务模块差异化处理的总入口。
| 功能维度 | 卓越悦学 | 卓越优学 |
|---|
| 城市切换 | 支持多城市切换，后台可配 | 固定锁定深圳，不可切换 |
| 课程展示 | 按所选城市 + 年级展示 | 仅展示深圳课程 |
| 金刚区入口 | 按城市 + 年级配置 | 按深圳 + 年级配置 |
| 转介绍入口 | 有 | 有 |
| 入学诊断入口 | 有 | 有 |
| 专属顾问 | 按城市 + 年级配置 | 仅深圳维度 |
本节为双端差异总览，各模块如有更细化的差异规则，需在对应模块 PRD 中单独标注，并保持与本矩阵一致。
修订记录（V1.1 / 2026-07-28）
| 修订项 | 修订内容 | 期数 | 依据来源 | 日期 |
|---|
| 全局返回规则 | 新增 §5.7：从哪个页面进入即返回到哪个页面（按页面栈原路返回），替代旧版错误返回链路 | 一期 | 改动汇总 12.3 | 2026-07-26 |
| 网报内部跳转免登录 | 新增 §2.6：网报→网报、→入学诊断、→调课转班课表、→转介绍H5 免登录状态表 | 一期 | 改动汇总 5.7 | 2026-07-26 |
| 统一异常 Toast 文案 | §6.1 新增：接口异常统一 Toast 文案"网络异常，请重试"，全端公用 | 一期 | 2026-07-28 测试评审会 | 2026-07-28 |
期数徽标说明：一期 二期 三期，仅标注本次修订涉及内容。