ai-learning-platform/AGENTS.md

AGENTS.md — 项目知识库（AI 专用）

每次任务前先读此文件。维护项目关键上下文，避免重复探索。

项目概览

宇之然 AI 工具指南与技能练习平台。前端 Next.js + shadcn/ui，后端 NestJS + MySQL。

项目	值
品牌	宇之然（北京宇之然科技中心）
域名	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: Prisma + MySQL（schema 在 prisma/schema.prisma）
• 认证: 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
• 国际化: 所有用户可见文本使用 useT() hook，翻译 key 位于 src/i18n/locales/。新增页面先加翻译 key 再写 UI。中文默认，英文同步维护。

2026 市场验证数据（已修正）

指标	数据	来源
AI 教育市场	$7-10B(2025) → $42B(2030)，CAGR 40%+	TBRC, Mordor Intelligence
Prompt 工程市场	$505M(2025) → $673M(2026) → $6.7B(2034)，CAGR 33%	Fortune Business Insights
Shadow AI	75% 员工用未授权 AI，48% 把公司数据贴进公共 AI	Microsoft, Cisco
企业 IP 泄漏	43% 企业因员工使用外部 AI 发生过泄漏	Bitglass/Forcepoint
学生 AI 使用率	86% 学生使用 AI，66% 用 ChatGPT	Digital Education Council
教师 AI 培训缺口	68% 城市教师未接受任何 AI 培训	Education Week

调整后产品路线图（基于真实数据）

1. AI 工具指南（最高优先级） ✅ — 收录优质 AI 工具，联盟返佣变现，首页展示精选工具
2. 练习系统 ✅ — Prompt 工程市场 $673M(2026)，练习+评分是已验证的付费模式
3. ¥9.9 用量包 ✅ — 免费 5 次 → 付费 50 次，从沙盒使用量直接变现
4. 技能广场 ✅ — 一次性购买技能，¥9.9-29.9，独立变现渠道
5. 企业版 ↓ — 从主菜单隐藏，页面仍可通过 URL 访问，不主动运营
6. 社区/圈子 ↓ — 从主菜单隐藏，页面仍可访问，不主动运营
7. 内容扩充（下一个） — 核心竞争围绕内容质量而非模型数量：增加练习场景、行业定制题、评分系统优化

关键架构决策

后端关键 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，返回阶段任务完成情况）
GET /api/v1/skills	技能列表（支持 ?category= / ?difficulty= / ?search= 过滤）
GET /api/v1/skills/:id	技能详情（含 system prompt、练习任务、starter 问题，返回 purchased/locked 状态）
GET /api/v1/skills/marketplace	技能广场（返回所有技能含 price + purchased 状态，无需认证也可用）
GET /api/v1/skills/categories	技能分类列表
GET /api/v1/skills/difficulties	难度等级列表

关键上下文（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
• ESLint 循环引用已在 next.config.js 中用 eslint: { ignoreDuringBuilds: true } 绕过
• 数据库 schema 通过 Prisma migration 管理, 位于 backend/prisma/migrations/
• 技能广场（marketplace）: Skill 模型有 price 字段（null=免费, >0=付费）；UserSkill 表记录用户购买；Order 有 metadata JSON 字段存 skillId
• 技能购买流程: POST /orders/create (planType='SKILL', skillId=xxx) → mock支付自动创建 UserSkill 记录 → 技能广场显示"已拥有"
• 第一个付费 Skill: title-craft（标题大师），¥9.9，seed 在 prisma/seed-marketplace.cjs
• 后续 5 个付费 Skill: payment-chaser(回款助手 ¥19.9), proposal-wizard(提案智造 ¥19.9), review-intel(差评分析师 ¥19.9), listing-optimizer(商品文案大师 ¥29.9), contract-reviewer(合同审查助手 ¥29.9)

项目管理流程

每次任务遵循以下流程：

1. 任务开始前 — 读 AGENTS.md + docs/progress.md，了解当前进度和上下文
2. 规划阶段 — 分析需求，拆解为 TODO 列表，按优先级排序
3. 执行阶段 — 按 TODO 依次实施，完成后先做代码评审修复（检查代码风格、类型安全、边界情况、安全隐患、是否符合项目约定），再做测试验证（运行 lint/build + 相关测试，发现失败立即修复）
4. 任务完成后 — 更新 docs/progress.md（更新阶段状态、补充完成项）
5. 归档 — 旧版 progress.md 移到 docs/archive/progress-YYYY-MM-DD.md
6. 提交 — 只有在用户明确要求时才创建 git commit

常用命令

# 前端开发
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。

---

此文件仅在架构/约定变更时更新。进度追踪见 docs/progress.md。