Files
lpt-fe/AGENTS.md
T

130 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# LPT 前端应用(lpt-fe)
> Vue 3 + TypeScript + Vite 单页应用。
## 规则与技能位置
- 通用规则(跨仓库):meta 仓库 `.agents/roles/`;本仓库的 Git 提交规范已统一到其中的 `commit-convention.md`。
- 本仓库专属规则:`roles/`
- `roles/code-standards.md` — 前端代码标准(交互防抖与加载、按钮规范、颜色与主题、界面质量与可访问性、卡片列表交互、移动端适配、代码整洁、请求层与类型规范、组合式函数复用)
- `roles/design-principles.md` — 前端设计原则(页面信息架构、视觉层级、模型默认做法禁用清单、文案即设计、独立评审触发条件)
- `roles/design-system.md` — 前端设计系统(调性、色板、间距节奏、圆角/描边/阴影、文字角色、组件语法)
- `roles/ui-review-checklist.md` — 前端界面交付自检清单(状态完整性、交互反馈、可访问性、动效、内容承载、表单、移动端)
- `roles/testing.md` — 前端测试规范(分层策略、交互式集成测试、逻辑单测、覆盖率、提交前检查)
- `roles/style-conventions.md` — 样式与交互约定
- 本仓库专属技能:`skills/`
- `skills/ui-review/` — 新页面或大范围 UI 改动的独立视觉评审(取证 → 派无上下文的评审者 → 修正 → 复核)
## 技术栈
- 框架: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 | 回忆复习 |
| `/ai-usage` | AiUsage.vue | AI 用量统计(仅白名单用户可见) |
> 「AI 用量统计」的数据全部来自 `lpt-be` 的 `/ai/usage/*`(不直连 lpt-ai),
> 页面只展示聚合数字与费用,**不含 prompt 与学习内容**(完整日志仍在 lpt-ai 的 `/admin`)。
> 入口显隐读登录响应写入的 `localStorage.aiAdmin`,真正的权限校验在服务端。
>
> 支持三个分组维度:任务类型 / 模型 / **用户**(`groupBy=user`)。用户维度靠 lpt-be 落库的归属字段,
> 未归属的记录单独成行(`key` 为 null、`label` 为「未归属」),并且**不进用户筛选下拉**——
> 它不是一个可筛选的用户。明细表首列渲染 `label ?? key`。
## 认证与请求
- 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` 展示应用场景链接标题。
## 开发配置
- 开发端口: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
npm run type-check
npm run lint
npm run test:coverage
```
编译检查也可以使用:
```bash
npx vite build
npm run type-check
```
## 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)
```