Files
lpt-fe/AGENTS.md
T

5.2 KiB
Raw Blame History

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

项目结构

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

启动命令

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

编译检查也可以使用:

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 服务,前端不直接调用

调用关系

浏览器 → lpt-fe (5158) ──/api──→ lpt-be (5157) ──HTTP──→ lpt-ai (5199)
                                      │
                                      └── MySQL (8109)