Files
lpt-fe/AGENTS.md
T
cat-shark 0a728cfba8 feat: 新增 AI 用量统计页与头部入口
- 新增 /ai-usage 页面:统计卡、按任务类型/模型明细、内联 SVG 趋势图、上游余额
- 入口按钮放在「退出登录」左侧,显隐读登录响应写入的 aiAdmin
- token 为 null 时显示「未上报」,与 0 区分
2026-10-10 18:46:11 +08:00

122 lines
4.3 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/testing.md` — 前端测试规范(分层策略、交互式集成测试、逻辑单测、覆盖率、提交前检查)
- `roles/style-conventions.md` — 样式与交互约定
- 本仓库专属技能:本仓库暂无专属技能目录
## 技术栈
- 框架: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`,真正的权限校验在服务端。
## 认证与请求
- 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)
```