Vue d’ensemble du projet

Fichiers source

Cette page est générée à partir des fichiers source suivants :

• README.md
• package.json
• src/app/page.tsx
• src/app/layout.tsx
• src/app/not-found.tsx
• src/types/index.ts
• .spec-workflow/user-templates/README.md
• next-env.d.ts
• next.config.js
• postcss.config.js

Ce projet est une plateforme d'apprentissage gamifiée conçue pour aider les élèves de sixième à maîtriser les compétences d'écriture à travers une approche interactive et progressive. Basée sur une architecture moderne sans backend, l'application tire parti de Next.js 14, TypeScript et Tailwind CSS pour offrir une expérience utilisateur fluide et responsive. Le système repose entièrement sur le stockage local du navigateur et l'intégration d'API IA configurables par l'utilisateur (BYOK - Bring Your Own Key), permettant un déploiement simplifié sans infrastructure serveur (README.md:1-12, package.json:1-5).

Présentation générale

La plateforme "六年级作文成长手册" (Manuel de croissance en rédaction pour la sixième) constitue un environnement d'apprentissage complet intégrant sept outils d'écriture progressifs, un éditeur de composition en temps réel avec sauvegarde automatique, et un système de correction IA personnalisable. L'architecture sans backend permet une distribution via Vercel avec zéro configuration serveur, tandis que toutes les données utilisateur sont persistées localement dans le localStorage du navigateur (README.md:87-92).

Objectifs pédagogiques

Le projet vise à transformer l'apprentissage de l'écriture en une expérience engageante grâce à la gamification. Les élèves progressent à travers des niveaux structurés, complètent des défis quotidiens, et reçoivent des retours automatisés sur leurs compositions. Le système de streak (série consécutive) et d'achievements (accomplissements) maintient la motivation sur le long terme.

Caractéristiques quantifiables

Architecture technique

L'architecture du projet repose sur le paradigme App Router de Next.js 14, combiné à une stack technologique moderne optimisée pour les performances et l'expérience développeur.

Stack technologique détaillée

(README.md:13-22, package.json:12-42)

Architecture sans backend

Le principe de conception "sans backend" implique que toutes les opérations de persistance s'effectuent côté client via l'API localStorage du navigateur. Cette approche élimine les coûts d'infrastructure serveur tout en simplifiant le déploiement. La fonctionnalité de correction IA utilise un modèle BYOK (Bring Your Own Key) où l'utilisateur configure sa propre clé API OpenAI ou compatible (DeepSeek, Moonshot, etc.) dans les paramètres de l'application (README.md:87-92).

正在加载图表渲染器...

Points clés de l'architecture :

• La couche client gère intégralement l'état et la persistance via Zustand et localStorage
• Next.js App Router structure le routage et l'optimisation du bundle
• Les appels API IA sont initiés depuis le client avec les clés fournies par l'utilisateur
• Le déploiement Vercel Edge assure une distribution CDN globale

Configuration Next.js

Le fichier next.config.js:1-20 définit les optimisations clés pour le déploiement Vercel :

javascript
1const nextConfig = {
2  reactStrictMode: true,
3  swcMinify: true,
4  images: {
5    unoptimized: true
6  },
7  webpack: (config) => {
8    config.module.rules.push({
9      test: /\.mjs$/,
10      include: /node_modules/,
11      type: 'javascript/auto',
12    });
13    return config;
14  }
15}

La configuration désactive l'optimisation d'images pour simplifier le déploiement et ajoute une règle webpack pour gérer les modules ES dans node_modules.

Structure du projet

L'organisation du code suit les conventions Next.js App Router avec une séparation claire des responsabilités (README.md:75-85).

src/
├── app/           # Next.js App Router - Pages et layouts
│   ├── page.tsx       # Page d'accueil avec logique de gamification
│   ├── layout.tsx     # Layout racine avec providers
│   └── not-found.tsx  # Page 404 personnalisée
├── components/    # Composants React réutilisables
├── data/          # Données statiques (outils, exercices)
├── lib/           # Utilitaires et store Zustand
├── types/         # Définitions TypeScript
└── styles/        # Styles globaux Tailwind

Module App Router

Le fichier src/app/layout.tsx:2-30 configure le layout racine avec les métadonnées SEO et le provider de notification :

