feat: Phase 1-3 全部完成 — 沙盒增强、学情分析、学习路径

2026-05-18 09:48:51 +08:00
commit 11bb86854c
277 changed files with 37755 additions and 0 deletions
@@ -0,0 +1,112 @@
+# AGENTS.md — 项目知识库（AI 专用）
+
+> 每次任务前先读此文件。维护项目关键上下文，避免重复探索。
+
+## 项目概览
+
+宇之然 AI 学习与实践平台。前端 Next.js + shadcn/ui，后端 NestJS + PostgreSQL。
+
+| 项目 | 值 |
+|------|-----|
+| 品牌 | 宇之然（北京宇之然科技中心） |
+| 域名 | yuzhiran.com |
+| 前端 | `frontend/`, port 3000, Next.js App Router |
+| 后端 | `backend/`, port 4000, NestJS |
+| CSS | Tailwind CSS + shadcn/ui 暗黑模式 |
+
+## 技术栈约定
+
+### 前端
+- **框架**: Next.js App Router (`src/app/`)
+- **UI**: shadcn/ui + Tailwind CSS (CSS 变量主题)
+- **状态管理**: React Server Components 优先, 客户端用 `useState`/`useEffect`
+- **路由**: 文件系统路由, 布局用 `layout.tsx`, 加载用 `loading.tsx`, 错误用 `error.tsx`
+- **暗黑模式**: `next-themes` + Tailwind 暗类策略 (`darkMode: 'class'`)
+
+### 后端
+- **框架**: NestJS 模块化架构
+- **ORM**: TypeORM + PostgreSQL（schema 在 `database/migrations/`）
+- **认证**: JWT + Passport
+- **API 前缀**: `/api/v1`
+- **CORS**: `origin: true`, `maxAge: 0`（避免浏览器预检缓存）
+
+### UI/UX 统一规则
+- **容器**: 内容页 `max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12`；法律/文本页用 `max-w-3xl`
+- **标题**: `text-3xl font-bold text-foreground`
+- **副标题**: `<p className="mt-2 text-muted-foreground">...</p>`
+- **颜色**: 全站禁用 `text-gray-*` / `bg-gray-*` / `border-gray-*` 硬编码 —— 使用 CSS 变量：
+  - 前景色 → `text-foreground` / `text-muted-foreground`
+  - 背景 → `bg-card` / `bg-muted/50` / `bg-accent`
+  - 边框 → `border-border`
+  - hover → `hover:text-foreground` / `hover:bg-accent`
+
+## 关键架构决策
+
+| 决策 | 方案 | 原因 |
+|------|------|------|
+| CORS | `origin: true` + `maxAge: 0` | 避免预检缓存, 开发灵活 |
+| Favicon | `public/favicon.png` + `app/icon.svg` | `.ico` 与 `output: 'export'` 不兼容 |
+| 静态导出 | `output: 'export'` | 部署到静态托管 |
+| Sandbox 布局 | `h-[calc(100vh-4rem)] flex flex-col` | 固定头尾, 消息区滚动 |
+| 流式聊天 | `ReadableStream` fetch API | 实时 AI 响应 |
+| 法律页面 | `max-w-3xl` 窄容器 | 长文本可读性 |
+| 模型列表 | `frontend/src/lib/models.ts` | 全站唯一数据源，3 个页面统一导入 |
+| 颜色约定 | 全站禁用 `text-gray-*` / `bg-gray-*` / `border-gray-*` | 必须使用 CSS 变量 |
+| 学情分析 | `GET /api/v1/learning/analytics` + `GET /api/v1/learning/path` | 基于对话知识度分析 |
+
+## 后端关键 API
+
+| 端点 | 说明 |
+|------|------|
+| `POST /api/v1/auth/register` | 注册 |
+| `POST /api/v1/auth/login` | 登录 |
+| `GET /api/v1/search?q=xxx` | 搜索（返回 `{ results: [...] }`，**不是** `items`） |
+| `GET /api/v1/users/:id` | 用户信息 |
+| `POST /api/v1/chat/completions` | AI 流式对话 |
+| `GET /api/v1/enterprise/...` | 企业版管理 |
+| `GET /api/v1/notifications` | 通知列表（需 JWT） |
+| `GET /api/v1/notifications/unread` | 未读数（需 JWT） |
+| `PATCH /api/v1/notifications/:id/read` | 标记已读（需 JWT） |
+| `PATCH /api/v1/notifications/read-all` | 全部已读（需 JWT） |
+| `GET /api/v1/learning/analytics` | 学情分析（需 JWT，返回知识领域掌握度） |
+| `GET /api/v1/learning/path` | 学习路径进度（需 JWT，返回阶段任务完成情况） |
+
+## 关键上下文（Critical Context）
+
+- `search.service.ts` 返回 `results` 而非 `items` —— 写测试时注意
+- `users.service.ts` 的 `if (status)` 曾误写为 `if (params.status)`（已修复）
+- 静态构建 (`next build`) 已修复 —— 所有动态路由都通过 server wrapper 模式导出 `generateStaticParams()`（60 页面全部生成）
+- `public/favicon.ico` 和 `app/favicon.ico` 不能共存，会触发 500
+- 数据库 schema 通过 TypeORM migration 管理, 位于 `backend/src/database/migrations/`
+
+## 项目管理流程
+
+每次任务遵循以下流程：
+
+1. **任务开始前** — 读 AGENTS.md + docs/progress.md，了解当前进度和上下文
+2. **规划阶段** — 分析需求，拆解为 TODO 列表，按优先级排序
+3. **执行阶段** — 按 TODO 依次实施，每次完成后验证（lint/test/build）
+4. **任务完成后** — 更新 docs/progress.md（更新阶段状态、补充完成项）
+5. **归档** — 旧版 progress.md 移到 `docs/archive/progress-YYYY-MM-DD.md`
+6. **提交** — 只有在用户明确要求时才创建 git commit
+
+## 常用命令
+
+```bash
+# 前端开发
+cd frontend && npm run dev
+
+# 后端开发
+cd backend && npm run start:dev
+
+# 前端构建
+cd frontend && npm run build
+
+# 后端测试
+cd backend && npm test
+npm run test:e2e
+```
+
+---
+
+> 此文件仅在架构/约定变更时更新。进度追踪见 `docs/progress.md`。