# 知了数学 · 小程序

`math.client-pc` 的教师工作台小程序，使用 Taro 4、React 18、TypeScript、Vite 和 SCSS。此目录为独立 Git 仓库，使用 pnpm 管理依赖。

当前仅实现首页和「我的」页面，所有环境均使用虚构的本地演示数据，不调用后端、不读取或上传文件、不播放真实视频。上传入口、消息、题目讲解、账号信息、密码校验与退出/重新进入演示账号支持本地交互；退出不代表真实鉴权。

## 安装与预览

要求 Node.js 22.18+、pnpm 10.34.9（已在 `packageManager` 中固定）。React 18 为当前 Taro 官方插件支持的版本，未沿用 PC 端的 React 19。

```powershell
pnpm install --frozen-lockfile
pnpm dev
```

如果本机全局 pnpm 不是 10.34.9，可将命令前缀换成 `npx --yes pnpm@10.34.9`，例如 `npx --yes pnpm@10.34.9 dev`，无需改动全局安装。

先执行 `pnpm dev` 完成首次编译，再在微信开发者工具中直接导入 **`math.miniapp` 根目录**。根目录的 `project.config.json` 已将 `miniprogramRoot` 设为 `dist/`，修改源码后会自动重新编译。`pnpm build:dev` 可生成一次性的开发环境产物。

默认 `touristappid` 用于本地预览；需要真机或正式上传时，在微信开发者工具中使用自己的公开 AppID，不在本项目填写 AppSecret。也支持单独导入 `dist/`，该目录的工程配置可用进程环境变量覆盖 AppID：

```powershell
$env:TARO_APP_ID = '你的小程序AppID'
pnpm build:test
```

浏览器辅助预览：`pnpm dev:h5`，访问 `http://127.0.0.1:10086`。H5 用于快速查看布局与交互，微信端效果仍需在开发者工具及真机上确认。构建命令只编译本地文件，不会上传或发布小程序。

## 三套打包环境

| 环境 | 打包命令 | 产物目录 |
| --- | --- | --- |
| 开发 | `pnpm build:dev` | `dist/` |
| 测试 | `pnpm build:test` | `dist/` |
| 正式 | `pnpm build:production`（或 `pnpm build`） | `dist/` |

`pnpm build:all` 依次构建开发、测试、正式环境，最终 `dist/` 保留正式环境产物。测试环境监听构建使用 `pnpm dev:test`。切换环境前请先停止正在运行的监听构建，避免不同命令同时写入 `dist/`。需要恢复开发环境时运行 `pnpm dev` 或 `pnpm build:dev`。

H5 开发环境静态打包使用 `pnpm build:h5`，产物单独保存到 `dist-h5/`，避免覆盖小程序产物。

业务环境由构建命令选择，脚本显式传递 `--mode development/test/production`，由 Taro 加载对应的 `.env.*` 文件，并设置 `APP_ENV`。所有一次性打包均使用 `NODE_ENV=production` 优化，避免将 React 的构建模式和业务测试环境混用。三个环境共用 `dist/`，后一次构建覆盖前一次，微信开发者工具运行的是最近一次构建的环境。

`dist/build-info.json` 包含当前产物的环境、平台、版本、数据来源和构建时间；单独导入 `dist/` 时微信工程名称也带环境后缀。所有环境的页面顶部均不显示环境标记；「关于」页可以查看环境和版本。三套环境目前都不含 API 地址，未来接接口时再分别添加公开配置，不能把密钥编译进前端。

根目录 `project.config.json` 用于直接导入仓库，同时作为产物工程配置的模板；构建生成的 `dist/project.config.json` 将 `miniprogramRoot` 设为 `./`，也可直接导入。`TARO_APP_ID` 仅覆盖产物工程配置，不改写根目录配置。不同 AppID 不是区分环境的必要条件，微信体验版/正式版发布状态与业务环境是两个概念。

## 环境变量

| 文件 | 用途 | 提交 Git |
| --- | --- | --- |
| `.env.development` | 开发环境的公开值 | 是 |
| `.env.test` | 测试环境的公开值 | 是 |
| `.env.production` | 正式环境的公开值 | 是 |
| `.env` / `.env.local` | 可选的公共默认值 / 个人默认值 | 否 |
| `.env.<mode>.local` | 某个环境的个人覆盖值 | 否 |

