diff --git a/README.en.md b/README.en.md index cdf32c4..cf2fd94 100644 --- a/README.en.md +++ b/README.en.md @@ -1,122 +1,315 @@ -# International Chinese Platform + -International Chinese Platform is a Vue 3 frontend prototype for personalized Chinese-language education. It models course, booking, homework, chat, live-class, and platform-management workflows for students, teachers, and administrators. +
+ International Chinese Platform logo -> This is the canonical repository for ongoing development: -> [computersciencefreshmen/International_Chinese_Platform](https://github.com/computersciencefreshmen/International_Chinese_Platform) +

🌏 International Chinese Platform

+ +

A multi-role teaching workspace for international Chinese education

+

A Vue 3 frontend connecting student learning, teacher workflows, course interaction, live classes, and a digital-human classroom experience.

+ +

+ Features + · + Getting Started + · + 中文 + · + Report an Issue +

+ +

+ + CI + + Vue 3 + Vite 6 + Pinia 2 + Tailwind CSS 3 + pnpm 8.15.9 +

+
+ +--- + +## 📖 Overview + +International Chinese Platform is a multi-role frontend organized around real international Chinese teaching workflows. It is more than a single-page showcase: one Vue 3 application contains separate student, teacher, and administrator workspaces for course discovery, teacher booking, learning requests, homework, dialogue generation, live classes, a digital-human classroom, course uploads, and platform-management views. + +Role-aware routing, persisted client state, and centralized runtime configuration keep browser workflows decoupled from external REST, dialogue-generation, and WebSocket services. The repository works well as an education-product prototype, a frontend/backend integration base, and an evolving portfolio project. + +> [!IMPORTANT] +> This repository contains the frontend only. Production-ready authentication, registration, verification codes, courses, teachers, homework, dialogue generation, and real-time classroom behavior still require external backend, signaling, and media infrastructure. This README distinguishes implemented frontend behavior from service-dependent and prototype functionality. + +## ✨ Project Highlights + +- **Purposeful multi-role structure** — Students, teachers, and administrators have separate layouts, entry points, navigation, and role guards instead of sharing one overloaded dashboard. +- **A broad teaching journey** — Course discovery, teacher booking, learning requests, homework, dialogues, live interaction, and personal settings form a recognizable online teaching flow. +- **Real-time and digital teaching exploration** — Camera, microphone, screen sharing, WebRTC foundations, class-matching animation, and a digital-human classroom prototype are included. +- **Explicit service boundaries** — REST, dialogue-generation, and WebSocket addresses are injected through environment variables with same-origin fallbacks. +- **A maintainable engineering baseline** — pnpm lockfile installs, ESLint, Prettier, production builds, and GitHub Actions create a repeatable quality gate. +- **Auditable repository consolidation** — Useful history from three early repositories is connected through merge commits in this canonical repository. + +## 🎯 Key Features + +### 👨‍🎓 Student Workspace + +- **Course and teacher discovery** — Browse course and teacher views and enter their detail and booking flows. +- **Teacher booking** — Create an appointment, persist it in the browser, and show the latest booking on the student home page. +- **Learning requests** — Capture goals, schedule, and preferences as a request draft that can later be matched with a teacher. +- **Dialogue generation** — Submit keywords to the dedicated dialogue service and display generated practice turns. +- **Homework workspace** — Load homework, save and restore browser drafts, validate answers, and call the submission API. +- **Live and digital-human classes** — Explore live-class media controls, animated class matching, and a digital-human teaching view. +- **Personal center** — Navigate personal information, membership, password, and notification pages. + +### 👩‍🏫 Teacher Workspace -[中文说明](README.md) +- **Teaching dashboard** — Organize teacher home, teaching-coordination, and course-management entry points. +- **Online courses and details** — Browse teacher course views and course-detail flows. +- **Course-upload prototype** — Select course files, validate type and size, preview a cover, and save a browser-local course draft. +- **Teacher account view** — Provide the structure for teacher information and account pages. -## Repository consolidation +### 🧭 Administrator Workspace -Early versions of the project were spread across: +- **Course coordination** — Provide a unified course-coordination entry point. +- **Audit center** — Model a content-review workspace. +- **Data center** — Present an early platform analytics dashboard. +- **Account and notifications** — Include administrator password and notification views. -- [vue3-project-initialization](https://github.com/computersciencefreshmen/vue3-project-initialization) -- [project](https://github.com/computersciencefreshmen/project) +### ⚙️ Platform Capabilities -Development is now consolidated in International_Chinese_Platform. New code, issues, documentation, and releases should use this repository; the older repositories should be treated as historical references to avoid further divergence. +- **Role session and routing guards** — Protect student, teacher, and administrator routes and preserve the original destination across login redirects. +- **Persisted client state** — Use Pinia and its persistence plugin for frontend sessions, student data, and bookings. +- **Centralized networking** — Share Axios timeout, error handling, URL normalization, and environment-aware service addresses. +- **Real-time foundations** — Wrap WebSocket management plus camera, microphone, screen sharing, and WebRTC peer connections. +- **Internationalization foundation** — Integrate Vue i18n and a language selector for future full interface localization. -## Current features +## 👥 Roles and Entry Points -- Student workspace for courses, teacher booking, learning requests, chats, homework, live classes, a digital-human classroom, and personal settings. -- Teacher workspace for teaching coordination, online courses, course uploads, user information, and course details. -- Administrator workspace for course coordination, audits, analytics, and account-center workflows. -- Shared infrastructure using nested Vue Router routes, persisted Pinia state, Element Plus, Tailwind CSS, Axios, and Vue i18n. +| Role | Default entry | Primary tasks | +| ------------- | ------------------------------ | ------------------------------------------------------------------------------------------------- | +| Student | `/student/home` | Courses, booking, learning requests, homework, dialogues, live classes, and digital-human classes | +| Teacher | `/teacher/home` | Teaching coordination, online courses, course uploads, details, and account information | +| Administrator | `/administrator/courseDocking` | Course coordination, audits, analytics, account, and notifications | -This repository is currently a frontend prototype and does not include backend services. Authentication, real-time communication, media signaling, and some business workflows depend on external APIs and require security review and end-to-end integration before production use. +Every protected role route passes through frontend session and role checks. Anonymous visitors return to `/login`; a role mismatch redirects to the current role's default home page. -## Technology +## 🏗️ Architecture -| Layer | Technology | -| ------------------- | ---------------------------------- | -| Framework | Vue 3 | -| Build | Vite 6 | -| Routing | Vue Router | -| State | Pinia, pinia-plugin-persistedstate | -| UI and styling | Element Plus, Tailwind CSS, Sass | -| Networking and i18n | Axios, Vue i18n | -| Quality | ESLint, Prettier, GitHub Actions | +```mermaid +flowchart LR + Login["Login and role selection"] --> Guard["Client session and role guards"] + Guard --> Student["Student workspace"] + Guard --> Teacher["Teacher workspace"] + Guard --> Admin["Administrator workspace"] -## Requirements + Student --> State["Persisted Pinia state"] + Teacher --> State + Admin --> State + + Student --> HTTP["Axios / REST"] + Teacher --> HTTP + Admin --> HTTP + Student --> Realtime["WebSocket / WebRTC"] -- Node.js 18 or newer -- pnpm 8.15.9 + HTTP -. "VITE_API_BASE_URL / VITE_FORUM_API_URL" .-> Services["External backend services"] + Realtime -. "VITE_WEBSOCKET_URL" .-> Services +``` + +`src/config/runtime.js` normalizes service addresses in one place. Without explicit configuration, REST uses the current origin, dialogue generation falls back to `/process_words`, and WebSocket selects `ws://` or `wss://` from the current page. + +## 📊 Capability Maturity + +| Capability | Status | Current boundary | +| ---------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------- | +| Multi-role layouts, routes, and client session | ✅ Implemented | Production identity, authorization, and token lifecycle remain backend responsibilities | +| Booking, homework, and course-upload flows | 🟡 Frontend flow | Booking persists locally; homework depends on APIs; uploads currently save a browser draft | +| Course, teacher, and administration data | 🟡 Mixed | Some views request APIs, while several lists and dashboards still use static or demonstration data | +| Live-class media controls | 🧪 Prototype | Camera, microphone, and screen sharing work; room signaling, TURN, and chat protocols remain incomplete | +| Digital-human classroom | 🧪 Prototype | The current interaction is simulated and is not connected to real AI, ASR, or TTS services | +| Internationalization | 🧪 Foundation | Vue i18n and language selection exist, but most product copy is still Chinese-first | +| Engineering quality gate | ✅ Implemented | CI covers install, ESLint, Prettier, and production build; automated tests remain planned | + +## 🛠️ Technology Stack + +| Layer | Technology | +| ------------------------ | ------------------------------------------------- | +| Frontend | Vue 3.5, Single-File Components | +| Build | Vite 6 | +| Routing | Vue Router 4, lazy nested routes, role guards | +| State | Pinia, pinia-plugin-persistedstate | +| UI and styling | Element Plus, Tailwind CSS 3, PostCSS, Sass | +| Networking and real time | Axios, WebSocket, WebRTC | +| Internationalization | Vue i18n | +| Engineering | pnpm 8.15.9, ESLint 9, Prettier 3, GitHub Actions | + +## 🚀 Getting Started + +### Prerequisites -The pnpm version is pinned in package.json. Use Corepack so a different local pnpm version does not rewrite the lockfile. +- Node.js `>= 18` +- pnpm `8.15.9` (pinned in `package.json`) -## Local development +### 1. Clone the repository ```bash git clone https://github.com/computersciencefreshmen/International_Chinese_Platform.git cd International_Chinese_Platform +``` + +### 2. Install dependencies +```bash corepack enable corepack prepare pnpm@8.15.9 --activate pnpm install --frozen-lockfile +``` +### 3. Configure environment variables + +```bash cp .env.example .env.local -pnpm dev ``` -On Windows PowerShell, copy the environment file with: +Windows PowerShell: ```powershell Copy-Item .env.example .env.local ``` -## Environment variables +Update `.env.local` for your backend and signaling services. -| Variable | Purpose | Example | -| ------------------ | ------------------------------------------ | ----------------------------------- | -| VITE_API_BASE_URL | REST API base URL | http://localhost:7777 | -| VITE_FORUM_API_URL | Full forum/keyword-processing endpoint | http://localhost:5002/process_words | -| VITE_WEBSOCKET_URL | Chat and live-signaling WebSocket endpoint | ws://localhost:7788/websocket | +### 4. Start the development server -Copy .env.example to .env.local and replace the values for your backend. Variables prefixed with VITE\_ are exposed to the browser; never store passwords, private keys, or long-lived access tokens in them. +```bash +pnpm dev +``` + +Open the local URL printed in the terminal, normally `http://localhost:5173`. -The application reads these variables as its shared endpoint contract, avoiding committed environment-specific URLs. +## 🔧 Environment Variables -## Commands +| Variable | Purpose | Code fallback when unset | +| -------------------- | -------------------------------------- | -------------------------------------------------------------- | +| `VITE_API_BASE_URL` | REST API origin | `/` (current site origin) | +| `VITE_FORUM_API_URL` | Full keyword-to-dialogue endpoint | `/process_words` | +| `VITE_WEBSOCKET_URL` | Chat and classroom-signaling WebSocket | Current site's `/websocket`, automatically using `ws` or `wss` | -| Command | Description | -| ----------------- | ------------------------------------------------- | -| pnpm dev | Start the development server | -| pnpm build | Create a production build | -| pnpm preview | Preview the production build locally | -| pnpm lint | Apply auto-fixable ESLint changes | -| pnpm lint:check | Run ESLint without modifying files | -| pnpm format | Format the src directory | -| pnpm format:check | Check src formatting without modifying files | -| pnpm check | Run lint, formatting, and production-build checks | +`.env.example` contains local development examples. Every `VITE_` variable becomes visible in the browser bundle; never store passwords, private keys, or long-lived server secrets in these values. -Before committing, run: +## 📜 Commands + +| Command | Description | +| ------------------- | ------------------------------------------------- | +| `pnpm dev` | Start the Vite development server | +| `pnpm build` | Create a production build in `dist/` | +| `pnpm preview` | Preview the production build locally | +| `pnpm lint` | Apply auto-fixable ESLint changes | +| `pnpm lint:check` | Run ESLint without modifying files | +| `pnpm format` | Format `src/` | +| `pnpm format:check` | Check Prettier formatting in `src/` | +| `pnpm check` | Run lint, formatting, and production-build checks | + +Run before committing: ```bash pnpm check ``` -GitHub Actions runs the same quality gate for pushes to main and pull requests. Automated unit and end-to-end tests are not configured yet, so the critical role-based paths still require browser smoke testing. - -## Project structure +## 📁 Project Structure ```text International_Chinese_Platform/ -├── .github/workflows/ # Continuous integration -├── public/ # Public static assets +├── .github/ +│ └── workflows/ci.yml # GitHub Actions quality gate +├── public/ # Public static assets ├── src/ -│ ├── api/ # API wrappers -│ ├── assets/ # Styles and media -│ ├── components/ # Shared and domain components -│ ├── i18n/ # Locale setup and messages -│ ├── router/ # Role-based routes -│ ├── stores/ # Pinia stores -│ ├── utils/ # HTTP and WebSocket utilities -│ └── views/ # Student, teacher, admin, and login pages -├── .env.example -├── package.json -└── vite.config.js +│ ├── api/ # Student, user, and shared API wrappers +│ ├── assets/ # Styles, icons, and course media +│ ├── components/ # Base, domain, and class-matching components +│ ├── config/ # REST / Forum / WebSocket runtime configuration +│ ├── i18n/ # i18n instance and Chinese/English messages +│ ├── router/ # Multi-role nested routes and guards +│ ├── stores/ # Pinia session, student, and administrator state +│ ├── utils/ # Axios and WebSocket utilities +│ └── views/ +│ ├── student/ # Student-facing pages +│ ├── teacher/ # Teacher-facing pages +│ ├── administrator/ # Administrator-facing pages +│ ├── liveClass/ # Live-class UI and WebRTC composable +│ └── login/ # Login and registration views +├── .env.example # Local service-address examples +├── package.json # Scripts, dependencies, and runtime requirements +├── pnpm-lock.yaml # Reproducible dependency lockfile +└── vite.config.js # Vite configuration ``` -## Deployment +## ✅ Quality Assurance + +| Layer | Gate | +| ---------------------- | ------------------------------------------------------------------------------------------------- | +| Static quality | Read-only ESLint check | +| Formatting | Prettier check | +| Buildability | Vite production build | +| Continuous integration | Ubuntu + Node.js 20 + pnpm 8.15.9 + frozen lockfile | +| Browser validation | Manual smoke checks for login, role redirects, the student dashboard, and the digital-human route | + +GitHub Actions runs the same install, check, and build sequence for pull requests and pushes to `main`. Automated unit, component, and end-to-end tests are not configured yet, so critical product changes still require browser validation. + +## 🔗 Repository Consolidation + +This is the project's only canonical development repository: + +> [computersciencefreshmen/International_Chinese_Platform](https://github.com/computersciencefreshmen/International_Chinese_Platform) + +Early code was split across: + +- [computersciencefreshmen/vue3-project-initialization](https://github.com/computersciencefreshmen/vue3-project-initialization) +- [computersciencefreshmen/project](https://github.com/computersciencefreshmen/project) + +Useful commits from the older repositories are now reachable from the current `main` through standard Git merge commits, including the initialization history that originally had no common ancestor. New code, issues, documentation, and releases should use this repository; the older repositories are historical references only. + +## 🗺️ Roadmap + +- [x] Consolidate three repository histories and establish one canonical home +- [x] Build student, teacher, and administrator route structures +- [x] Centralize REST, dialogue-service, and WebSocket runtime configuration +- [x] Add ESLint, Prettier, production-build, and GitHub Actions gates +- [ ] Align the complete backend contract and replace static course, teacher, and administration data +- [ ] Complete WebRTC rooms, signaling, TURN, and classroom chat protocols +- [ ] Connect real digital-human, AI, ASR, and TTS services +- [ ] Localize all product copy in Chinese and English +- [ ] Add unit, component, and end-to-end automated tests +- [ ] Add production deployment, monitoring, security guidance, and an open-source license + +## 🚢 Deployment + +```bash +pnpm build +``` + +The production bundle is written to `dist/`. A deployment must: + +1. Inject the correct `VITE_*` variables during the build. +2. Configure SPA fallback for Vue Router history mode so unknown routes return `index.html`. +3. Use HTTPS and WSS, with correct backend CORS policies. +4. Provide authenticated signaling, TURN infrastructure, and media-security policies for production live classes. +5. Verify complete login, course, homework, dialogue, and real-time classroom flows before release. + +## 🤝 Contributing + +Issues and pull requests are welcome: + +1. Create a clearly named branch from the latest `main`. +2. Keep the change focused and update related documentation. +3. Run `pnpm check` before committing. +4. Open a pull request and merge it into `main` with a standard merge commit after CI passes. + +## 📄 License + +This repository does not currently declare an open-source license. Until one is added, do not assume permission to copy, distribute, or use the code commercially. -Use HTTPS/WSS service endpoints in production and inject environment variables through the deployment platform. Because the application uses Vue Router history mode, configure the static host to fall back unknown routes to index.html. +
+

Built with ❤️ for international Chinese education.

+ ⬆ Back to top +
diff --git a/README.md b/README.md index 00433e6..dc5dce6 100644 --- a/README.md +++ b/README.md @@ -1,122 +1,315 @@ -# 国际中文平台 + -国际中文平台是一个基于 Vue 3 的国际中文教育前端原型，围绕学生、教师和管理员三类角色组织课程、预约、作业、聊天、直播课堂与平台管理流程。 +
+ International Chinese Platform 标志 -> 当前仓库是项目的唯一主维护仓库： -> [computersciencefreshmen/International_Chinese_Platform](https://github.com/computersciencefreshmen/International_Chinese_Platform) +

🌏 International Chinese Platform

+ +

面向国际中文教育的多角色教学协作平台

+

连接学生学习、教师授课、课程互动、直播课堂与数字人体验的 Vue 3 前端应用。

+ +

+ 功能概览 + · + 快速开始 + · + English + · + 问题反馈 +

+ +

+ + CI + + Vue 3 + Vite 6 + Pinia 2 + Tailwind CSS 3 + pnpm 8.15.9 +

+
+ +--- + +## 📖 项目概览 + +International Chinese Platform 是一个围绕国际中文教学流程构建的多角色前端平台。它不是单页展示模板，而是将学生、教师和管理员工作区组织在同一个 Vue 3 应用中，覆盖课程发现、教师预约、学习需求发布、作业、话轮、直播课堂、数字人课堂、课程上传和平台管理等场景。 + +项目采用角色路由、持久化状态和统一运行时配置，将浏览器端工作流与 REST、话轮生成服务、WebSocket 信令等外部能力解耦，适合作为国际中文教育产品原型、前后端联调基座和持续演进的作品项目。 + +> [!IMPORTANT] +> 本仓库只包含前端应用。登录、注册、验证码、课程、教师、作业、话轮生成及实时课堂的完整生产能力仍需外部后端、信令和媒体基础设施支持。README 会明确区分“已实现的前端能力”“依赖服务的流程”和“原型功能”。 + +## ✨ 项目亮点 + +- **多角色产品结构** — 学生、教师和管理员拥有独立布局、入口、导航与角色路由守卫，而不是把所有页面堆叠在同一个工作台中。 +- **覆盖教学闭环** — 从课程浏览、教师预约和学习需求，到作业、话轮、直播互动与个人中心，呈现较完整的在线中文教学路径。 +- **实时与数字化教学探索** — 提供摄像头、麦克风、屏幕共享、WebRTC 信令基础、滴滴上课匹配动画和数字人课堂原型。 +- **清晰的服务边界** — REST、话轮服务和 WebSocket 地址全部通过环境变量注入，并在未配置时采用安全的同源回退。 +- **可持续工程基线** — 使用 pnpm 锁定依赖，配备 ESLint、Prettier、生产构建和 GitHub Actions 质量门禁。 +- **可审计的仓库整合** — 三个早期仓库的有效 Git 历史已通过合并提交统一到本仓库，后续开发不再分叉。 + +## 🎯 核心功能 + +### 👨‍🎓 学生学习空间 + +- **课程与教师发现** — 浏览课程和教师信息，进入课程、教师详情及预约流程。 +- **教师预约** — 创建预约信息，将浏览器端预约持久化，并在学生首页回显最近预约。 +- **学习需求发布** — 填写学习目标、时间和偏好，形成可继续对接教师的需求草稿。 +- **话轮生成** — 提交关键词并调用独立话轮服务，生成对话练习内容。 +- **作业工作台** — 加载作业、保存浏览器草稿、恢复答案、校验并提交结果。 +- **直播与数字人课堂** — 提供直播课堂媒体控制、滴滴上课匹配交互和数字人教学页面。 +- **个人中心** — 管理个人信息、会员页面、密码入口和消息通知页面。 + +### 👩‍🏫 教师工作空间 -[English](README.en.md) +- **授课工作台** — 组织教师首页、授课对接和课程管理入口。 +- **网络课程与详情** — 浏览教师课程页面并进入课程详情流程。 +- **课程上传原型** — 支持课程资料选择、类型与大小校验、封面预览和浏览器内课程草稿。 +- **教师账户页面** — 提供教师信息与账户相关界面结构。 -## 仓库整合 +### 🧭 管理员工作空间 -项目早期代码曾分散在以下仓库： +- **课程对接** — 统一查看平台课程对接入口。 +- **审核中心** — 提供内容审核工作台页面结构。 +- **数据中心** — 展示平台数据看板原型。 +- **账户与消息** — 提供管理员密码和消息通知页面。 -- [vue3-project-initialization](https://github.com/computersciencefreshmen/vue3-project-initialization) -- [project](https://github.com/computersciencefreshmen/project) +### ⚙️ 平台基础能力 -现已统一到 International_Chinese_Platform。后续代码、Issue、文档和发布均应以本仓库为准；旧仓库仅作为历史参考，避免继续产生分叉。 +- **角色会话与路由守卫** — 根据登录状态和角色保护学生、教师、管理员路由，并支持登录后回到原目标页面。 +- **持久化状态** — 使用 Pinia 与持久化插件保存前端会话、学生资料和预约数据。 +- **统一网络层** — 使用 Axios 实例、超时配置、响应错误处理和环境化服务地址。 +- **实时通信基础** — 提供 WebSocket 管理以及摄像头、麦克风、屏幕共享和 WebRTC PeerConnection 封装。 +- **国际化基础设施** — 集成 Vue i18n 和语言切换组件，为后续完整多语言覆盖提供基础。 -## 当前功能 +## 👥 角色与入口 -- 学生端：课程浏览、教师预约、学习需求发布、话轮聊天、作业、直播课堂、数字人课堂和个人中心。 -- 教师端：授课对接、网络课程、课程上传、用户信息和课程详情。 -- 管理员端：课程对接、审核中心、数据中心和账户中心。 -- 公共能力：Vue Router 嵌套路由、Pinia 持久化状态、Element Plus 组件、Tailwind CSS、Axios 接口层和 Vue i18n 基础设施。 +| 角色 | 默认入口 | 主要任务 | +| ------ | ------------------------------ | ------------------------------------------------------ | +| 学生 | `/student/home` | 课程、教师预约、需求发布、作业、话轮、直播和数字人课堂 | +| 教师 | `/teacher/home` | 授课对接、网络课程、课程上传、课程详情和账户信息 | +| 管理员 | `/administrator/courseDocking` | 课程对接、审核、数据中心、账户和消息管理 | -本仓库目前是前端原型，不包含后端服务。登录鉴权、实时通信、媒体信令和部分业务流程仍依赖外部接口，部署前应完成安全审查和端到端联调。 +所有受保护的角色路由都经过前端会话与角色检查。未登录用户会被送回 `/login`，角色不匹配时会回到当前角色的默认首页。 -## 技术栈 +## 🏗️ 应用架构 -| 层级 | 技术 | -| ------------ | ---------------------------------- | -| 前端框架 | Vue 3 | -| 构建工具 | Vite 6 | -| 路由 | Vue Router | -| 状态管理 | Pinia、pinia-plugin-persistedstate | -| UI 与样式 | Element Plus、Tailwind CSS、Sass | -| 网络与国际化 | Axios、Vue i18n | -| 工程质量 | ESLint、Prettier、GitHub Actions | +```mermaid +flowchart LR + Login["登录与角色选择"] --> Guard["前端会话与角色路由守卫"] + Guard --> Student["学生工作区"] + Guard --> Teacher["教师工作区"] + Guard --> Admin["管理员工作区"] -## 环境要求 + Student --> State["Pinia 持久化状态"] + Teacher --> State + Admin --> State + + Student --> HTTP["Axios / REST"] + Teacher --> HTTP + Admin --> HTTP + Student --> Realtime["WebSocket / WebRTC"] -- Node.js 18 或更高版本 -- pnpm 8.15.9 + HTTP -. "VITE_API_BASE_URL / VITE_FORUM_API_URL" .-> Services["外部后端服务"] + Realtime -. "VITE_WEBSOCKET_URL" .-> Services +``` + +运行时地址由 `src/config/runtime.js` 统一归一化。未显式设置时，REST 使用同源地址，话轮服务回退到 `/process_words`，WebSocket 根据当前页面自动选择 `ws://` 或 `wss://`。 + +## 📊 功能成熟度 + +| 能力 | 状态 | 当前边界 | +| -------------------------- | ----------- | --------------------------------------------------------------- | +| 多角色布局、路由和前端会话 | ✅ 已实现 | 生产级身份认证、授权和令牌生命周期仍由后端负责 | +| 预约、作业和课程上传流程 | 🟡 前端流程 | 预约可本地持久化；作业依赖接口；课程上传目前保存浏览器草稿 | +| 课程、教师和管理数据 | 🟡 混合状态 | 部分页面请求接口，部分列表与管理看板仍使用静态或演示数据 | +| 直播课堂媒体控制 | 🧪 原型阶段 | 摄像头、麦克风和屏幕共享可交互；房间信令、TURN 和聊天协议待完善 | +| 数字人课堂 | 🧪 原型阶段 | 当前为交互与教学页面原型，尚未接入真实 AI、ASR 或 TTS 服务 | +| 国际化 | 🧪 基础设施 | 已有 Vue i18n 和语言切换，绝大多数业务文案仍以中文为主 | +| 工程质量门禁 | ✅ 已实现 | CI 覆盖安装、ESLint、Prettier 和生产构建；自动化测试待补充 | + +## 🛠️ 技术栈 + +| 层级 | 技术 | +| -------------- | ------------------------------------------------- | +| 前端框架 | Vue 3.5、单文件组件（SFC） | +| 构建工具 | Vite 6 | +| 路由 | Vue Router 4、懒加载嵌套路由、角色守卫 | +| 状态管理 | Pinia、pinia-plugin-persistedstate | +| UI 与样式 | Element Plus、Tailwind CSS 3、PostCSS、Sass | +| 网络与实时能力 | Axios、WebSocket、WebRTC | +| 国际化 | Vue i18n | +| 工程工具 | pnpm 8.15.9、ESLint 9、Prettier 3、GitHub Actions | + +## 🚀 快速开始 + +### 前置要求 -package.json 已固定 pnpm 版本。建议通过 Corepack 使用项目声明的版本，避免 pnpm 版本差异改写锁文件。 +- Node.js `>= 18` +- pnpm `8.15.9`（已在 `package.json` 中固定） -## 本地开发 +### 1. 克隆仓库 ```bash git clone https://github.com/computersciencefreshmen/International_Chinese_Platform.git cd International_Chinese_Platform +``` + +### 2. 安装依赖 +```bash corepack enable corepack prepare pnpm@8.15.9 --activate pnpm install --frozen-lockfile +``` +### 3. 配置环境变量 + +```bash cp .env.example .env.local -pnpm dev ``` -Windows PowerShell 可使用以下命令复制环境文件： +Windows PowerShell： ```powershell Copy-Item .env.example .env.local ``` -## 环境变量 +根据你的后端和信令服务修改 `.env.local`。 -| 变量 | 用途 | 示例 | -| ------------------ | ----------------------------- | ----------------------------------- | -| VITE_API_BASE_URL | REST API 基础地址 | http://localhost:7777 | -| VITE_FORUM_API_URL | 话轮/关键词处理接口完整地址 | http://localhost:5002/process_words | -| VITE_WEBSOCKET_URL | 聊天和直播信令 WebSocket 地址 | ws://localhost:7788/websocket | +### 4. 启动开发服务器 -复制 .env.example 为 .env.local 后，根据实际后端修改地址。所有以 VITE\_ 开头的变量都会暴露给浏览器，禁止写入密码、私钥或长期有效的访问令牌。 +```bash +pnpm dev +``` + +打开终端显示的本地地址，默认通常为 `http://localhost:5173`。 -业务代码统一读取这些变量作为服务地址契约，避免提交环境相关的硬编码地址。 +## 🔧 环境变量 -## 常用命令 +| 变量 | 用途 | 未配置时的代码回退 | +| -------------------- | ------------------------ | ---------------------------------------------- | +| `VITE_API_BASE_URL` | REST API 根地址 | `/`（当前站点同源） | +| `VITE_FORUM_API_URL` | 关键词生成话轮的完整接口 | `/process_words` | +| `VITE_WEBSOCKET_URL` | 聊天与课堂信令 WebSocket | 当前站点的 `/websocket`，自动选择 `ws` / `wss` | -| 命令 | 说明 | -| ----------------- | --------------------------------- | -| pnpm dev | 启动开发服务器 | -| pnpm build | 构建生产版本 | -| pnpm preview | 本地预览生产构建 | -| pnpm lint | 自动修复可修复的 ESLint 问题 | -| pnpm lint:check | 只读检查 ESLint | -| pnpm format | 格式化 src 目录 | -| pnpm format:check | 只读检查 src 目录格式 | -| pnpm check | 依次执行 lint、格式检查和生产构建 | +`.env.example` 提供了本地开发示例。所有以 `VITE_` 开头的变量都会进入浏览器构建产物，禁止在其中存放密码、私钥或长期有效的服务端密钥。 -提交前建议执行： +## 📜 常用命令 + +| 命令 | 说明 | +| ------------------- | --------------------------------- | +| `pnpm dev` | 启动 Vite 开发服务器 | +| `pnpm build` | 生成生产构建到 `dist/` | +| `pnpm preview` | 本地预览生产构建 | +| `pnpm lint` | 自动修复可修复的 ESLint 问题 | +| `pnpm lint:check` | 只读执行 ESLint 检查 | +| `pnpm format` | 格式化 `src/` | +| `pnpm format:check` | 检查 `src/` 的 Prettier 格式 | +| `pnpm check` | 依次执行 lint、格式检查和生产构建 | + +提交代码前建议执行： ```bash pnpm check ``` -GitHub Actions 会在推送到 main 以及 Pull Request 时执行同样的质量门禁。当前项目尚未配置自动化单元测试或端到端测试，关键角色路径仍需进行浏览器冒烟测试。 - -## 项目结构 +## 📁 项目结构 ```text International_Chinese_Platform/ -├── .github/workflows/ # 持续集成 -├── public/ # 公共静态资源 +├── .github/ +│ └── workflows/ci.yml # GitHub Actions 质量门禁 +├── public/ # 公共静态资源 ├── src/ -│ ├── api/ # API 封装 -│ ├── assets/ # 样式与媒体资源 -│ ├── components/ # 通用与业务组件 -│ ├── i18n/ # 国际化配置和词条 -│ ├── router/ # 多角色路由 -│ ├── stores/ # Pinia 状态 -│ ├── utils/ # HTTP、WebSocket 等工具 -│ └── views/ # 学生、教师、管理员和登录页面 -├── .env.example -├── package.json -└── vite.config.js +│ ├── api/ # 学生、用户与通用 API 封装 +│ ├── assets/ # 样式、图标与课程媒体 +│ ├── components/ # 基础组件、领域组件与滴滴上课组件 +│ ├── config/ # REST / Forum / WebSocket 运行时配置 +│ ├── i18n/ # 国际化实例与中英文词条 +│ ├── router/ # 多角色嵌套路由和守卫 +│ ├── stores/ # Pinia 会话、学生与管理员状态 +│ ├── utils/ # Axios 与 WebSocket 工具 +│ └── views/ +│ ├── student/ # 学生端页面 +│ ├── teacher/ # 教师端页面 +│ ├── administrator/ # 管理员端页面 +│ ├── liveClass/ # 直播课堂与 WebRTC 组合式函数 +│ └── login/ # 登录与注册界面 +├── .env.example # 本地服务地址示例 +├── package.json # 脚本、依赖和运行时要求 +├── pnpm-lock.yaml # 可复现依赖锁文件 +└── vite.config.js # Vite 配置 ``` -## 部署说明 +## ✅ 质量保障 + +| 层级 | 门禁 | +| ---------- | -------------------------------------------------------- | +| 静态质量 | ESLint 只读检查 | +| 格式一致性 | Prettier 检查 | +| 可构建性 | Vite 生产构建 | +| 持续集成 | Ubuntu + Node.js 20 + pnpm 8.15.9 + frozen lockfile | +| 浏览器验证 | 关键登录、角色重定向、学生首页和数字人路由的人工冒烟检查 | + +GitHub Actions 会在 Pull Request 以及推送到 `main` 时运行同一套安装、检查和构建流程。项目目前尚未配置自动化单元、组件或端到端测试，因此关键业务改动仍应补充浏览器验证。 + +## 🔗 仓库整合 + +本仓库是项目唯一的主维护仓库： + +> [computersciencefreshmen/International_Chinese_Platform](https://github.com/computersciencefreshmen/International_Chinese_Platform) + +项目早期代码曾分散在： + +- [computersciencefreshmen/vue3-project-initialization](https://github.com/computersciencefreshmen/vue3-project-initialization) +- [computersciencefreshmen/project](https://github.com/computersciencefreshmen/project) + +旧仓库的有效提交历史已通过标准 Git 合并提交进入当前 `main`，包括原本无共同祖先的初始化历史。后续代码、Issue、文档和发布均应以本仓库为准；旧仓库只作为历史参考。 + +## 🗺️ 路线图 + +- [x] 统一三个仓库历史和主维护入口 +- [x] 建立学生、教师、管理员三端路由结构 +- [x] 统一 REST、话轮服务和 WebSocket 运行时配置 +- [x] 建立 ESLint、Prettier、生产构建和 GitHub Actions 门禁 +- [ ] 对齐完整后端契约，将静态课程、教师和管理数据替换为真实数据 +- [ ] 完成 WebRTC 房间、信令、TURN 和课堂聊天协议 +- [ ] 接入真实数字人、AI、ASR 与 TTS 服务 +- [ ] 完成全量中英文界面国际化 +- [ ] 增加单元、组件和端到端自动化测试 +- [ ] 补充生产部署、监控、安全基线和开源许可证 + +## 🚢 部署说明 + +```bash +pnpm build +``` + +生产构建输出到 `dist/`。部署时需要： + +1. 在构建阶段注入正确的 `VITE_*` 环境变量。 +2. 为 Vue Router history 模式配置 SPA 回退，将未知路由返回 `index.html`。 +3. 使用 HTTPS，并为实时服务使用 WSS；同时正确配置后端 CORS。 +4. 为生产直播课堂提供经过认证的信令服务、TURN 服务和媒体安全策略。 +5. 在发布前联调登录、课程、作业、话轮和实时课堂的完整端到端流程。 + +## 🤝 参与贡献 + +欢迎通过 Issue 和 Pull Request 改进项目： + +1. 从最新 `main` 创建语义清晰的功能分支。 +2. 保持改动聚焦，并同步更新相关文档。 +3. 提交前运行 `pnpm check`。 +4. 创建 Pull Request，等待 CI 通过后使用标准合并提交并入 `main`。 + +## 📄 许可证 + +本仓库目前尚未声明开源许可证。在添加明确许可证之前，请不要假定代码已获得自由复制、分发或商用授权。 -生产环境应使用 HTTPS/WSS 服务地址，并由部署平台注入环境变量。由于项目采用 Vue Router history 模式，静态服务器还需将未知路由回退到 index.html。 +
+

Built with ❤️ for international Chinese education.

+ ⬆ 回到顶部 +