# 食品添加剂侦探课程

「零食侦探事务所」主题的食品添加剂网络课程。学生以实习侦探身份，围绕一段关于零食添加剂的网络舆论展开探案式学习，在「接收线索 → 开展调查 → 获取证据 → 作出判定」的流程中，逐步建立对食品添加剂的科学认知。

课程面向易班 H5 平台交付，按 1920×1080 设计稿开发，整体等比缩放适配 PC 与移动端横屏。

## 课程概要

### 学习路径

学生首次学习沿剧情主线推进，完成每个阶段的调查任务即可积累经验、提升侦探等级：

```text
实习侦探（序幕）
  ↓
助理侦探（第一幕）
  ↓
初级侦探（第二幕）
  ↓
中级侦探（第三幕）
  ↓
高级侦探（第四幕）
  ↓
食安神探（终章 · 零食风暴）
```

### 四条调查线

序幕从前情舆论视频切入，学生从求助信中梳理出四条调查线索，分别对应四幕核心案件：

| 案件 | 调查线 | 待核验说法 | 核心问题 |
| --- | --- | --- | --- |
| 🌈 色彩迷局 | 着色剂身份线 / 来源辨析线 | 「颜色这么鲜艳，色素肯定没少加」 | 食品里的「色素」是什么？天然与人工合成能直接代表安全吗？ |
| 🍊 味觉密码 | 香精与风味线 | 「水果味都是香精调出来的」 | 食品的香气从哪里来？香精的使用是否有据可依？ |
| 🍮 Q 弹真相 | 增稠剂线 | 「果冻 Q 弹是因为加了很多胶」 | 「胶」是什么？增稠剂在食品中起什么作用？ |
| ⏳ 保鲜疑云 | 防腐剂线 | 「面包放得久是因为防腐剂多」 | 防腐剂为什么被使用？如何判断其安全性？ |

每条调查线统一遵循五步调查轨迹：**待核验说法 → 调查问题 → 探查方式 → 关键证据 → 调查判定**。

### 核心教学要点

- **着色剂**：赋予或改善食品色泽的一类食品添加剂；食品有颜色不等于额外加入了着色剂，颜色鲜艳也不代表用量多。
- **身份核验**：能染色 ≠ 可作为食品着色剂。苏丹红是工业染料、非法添加物，不属于食品着色剂；胭脂红、栀子黄等才具有食品着色剂身份。
- **天然 vs 人工合成**：两者首先反映的是来源与获得方式不同，不能直接等同于「安全」与「有害」；无论哪种来源，都要结合具体物质、食品类别及相应标准判断。
- **铝色淀**：把水溶性着色剂转变为水不溶性着色形态，满足彩色糖衣、蛋糕装饰等不掉色、不迁移的加工需要。
- **国标意识**：GB 2760-2024《食品安全国家标准 食品添加剂使用标准》对每种允许使用的添加剂的适用食品类别、最大使用量、使用范围均有严格规定。

### 案件档案与学习资源

课程把调查过程中产生和解锁的内容沉淀为「零食侦探事务所」资源清单，首次学习沿剧情推进，完成后可脱离剧情顺序回看复习：

| 分类 | 功能定位 |
| --- | --- |
| 01 物证材料 | 案件调查的原始物证，调查的事实起点 |
| 02 收件箱 | 市民求助、补充线索及后续来信 |
| 03 调查资料 | 科普动画、微课、案例短片、旧案资料，承担主要知识讲解 |
| 04 调查成果 | 学生实际完成过的调查操作及判断记录 |
| 05 添加剂档案 | 持续积累的食品添加剂知识库，学一个解锁一个 |
| 06 国标档案 | 培养「遇到添加剂问题查标准」的意识，提供标准依据 |
| 07 案件线索板 | 剧情导航与学习进度导航，首页常驻入口 |
| 08 调查报告 | 对一幕中多条调查线的最终汇总与消费建议 |
| 09 侦探等级 | 学习者身份与整体课程成长记录 |

## 技术栈

- React 19 + TypeScript
- Vite 8 开发与构建
- React Router 7 路由管理（Hash 路由 + 懒加载）
- Tailwind CSS 4 原子化样式
- Zustand 轻量状态管理
- GSAP + @gsap/react 动效
- dnd-kit 拖拽交互
- Biome 代码格式化与检查
- Husky + lint-staged 提交前检查
- 1920×1080 整体缩放适配
- 横屏访问提示
- vconsole 移动端调试（仅开发环境）
- 易班 videoajax.js 封装与用户信息状态管理

## 开发命令

