docs: migrate .pi/SYSTEM.md to AGENTS.md

2026-08-01 00:13:07 +08:00
parent 9af479d833
commit a43267db73
2 changed files with 107 additions and 125 deletions
@@ -0,0 +1,107 @@
+# 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`，带内存缓存和请求去重。
+
+## 样式与交互约定
+
+- 链接使用绿色系 `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 模式。
+
+## 开发配置
+
+- 开发端口：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
+```
+
+## 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)
+```