typescript
1import { Inter } from 'next/font/google';
2import './globals.css';
3import { NotificationProvider } from '@/contexts/NotificationContext';
4
5const inter = Inter({ subsets: ['latin'] });
6
7export const metadata: Metadata = {
8  title: '六年级作文成长手册',
9  description: '游戏化作文学习平台 - 在规则内说真话',
10  keywords: ['作文', '六年级', '写作', '语文学习', '游戏化学习'],
11};

Le layout encapsule l'application dans un NotificationProvider et applique un fond dégradé Morandi pour l'esthétique générale.

Gestion des erreurs 404

Le composant src/app/not-found.tsx:1-33 implémente une page d'erreur personnalisée avec navigation de retour vers l'accueil, utilisant les composants Card et Button de l'UI library.

Modèle de données

Le système de types TypeScript définit l'ensemble des structures de données utilisées dans l'application (src/types/index.ts:1-169).

Types fondamentaux

WritingTool - Outil d'écriture

L'interface WritingTool (src/types/index.ts:10-57) définit la structure complète d'un outil d'écriture :

typescript
1export interface WritingTool {
2  id: string;
3  name: string;
4  title: string;
5  description: string;
6  mantra: string;              // Mnémonique/petite phrase
7  tips: string;
8  suitableFor: string;
9  caution: string;
10  examples: {
11    bad: string;
12    good: string;
13  }[];
14  exercises: string[];
15  comprehensionTest?: ComprehensionTest;
16  unlockConditions?: {
17    prerequisiteTools?: string[];
18    minMasteryLevel?: number;
19    minPracticeCount?: number;
20    minWritingStreak?: number;
21    password?: string;
22    unlockPath?: string;
23  };
24  subTools?: string[];
25  guidance?: {
26    coreConcepts?: string[];
27    techniques?: {
28      name: string;
29      description: string;
30      examples?: string[];
31    }[];
32    practiceStages?: {
33      stage: string;
34      tasks: string[];
35    }[];
36    selfCheck?: string[];
37  };
38}

Responsabilités :

• Définit le contenu pédagogique de chaque outil
• Gère les conditions de déblocage progressif
• Structure les exercices et tests de compréhension

StudentProgress - Progression étudiante

L'interface StudentProgress (src/types/index.ts:103-111) capture l'état complet de l'apprenant :

typescript
1export interface StudentProgress {
2  currentLevel: number;
3  levels: LevelProgress[];
4  totalScore: number;
5  unlockedTools: string[];
6  dailyChallenge?: DailyChallenge;
7  habitTracker?: HabitTracker;
8}

Chaque niveau (LevelProgress) suit les métriques de maîtrise incluant testPassed, practiceCount, et masteryLevel (0-100).

Système de gamification

DailyChallenge - Défi quotidien

typescript
1export interface DailyChallenge {
2  date: Date;
3  task: string;
4  completed: boolean;
5  streak: number;              // Jours consécutifs
6  recommendedToolId?: string;
7  canMakeup?: boolean;         // Rattrapage possible
8}

(src/types/index.ts:75-84)

Achievement - Accomplissement

typescript
1export interface Achievement {
2  id: string;
3  title: string;
4  description: string;
5  earnedAt: Date;
6  icon: string;                // Emoji
7}

(src/types/index.ts:87-93)

Gestion des compositions

L'interface Essay (src/types/index.ts:149-169) supporte plusieurs types de contenu :

typescript
1export interface Essay {
2  id: string;
3  title: string;
4  content: string;
5  toolUsed: string;
6  createdAt: Date;
7  feedback?: string;
8  versions?: EssayVersion[];
9  currentVersionId?: string;
10  actionItems?: ActionItem[];
11  contentType?: 'text' | 'image' | 'audio';
12  imageUrl?: string;           // Composition manuscrite
13  audioUrl?: string;           // Enregistrement vocal
14  transcribedText?: string;    // Texte transcrit
15}

Le système de versions (EssayVersion) permet un historique arborescent avec parentId pour tracer les révisions.

Fonctionnalités de gamification

Le cœur de l'expérience utilisateur repose sur un système de gamification sophistiqué implémenté dans src/app/page.tsx:21-69.

Génération des défis quotidiens

La fonction generateDailyChallenge implémente la logique de sélection aléatoire des tâches :

