121 lines
4.0 KiB
Markdown
121 lines
4.0 KiB
Markdown
# LPT 前端应用（lpt-fe）
|
||
|
||
> Vue 3 + TypeScript + Vite 单页应用。
|
||
|
||
## Git 提交规范
|
||
|
||
- 提交信息必须简短且使用中文，不要使用英文长句。
|
||
- 格式：`类型: 简述`，例如 `feat: 新增学习会话页面`、`fix: 修复路由守卫401跳转`、`docs: 补充组件说明`。
|
||
|
||
## 技术栈
|
||
|
||
- 框架：Vue 3 + TypeScript + Vite 5
|
||
- UI 库：Element Plus 2.8
|
||
- HTTP：Axios（`withCredentials: true`，自动携带 Cookie `satoken`）
|
||
- 思维导图：mind-elixir 5.13
|
||
- Markdown：marked 18.0
|
||
- 测试：Vitest + Playwright
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
lpt-fe/src/
|
||
├── api/ → API 接口层
|
||
├── components/ → 页面组件
|
||
├── components/composables/ → 组合式函数
|
||
├── router/ → 路由配置
|
||
├── utils/ → 工具函数
|
||
├── assets/ → 全局样式与资源
|
||
└── __tests__/ → 单元测试
|
||
```
|
||
|
||
核心组件：`Login.vue`、`Welcome.vue`、`Study.vue`、`StartTask.vue`、`Review.vue`、`ReviewDetail.vue`、`ReviewRecall.vue`、`TaskForm.vue`、`MindMapViewer.vue`、`MarkdownRenderer.vue`。
|
||
|
||
## 路由表
|
||
|
||
| 路径 | 组件 | 说明 |
|
||
|------|------|------|
|
||
| `/login` | Login.vue | 登录页（无需认证） |
|
||
| `/welcome` | Welcome.vue | 首页 |
|
||
| `/study` | Study.vue | 学习任务列表 |
|
||
| `/start-task/:taskNum` | StartTask.vue | 学习会话 |
|
||
| `/add-task` | TaskForm.vue | 创建任务 |
|
||
| `/update-task/:taskId` | TaskForm.vue | 更新任务 |
|
||
| `/review` | Review.vue | 复习总览 |
|
||
| `/review/detail/:type/:id` | ReviewDetail.vue | 复习详情 |
|
||
| `/review/recall/:taskNum` | ReviewRecall.vue | 回忆复习 |
|
||
|
||
## 认证与请求
|
||
|
||
- Axios `withCredentials: true`，Cookie `satoken` 自动携带。
|
||
- 401 处理：HTTP 层和业务层双重检测，清理 `localStorage.isLoggedIn` 后跳转 `/login`。
|
||
- `validateResponse`：`code !== 200` 时 reject。
|
||
- Vite 代理：`/api` → `http://localhost:5157`，自动重写去掉 `/api` 前缀。
|
||
|
||
## Markdown 学习材料
|
||
|
||
- 编辑：textarea 输入，支持 `[文字](url)` 和裸 URL。
|
||
- 预览：`renderMarkdown(raw)` 同步函数，使用 `__LINK_N__` 占位符防止嵌套 HTML。
|
||
- 保存：`convertMaterialUrls()` 异步拉取标题，替换裸 URL 为 `[标题](url)`。
|
||
- `getUrlTitle(url)`：调用 `/utils/fetch-title`，带内存缓存和请求去重。
|
||
|
||
## 应用场景
|
||
|
||
- TaskForm 编辑页使用 `el-dialog` 弹窗管理应用场景。
|
||
- Study 详情页使用 `getUrlTitle` 展示应用场景链接标题。
|
||
|
||
## 样式与交互约定
|
||
|
||
- 链接使用绿色系 `var(--green-600)`，虚线下划线，hover 变实线。
|
||
- 区块分隔使用 `.detail-block`：`border-top` + `padding-top`，首个除外。
|
||
- 小字提示使用 12px `var(--text-secondary)`。
|
||
- `Study.vue` 任务清单每页 20 条。
|
||
- `StartTask.vue` 编辑任务时先 GET 详情，合并后再 PUT，避免覆盖其他字段。
|
||
- `MindMapViewer.vue` 支持只读、编辑、selectable、colorByCompare 模式；selectable 模式下点击节点 emit `node-select`。
|
||
- ReviewRecall 中 `standardExpanded` 展开后节点可点击，用于选择复习起点。
|
||
|
||
## 开发配置
|
||
|
||
- 开发端口：5158
|
||
- 代理：`/api` → `http://localhost:5157`
|
||
- 环境变量：`.env.development` / `.env.production` / `.env.uat`
|
||
|
||
## 启动命令
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
npm run build
|
||
npm run test
|
||
npm run test:e2e
|
||
npx vue-tsc --noEmit
|
||
```
|
||
|
||
编译检查也可以使用：
|
||
|
||
```bash
|
||
npx vite build
|
||
npx vue-tsc --noEmit
|
||
```
|
||
|
||
## Docker
|
||
|
||
- 多阶段构建：`node:20-alpine` 编译 → `nginx:alpine` 运行。
|
||
- 暴露端口：80。
|
||
- 构建参数：`BUILD_MODE`，默认 production。
|
||
|
||
## 关联项目
|
||
|
||
| 项目 | 路径 | 端口 | 说明 |
|
||
|------|------|------|------|
|
||
| lpt-be | `../lpt-be/` | 5157 | Spring Boot 后端，前端通过 `/api` 代理调用 |
|
||
| lpt-ai | `../lpt-ai/` | 5199 | AI 服务，前端不直接调用 |
|
||
|
||
## 调用关系
|
||
|
||
```text
|
||
浏览器 → lpt-fe (5158) ──/api──→ lpt-be (5157) ──HTTP──→ lpt-ai (5199)
|
||
│
|
||
└── MySQL (8109)
|
||
```
|