同名变量的优先级从高到低：进程环境变量 → `.env.<mode>.local` → `.env.<mode>` → `.env.local` → `.env`。每个模式在独立构建进程中加载，`build:all` 不会沿用上一个环境文件的值。修改环境文件后需重启监听构建。

`.env` 文件格式本身不限制变量名前缀，但本项目使用 Taro 默认加载规则，自动加载并注入前端的自定义变量必须以完整的 `TARO_APP_` 开头，单独的 `TARO_` 前缀不够。任意名称的变量不会自动加载到业务代码；系统进程变量和框架内置变量另有用途。

例如，在本地 `.env` 中定义所有环境共用的公开变量（此文件不提交 Git）：

```dotenv
TARO_APP_APP_NAME=知了数学
```

在业务代码中可直接读取：

```ts
const appName = process.env.TARO_APP_APP_NAME
```

请使用完整的 `process.env.TARO_APP_XXX` 表达式，避免解构或动态键读取。同名值若存在于 `.env.development` 等优先级更高的文件中，将覆盖 `.env`，空字符串也会覆盖；需要使用公共默认值时，移除环境文件中的同名项。

三个环境文件已包含：

```dotenv
TARO_APP_ENV_LABEL=开发环境
TARO_APP_API_BASE_URL=
TARO_APP_ENABLE_DEBUG=true
TARO_APP_ID=touristappid
```

环境名称和调试开关分别按环境填写；接口地址目前留空，仍然只运行本地演示，不发请求。`TARO_APP_ENABLE_DEBUG` 必须为 `true` 或 `false`，不会自动打开调试工具。`TARO_APP_ID` 默认为游客 AppID；需要个人覆盖时在 `.env.development.local` 等文件中填写。

业务代码统一读取经过类型转换的配置：

```ts
import { appConfig } from '@/config/environment'

const apiBaseUrl = appConfig.apiBaseUrl
const enableDebug = appConfig.enableDebug // boolean
```

新增变量时，共用默认值放在本地 `.env`，不同环境的值放在对应 `.env.*`，并同步维护本节变量说明。需要统一暴露给业务代码的变量，更新 `types/global.d.ts` 的类型声明及 `src/config/environment.ts` 的读取/转换。需要构建时校验的变量同步维护 `config/environments.ts` 中的 `readPublicConfig`。不要在 TypeScript 中再硬编码三套环境值。Taro 以字符串注入环境变量，数字、布尔值需显式转换。

`src/config/environment.ts` 仍作为统一的类型化读取入口，「关于」页面正在使用它；它还负责将 `TARO_APP_ENABLE_DEBUG` 转换为布尔值。环境值来自 `.env.*`，这个文件不再维护三套配置。项目不保留额外的环境示例模板，变量说明直接维护在 README 和三套公开环境文件中。

`TARO_APP_` 变量会打进前端包，只存放公开配置，不包含密钥。`APP_ENV`、`NODE_ENV` 由脚本控制，不在环境文件中设置。

## 验证

```powershell
pnpm typecheck
pnpm lint
pnpm test
pnpm build:all
pnpm test
pnpm build:h5
pnpm test:e2e
```

单元测试覆盖环境校验、模式文件加载、个人与进程覆盖优先级、布尔值转换、统一输出目录、根目录导入配置、错误命令和当前产物的实际编译变量；可通过 `EXPECTED_APP_ENV` 指定产物应有的环境。E2E 使用本机 Chrome，覆盖 390px/320px 两种视口、两页导航、本地弹层、密码演示、退出与重新进入，并检查无业务 API 请求。未安装 Chrome 时需先安装，或修改 Playwright 的浏览器配置。

## 目录约定

- `src/pages`：首页和个人页；`src/components`：公共弹层、安全区和环境标记。
- `src/data`：本地演示数据及演示登录态，仅存内存，刷新恢复初始数据。
- `config`、`scripts`：环境与跨平台构建入口。
- `tests`：环境回归与浏览器交互验证。

品牌 Logo 复用工作区 `math.client-pc/public/logo.png` 的副本；底部导航和通知铃铛 PNG 图标由本项目绘制，通知图标可运行 `scripts/create-notification-icon.ps1` 重新生成。未引入 PC 端的 Electron、Ant Design 或 API 依赖。