```bash
bun install        # 安装依赖
bun dev            # 启动开发服务器
bun run build      # 类型检查并构建生产版本
bun run preview    # 预览生产构建
bun run lint       # 代码检查
bun run lint:fix   # 自动修复代码问题
```

修改代码后至少运行 `bun run lint`；涉及路由、构建配置、页面结构或类型系统的改动，同时运行 `bun run build`。

## 应用配置

页面标题、描述、图标、课程标识和 viewport 统一维护在 [src/app.config.ts](src/app.config.ts)。修改后需重启开发服务。

## 目录结构

```text
src/
├── api/                   # API 请求封装
├── assets/                # 静态资源
│   └── images/            # 课程切图（按页面分子目录）
├── components/
│   ├── business/          # 业务组合组件
│   ├── common/            # 通用组件（Button、Overlay、Portal、Toast、ImageButton 等）
│   ├── course-interactions/ # 课程交互（GuideDialog、GuideSpotlight、DragDrop）
│   └── ui/                # 基础 UI 组件
├── course-runtime/        # 固定课程画布运行时（缩放、横屏守护）
├── lib/cn.ts              # class 合并工具
├── pages/                 # 页面组件
├── router/                # 路由配置
├── stores/                # Zustand 状态管理
├── styles/                # 全局样式
├── types/                 # 跨模块共享类型
└── utils/                 # 工具函数（assets、motion、yiban、lazyRoute 等）
```

完整开发规范见 [CLAUDE.md](CLAUDE.md)。

## 课程交互能力

项目内置一套课程交互能力，用于支撑探案式学习中的对话、引导、拖拽、弹层等场景。这些源码直接维护在当前仓库，可按需修改。

### 引导聚光灯 SpotlightGuide

适合课程首次学习时突出关键操作区域。在元素上标注 `data-guide`，在页面初始化时启动引导：

```tsx
import { useEffect } from "react";
import { GuideSpotlight } from "@/components/common";
import { useSpotlightStore } from "@/stores";

export default function LessonPage() {
	useEffect(() => {
		useSpotlightStore.getState().startSpotlight({
			courseId: "color-mystery",
			spotlightId: "intro",
			steps: [
				{
					id: "start",
					target: { dataGuide: "start-button" },
					title: "开始调查",
					description: "点击这里开始第一幕调查。",
					placement: "bottom",
					allowTargetClick: true,
				},
			],
		});
	}, []);

	return (
		<>
			<button data-guide="start-button">立即立案</button>
			<GuideSpotlight />
		</>
	);
}
```

- `target` 支持 CSS selector 或 `{ dataGuide: "xxx" }`。
- `placement`：`top` / `bottom` / `left` / `right` / `auto`。
- `allowTargetClick`：让高亮区域下方的真实元素可被点击，但不会自动切换步骤，需在业务点击逻辑中手动调用 `nextStep` / `finishSpotlight` / `closeSpotlight`。
- 同一 `courseId + spotlightId` 默认只显示一次（完成或跳过即标记已完成），可用 `resetSpotlight(courseId, spotlightId)` 重新显示。
- 组件内置遮罩淡入、高亮呼吸和提示框入场动画，并兼容系统 `prefers-reduced-motion`。

### 引导对话 GuideDialog

适合在剧情节点弹出侦探助手对话、问题选择等。通过 `defineDialog` 定义、`GuideDialog` 渲染：

```tsx
import { defineDialog, GuideDialog } from "@/components/common";

const dialog = defineDialog({ /* steps, characters, ... */ });

dialog.start();
```

### 拖拽交互 DragDrop

基于 dnd-kit，适合证据分类、调查轨迹排序、选项匹配等交互：

```tsx
import { DragDropProvider, Draggable, Droppable } from "@/components/course-interactions/drag-drop";
import { useCourseCanvas } from "@/course-runtime/canvas";

const { scale } = useCourseCanvas();

<DragDropProvider scale={scale} onDragEnd={(event) => console.log(event.active.id, event.over?.id)}>
	<Draggable id="tartrazine">柠檬黄</Draggable>
	<Droppable id="natural-zone">天然来源</Droppable>
</DragDropProvider>
```

由于画布整体使用 `transform: scale(...)` 缩放，拖拽内容在画布内时建议给 `DragDropProvider` 传入当前 `scale`，避免拖拽元素与手指/鼠标移动不同步。

### 动效 GSAP

