Files
lpt-fe/AGENTS.md
T
cat-shark a69b350829 feat: 用量明细支持按用户分组与筛选
- 分组维度增加「按用户」,首列渲染 label(用户名),未归属单独成行
- 新增用户筛选下拉,选项来自 groupBy=user,未归属不进下拉
2026-10-10 20:08:51 +08:00

126 lines
4.6 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`,真正的权限校验在服务端。
>
> 支持三个分组维度:任务类型 / 模型 / **用户**(`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)
```