typescript
1const getAvailableToolsForChallenge = () => {
2  return writingTools.filter(tool => {
3    if (tool.id === 'free-writing') return true;
4    const level = progress.levels.find(l => l.toolId === tool.id);
5    return !!level?.testPassed;
6  });
7};
8
9const generateDailyChallenge = () => {
10  const available = getAvailableToolsForChallenge();
11  const selected = available.length > 0 ? pickRandom(available) : writingTools[0];
12  const exercises = selected.exercises || [];
13  const task = exercises.length > 0 ? pickRandom(exercises) : '自由写作：...';
14  return {
15    date: new Date(),
16    task,
17    completed: false,
18    streak: currentChallenge?.streak || 0,
19    recommendedToolId: selected.id,
20    canMakeup: false,
21  };
22};

Points clés d'implémentation :

• Seuls les outils avec testPassed sont éligibles (sauf écriture libre)
• Le streak est préservé entre les générations successives
• Une tâche par défaut est fournie si aucun exercice n'existe

Système d'achievements

La fonction handleChallengeComplete déclenche l'attribution d'achievements basés sur le streak :

typescript
1const handleChallengeComplete = () => {
2  const updatedChallenge = {
3    ...currentChallenge!,
4    completed: true,
5    streak: (currentChallenge?.streak || 0) + 1
6  };
7  
8  setCurrentChallenge(updatedChallenge);
9  setDailyChallenge(updatedChallenge);
10  
11  const streak = (currentChallenge?.streak || 0) + 1;
12  if (streak === 1) {
13    addAchievement({
14      title: "写作新手",
15      description: "完成第一次写作挑战",
16      icon: "📝"
17    });
18  } else if (streak === 7) {
19    // Achievement pour 7 jours consécutifs
20  }
21};

(src/app/page.tsx:47-69)

正在加载图表渲染器...

Flux de données :

1. L'utilisateur complète une tâche d'écriture
2. Le composant calcule le nouveau streak et met à jour l'état
3. Les achievements sont attribués selon les seuils (1, 7, etc.)
4. L'état complet est persisté dans localStorage via Zustand

Configuration IA

L'interface AIConfig (src/types/index.ts:114-119) permet une configuration flexible :

typescript
1export interface AIConfig {
2  apiKey: string;
3  baseURL?: string;            // Endpoint personnalisé
4  model?: string;
5  models?: string[];           // Liste des modèles disponibles
6}

Cette structure supporte les providers compatibles OpenAI comme DeepSeek et Moonshot via le paramètre baseURL.

Flux de données et interactions

正在加载图表渲染器...

Points d'interaction clés :

• La page d'accueil orchestre la logique de gamification via les hooks Zustand
• L'éditeur de composition interagit avec l'API IA pour les corrections
• Le store centralise tout l'état applicatif et synchronise avec localStorage

Capacités quantifiées du projet

Guide de lecture du rapport

Le présent rapport technique est structuré pour faciliter la compréhension approfondie du projet. La lecture recommandée suit l'ordre ci-dessous pour une progression logique des concepts.

正在加载图表渲染器...

Ordre de lecture recommandé :

1. Vue d'ensemble (ce document) - Comprendre le projet globalement
2. Fonctionnalités - Explorer les 7 outils d'écriture en détail
3. Architecture - Analyser les patterns techniques et la structure modulaire
4. Modèle de données - Étudier les types TypeScript et leurs relations
5. Intégration IA - Configurer et utiliser la correction automatisée
6. Déploiement - Mettre en production sur Vercel

Scénarios dutilisation

Environnement scolaire

La plateforme est conçue pour une utilisation en classe de sixième, où les enseignants peuvent suivre la progression des élèves via les métriques de maîtrise. Le système de défis quotidiens encourage la pratique régulière, tandis que les achievements fournissent une motivation extrinsèque.

Apprentissage autonome

Les élèves peuvent utiliser la plateforme de manière autonome, progressant à leur rythme through les 7 outils. Le système de déblocage progressif (unlockConditions) assure que les concepts fondamentaux sont maîtrisés avant d'accéder aux outils avancés.

Correction IA personnalisée

L'intégration BYOK permet aux familles d'utiliser leur propre clé API pour la correction, offrant une flexibilité de coût et de modèle. Les providers supportés incluent OpenAI, DeepSeek, et Moonshot, tous compatibles avec le format d'API OpenAI (README.md:93-99).