xiaoshu-app

小树陪练 Angular 多项目工作区

这是从同级 xiaoshu-uniapp 迁移出的 Angular 18 工作区。移动端与运营管理后台是两个物理隔离、可独立构建和发布的 Angular 应用：

• projects/xiaoshu-mobile：学生端与老师端，根据登录身份展示对应业务能力。
• projects/xiaoshu-admin：运营管理后台与仅超级管理员可见的技术后台。

两个应用拥有独立入口、路由、测试配置、开发端口和构建产物，不会把另一端的业务源码打进自己的前端包。

环境

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

本地运行

npm install
npm run start:mobile
npm run start:admin

移动端运行在 http://127.0.0.1:4200/，管理后台运行在 http://127.0.0.1:4300/admin/login。两个开发服务器都通过 proxy.conf.cjs 转发所需服务，避免本地调试时的跨域问题。

AI 阅读统一通过生产云函数调用生成服务，本地 Angular 进程不需要、也不应持有生成服务令牌。首次部署服务端配置时执行：

XIAOSHU_MASTER_KEY="..." FMODE_API_TOKEN="..." npm run reading:ai:configure
npm run cloud:deploy -- --only=xiaoshu/app/gateway

构建与测试

npm run build
npm run test:ci

也可以分别执行：

npm run build:mobile
npm run build:admin
npm run test:mobile:ci
npm run test:admin:ci

移动端输出到 dist/xiaoshu-mobile/browser/，管理后台输出到 dist/xiaoshu-admin/browser/。两个站点部署时都需要把各自的 Angular 路由回退到对应的 index.html。

管理端发布包使用 npm run release:admin:prepare 生成，要求已跟踪的修改先提交。输出位于 dist/admin-release/，包含静态站点、带源码提交号的版本清单、每个文件的 SHA-256 和压缩包校验和。压缩包只包含前端构建，不包含云函数、数据库备份或服务端密钥。

上传 site/ 内容到现有后台站点时，先上传资源文件，最后更新 index.html；保留旧的哈希资源，避免已打开的页面找不到旧脚本。上传完成后执行 npm run release:admin:verify，核对 https://admin.xiaoshu.pro 的版本、全部文件及 /admin/login、/admin/payroll 深层路由。其他核验地址通过 XIAOSHU_ADMIN_URL 指定。准备和核验命令均不会上传文件或修改线上配置。

当前公网后台直接调用 https://server.xiaoshu.pro/api/functions，仅本地开发使用代理。前端上传需要独立的站点托管权限；XIAOSHU_MASTER_KEY 不具备该权限，不能放入前端配置或发布包。

迁移验收

• 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 阅读的身份、文章、题目、答案、成绩和历史记录只由 server.xiaoshu.pro 的阅读云函数处理；生成所需的单词、年级、题材和提示词由该云函数转发至 api.fmode.cn。生成服务令牌与 Parse masterKey 只保留在服务端，不存放在前端源码、Angular 代理或浏览器存储中。
• 上述流程已根据 2026-08-08 的明确授权启用。应用不会在该流程中自行向其他 NCloud 域名提交账号或密码。

生产部署需要配置 xiaoshu/app/gateway 云函数及 Parse Config 中的生成服务令牌；不要把 FMODE_API_TOKEN 或 Parse masterKey 写进 Angular 环境文件、反向代理或浏览器构建产物。

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

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