learn-languages/AGENTS.md

LEARN-LANGUAGES 知识库

生成时间: 2026-03-08 提交: 91c59c3 分支: dev

概述

全栈语言学习平台，集成 AI 翻译、词典和 TTS。Next.js 16 App Router + PostgreSQL + better-auth + next-intl。

结构

src/
├── app/              # Next.js 路由 (Server Components)
│   ├── (auth)/       # 认证页面: 登录、注册、个人资料
│   ├── (features)/   # 功能页面: 翻译、词典、字幕播放器
│   ├── folders/      # 文件夹管理
│   └── api/auth/     # better-auth catch-all
├── modules/          # 业务逻辑 (action-service-repository)
│   ├── auth/         # 认证 actions, services, repositories
│   ├── translator/   # 翻译模块
│   ├── dictionary/   # 词典模块
│   └── folder/       # 文件夹管理模块
├── design-system/    # 可复用 UI 基础组件 (CVA)
├── components/       # 业务组件
├── lib/              # 集成层 (db, auth, bigmodel AI)
├── hooks/            # 自定义 hooks (useAudioPlayer, useFileUpload)
├── utils/            # 纯工具函数 (cn, validate, json)
└── shared/           # 类型和常量

查找位置

任务	位置	备注
添加功能页面	src/app/(features)/	路由组，无 URL 前缀
添加认证页面	src/app/(auth)/	登录、注册、个人资料
添加业务逻辑	src/modules/{name}/	遵循 action-service-repository
添加 AI 管道	src/lib/bigmodel/{name}/	多阶段 orchestrator
添加 UI 组件	src/design-system/{category}/	base, feedback, layout, overlay
添加工具函数	src/utils/	纯函数
添加类型定义	src/shared/	业务类型
数据库查询	src/modules/*/	Repository 层
i18n 翻译	messages/*.json	8 种语言

约定

架构: Action-Service-Repository

每个模块 6 个文件:

{name}-action.ts       # Server Actions, "use server"
{name}-action-dto.ts   # Zod schemas, ActionInput*/ActionOutput*
{name}-service.ts      # 业务逻辑, 跨模块调用
{name}-service-dto.ts  # ServiceInput*/ServiceOutput*
{name}-repository.ts   # Prisma 操作
{name}-repository-dto.ts # RepoInput*/RepoOutput*

命名

• 类型: {Layer}{Input|Output}{Feature} → ActionInputSignUp
• 函数: {layer}{Feature} → actionSignUp, serviceSignUp
• 文件: kebab-case 带角色后缀

Server/Client 划分

• 默认: Server Components (无 "use client")
• Client: 仅在需要时 (useState, useEffect, 浏览器 API)
• Actions: 必须有 "use server"

导入风格

• 显式路径: @/design-system/base/button (无 barrel exports)
• 不创建 index.ts 文件

验证

• Zod schemas 放在 *-dto.ts
• 使用 validate() from @/utils/validate

认证

// 服务端
import { auth } from "@/auth";
const session = await auth.api.getSession({ headers: await headers() });

// 客户端
import { authClient } from "@/lib/auth-client";
const { data } = authClient.useSession();

受保护操作

const session = await auth.api.getSession({ headers: await headers() });
if (!session?.user?.id) return { success: false, message: "未授权" };
// 变更前检查所有权

反模式 (本项目)

• ❌ index.ts barrel exports
• ❌ as any, @ts-ignore, @ts-expect-error
• ❌ 用 API routes 做数据操作 (使用 Server Actions)
• ❌ Server Component 可行时用 Client Component
• ❌ npm 或 yarn (使用 pnpm)
• ❌ 生产代码中使用 console.log

独特风格

设计系统分类

• base/ — 原子组件: button, input, card, checkbox, radio, switch, select, textarea, range
• feedback/ — 反馈: alert, progress, skeleton, toast
• layout/ — 布局: container, grid, stack (VStack, HStack)
• overlay/ — 覆盖层: modal
• navigation/ — 导航: tabs

AI 管道模式

src/lib/bigmodel/ 中的多阶段 orchestrator:

{name}/
├── orchestrator.ts      # 协调各阶段
├── types.ts             # 共享接口
└── stage{n}-{name}.ts   # 各阶段实现

废弃函数

translator-action.ts 中的 genIPA() 和 genLanguage() — 保留用于 text-speaker 兼容

命令

pnpm dev           # 开发服务器 (HTTPS)
pnpm build         # 生产构建 (验证代码)
pnpm lint          # ESLint
pnpm prisma studio # 数据库 GUI

备注

• Tailwind CSS v4 (无 tailwind.config.ts)
• React Compiler 已启用
• i18n: 8 种语言 (en-US, zh-CN, ja-JP, ko-KR, de-DE, fr-FR, it-IT, ug-CN)
• TTS: 阿里云千问 (qwen3-tts-flash)
• 数据库: PostgreSQL via Prisma (生成在 generated/prisma/)
• 未配置测试基础设施