xiaoshu-app

小树陪练 Angular H5

这是从同级 xiaoshu-uniapp 迁移出的 Angular 18 Web/H5 项目。项目保留原有 95 条业务路由，并使用 Angular Router、Signals、HttpClient 与独立组件重新实现登录、学习、复习、测试、游戏、商城、支付、订单、团队、商户、表单与会员业务。

环境

• Node.js 18.19+（当前验证版本为 Node.js 22）
• npm 9+
• Angular 18.2

本地运行

npm install
npm start -- --host 127.0.0.1 --port 4201

浏览器打开 http://127.0.0.1:4201/。开发服务器通过 proxy.conf.cjs 将 /backend 转发到线上 UniApp 当前使用的 https://test.fmode.cn/engxs，并将客服、NCloud 与 AI 请求转发到对应服务，避免本地 H5 调试时的跨域问题。

AI 阅读需要在启动进程中提供服务端环境变量，令牌不会进入浏览器构建产物：

FMODE_API_TOKEN="你的令牌" npm start -- --host 127.0.0.1 --port 4201

构建与测试

npm run build
npm run test:ci

生产文件输出到 dist/xiaoshu-angular/browser/。部署时需要把 Angular 路由回退到 index.html，并确认原后端允许生产域名跨域；也可以在 Web 服务器上继续反向代理 /backend。

迁移验收

• pages.json 中 95/95 条路由已注册，路径保持不变。
• 生成的源码对照清单跟踪 91 个字面 API 动作及 Bytedesk httpApi.* 外部业务调用，npm run parity:check 可检测源页面变化。
• 原生微信授权接口 user_sync2 依赖 uni-app/微信容器，H5 改用短信登录、账号密码登录与注册。
• 收货地址、发票、商品、库存、结算、发货、售后、订单评价、提现账户、实名认证和反馈均保留原后端载荷格式。
• 生产构建通过，页面按路由懒加载；45 项自动测试覆盖路由对照、业务载荷、表单载荷、Bytedesk 会话/评价/留言协议、外部阅读参数和会员权益统计。
• 公开页已在 390 x 844 与 1440 x 900 视口回归，无横向溢出或 Angular 运行时错误；未登录访问受保护页面会保留 returnUrl 并跳转登录页。
• 客服页已迁移原 UniApp 使用的 Bytedesk 匿名访客登录、工作组会话、历史消息轮询、智能客服问答、图片上传与文件上传协议。2026-08-08 实测发现 uniapp.bytedesk.com 已停用原 /visitor/api/* 接口并改为返回微语官网 HTML，因此旧 UniApp 与迁移页目前都无法建立真实会话；页面会明确显示旧服务已停用。
• 满意度评价与离线留言不再复用业务留言表单，分别保持原 /api/rate/detail、/api/rate/do、/api/leavemsg/save 协议及 tid/wid/aid/type/invite 会话参数；旧 Bytedesk 服务停用时会显示真实错误。
• 用户中心和游戏中心入口按当前 UniApp 模板恢复：用户中心只显示源页面实际开放的服务，游戏中心四个年级入口继续提示“正在开发中”。
• 页面会区分“没有业务数据”和“接口加载失败”；依赖订单或详情上下文的表单缺少 id 时禁止提交并提示从正确入口进入。
• 学习记录中的“阅读”入口已完整内置：从记录 xxqs 提取单词后进入 Angular 阅读设置、AI 文章生成、词汇补全、选择题、历史成绩和 PDF 导出页面，不再加载 app.fmode.cn iframe。
• 旧入口 /pages/iframe/index 保留参数兼容，原 params 中的单词列表与 NCloud 会话会被内部页面接收。
• 独立项目原首页迁移到 /english：生词阅读入口可用，“外文源刊解析”和“智慧陪读陪练”继续按源代码显示“暂未开放”。
• 阅读业务保持源仓库规则：原默认参数、随机题材与类型、相同词汇三篇上限、重复文章判断、120/180 秒任务超时、最多五次重试、最近答题恢复、题目与选项洗牌、成绩记录、10 条历史分页、满分后新文章和微信 PDF 提示均已迁移。

涉及支付、短信、上传、写入和登录后数据的真实联调，需要有效测试账号及可用的后端业务数据。自动测试使用模拟会话和模拟 API，避免在验收中产生真实订单、短信或数据变更。

原排行榜动态调用的 ranklist_1 至 ranklist_5 在当前后端返回“接口不存在”，H5 保留原请求并显示空状态。

第三方数据边界

• 客服迁移代码仅允许向 uniapp.bytedesk.com、upload.bytedesk.com 发送聊天内容和所选附件。当前匿名会话握手会因旧接口下线而中止，不会继续发送聊天或上传文件。
• AI 阅读将手机号、昵称、NCloud 登录凭据、文章、题目、答案、成绩和历史记录发送至 server.xiaoshu.pro，并将单词列表、年级、题材、文章及提示词发送至 api.fmode.cn。AI 密钥与 Parse masterKey 只保留在服务端，不存放在前端源码或浏览器存储中。
• 上述流程已根据 2026-08-08 的明确授权启用。应用不会在该流程中自行向其他 NCloud 域名提交账号或密码。

生产部署必须配置 /fmode-api 到 https://api.fmode.cn 的服务端反向代理并注入授权头，同时配置 /ncloud 到 https://server.xiaoshu.pro/parse；不要把 FMODE_API_TOKEN 或 Parse masterKey 写进 Angular 环境文件。

为避免扩大私有数据读取范围，迁移版在两处保留了比源仓库更严格的限制：答题记录始终限定当前用户，PDF 页面继续要求当前应用登录；源仓库中未带用户条件的历史查询和公开 PDF ID 读取没有照搬。H5 目标也不再执行原 iframe 中仅供 APP-PLUS 使用的 uni.postMessage PDF 回传。

恢复客服需要在新版微语后台取得新的 org、sid，并另行授权新版 H5 客服实际使用的域名；当前官方接入格式已不再使用旧版 subDomain、workGroupId。