项目通过 [src/utils/motion.ts](src/utils/motion.ts) 统一封装 GSAP 入口：`gsap` / `useGSAP` 已注册导出，提供统一缓动常量 `EASE_OUT` / `EASE_IN_OUT`，以及 `useReducedMotion()` 响应 `prefers-reduced-motion` 做动画降级。后续课程页面需要 ScrollTrigger 等插件时，在该文件按需 `registerPlugin`。

```ts
import { gsap, useGSAP, EASE_OUT, useReducedMotion } from "@/utils";
```

### 弹层 Overlay / Portal

`Overlay` 已内置 `Portal`，默认挂载到 App 缩放画布内部，适合课程弹窗跟随画布缩放：

```tsx
import { Overlay } from "@/components/common";

<Overlay
	open={open}
	onClose={() => setOpen(false)}
	backgroundImage="url(./images/dialog-bg.png)"
	backgroundClassName="bg-cover bg-center"
>
	{/* 课程弹层内容 */}
</Overlay>
```

`Portal` 默认挂载到 `document.body`，`Overlay` 默认 `placement="app"`（跟随画布缩放）；也可用 `placement="app"` 或 `container` 自定义挂载位置。挂载优先级：`container` > `placement` > 组件默认值。

### Toast 轻提示

`App` 已默认接入 `ToastProvider` 和 `ToastViewport`，页面中可直接使用：

```tsx
import { useToast } from "@/components/common";

const toast = useToast();
toast.success("证据已收入档案");
toast.error("选择有误，请重新核验");
```

支持 `info` / `success` / `warning` / `error` / `show`。

## 易班平台接入

项目面向易班 H5 / 静态资源相对路径部署，Vite `base` 固定为 `"./"`，确保构建产物在未知子路径或压缩包上传场景下仍能引用资源。

### videoajax.js

已集成易班 [public/videoajax/jquery-3.7.1.min.js](public/videoajax/jquery-3.7.1.min.js) 与 [public/videoajax/videoajax.js](public/videoajax/videoajax.js)，需与构建产物同源、同相对路径部署。若易班平台提供新版本，确认来源、版本和分发权限后再替换，并重新验证用户数据、课程进度、断点和答题记录能力。

### 环境判断

启动时从 URL 读取 `courseId` / `courseid`、`uid`。生产环境中只要存在以上任意参数即视为易班环境。

本地开发即使 URL 带这些参数也默认使用 `sessionStorage`，避免误请求易班接口：

```text
http://localhost:5173/?courseId=123&uid=456
```

本地确需强制走易班接口时追加 `yiban=1`：

```text
http://localhost:5173/?courseId=123&uid=456&yiban=1
```

### 易班能力

```ts
import {
	setUserStorage,
	getUserStorage,
	reportCourseProgress,
	getCourseProgress,
	saveBreakPoint,
	getBreakPoint,
	saveUserAnswer,
} from "@/utils/yiban";
import { useUserStore } from "@/stores";
```

- **存取用户数据**：`setUserStorage(lessonId, key, value)` / `getUserStorage(lessonId, key)`，自动根据易班连接状态选择存储方式。
- **课程进度**：`reportCourseProgress(order)` / `getCourseProgress(order)`。
- **播放断点**：`saveBreakPoint({ userId, courseId, lessonId, breakPoint })` / `getBreakPoint(...)`。
- **答题记录**：`saveUserAnswer({ userId, lessonId, courseId, questionOrder, answer })`。
- **用户状态**：`useUserStore()` 提供 `userId`、`userName`、`setUserInfo`、`setYibanConnectionStatus` 等。

### 移动端调试

开发环境自动启用 vconsole，可在移动端查看 Console、Network、Element、Storage。

## 课程画布适配

按 1920×1080 设计稿开发，由 [src/course-runtime/canvas](src/course-runtime/canvas) 的 `CourseCanvas` 组件承担整体缩放，默认 `width=1920`、`height=1080`、`maxScale=1`。

- PC 端：按可视区域等比缩放并居中。
- 大屏：`maxScale` 默认为 1，不超过设计稿原始尺寸，周围留白。
- 移动端：优先横屏访问，竖屏时由 `OrientationGuard` 显示横屏提示。
- 视口优先读取 `visualViewport`，移动端地址栏显示/隐藏时更稳定。
- 页面内容按设计稿像素开发，不使用 rem 适配。

## 路由

路由集中在 [src/router/index.tsx](src/router/index.tsx)，使用 Hash 路由 + `lazyRoute` 懒加载，新增页面遵循该模式并配 `HydrateFallback: RouteFallback`：

```tsx
{
	path: "about",
	lazy: lazyRoute(() => import("../pages/About")),
	HydrateFallback: RouteFallback,
}
```

页面组件使用默认导出。

## License

MIT