# 小树陪练 Angular 多项目工作区

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

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

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

## 环境

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

## 本地运行

```bash
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 进程不需要、也不应持有生成服务令牌。首次部署服务端配置时执行：

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

## 构建与测试

```bash
npm run build
npm run test:ci
```

也可以分别执行：

```bash
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`。