Relevant source files

The following files were used as context for generating this wiki page: - [src/app/page.tsx](https://github.com/initialxko/writing/blob/main/src/app/page.tsx) - [src/app/layout.tsx](https://github.com/initialxko/writing/blob/main/src/app/layout.tsx) - [package-lock.json](https://github.com/initialxko/writing/blob/main/package-lock.json) - [tailwind.config.js](https://github.com/initialxko/writing/blob/main/tailwind.config.js) - [next-env.d.ts](https://github.com/initialxko/writing/blob/main/next-env.d.ts)

# 本地运行与调试 ## 介绍本章节面向 **开发者**，说明如何在本地启动、调试以及理解项目的核心运行时结构。项目基于 **Next.js 14**（App Router）+ **React 18** + **Tailwind CSS**，采用 **Zustand** 进行全局状态管理，所有业务逻辑集中在 `src/app/page.tsx`（首页）与 `src/app/layout.tsx`（根布局）中。通过阅读本页，您可以快速搭建本地开发环境、掌握关键组件的交互流程，并利用 VS Code/Chrome DevTools 进行断点调试。 > 相关概念可参考： > - **全局状态** → `useAppStore`（在 `src/lib/store` 中实现） > - **每日挑战** → `DailyChallengeCard` 组件（位于 `src/components/DailyChallenge`） --- ## 目录 1. [环境准备](#环境准备) 2. [项目结构概览](#项目结构概览) 3. [核心运行时流程](#核心运行时流程) 4. [Tailwind 配置要点](#tailwind-配置要点) 5. [调试技巧与常见问题](#调试技巧与常见问题) 6. [关键代码摘录](#关键代码摘录) --- ## 环境准备 | 步骤 | 操作 | 说明 | |------|------|------| | 1 | **Node.js ≥ 18**（项目 `package-lock.json` 中声明） | `node` 版本必须满足 `>=18.0.0`（见 `@gradio/client` 的 `engines`） | | 2 | **安装依赖** | `npm ci`（使用 lockfile 保证一致性） | | 3 | **启动开发服务器** | `npm run dev` → 访问 `http://localhost:3000` | | 4 | **类型检查** | `npm run lint`（ESLint + Next.js 规则） | | 5 | **构建生产** | `npm run build && npm start` | > 所有依赖列于 `package-lock.json`，包括 `next`, `react`, `tailwindcss`, `zustand` 等。Sources: [package-lock.json](https://github.com/initialxko/writing/blob/main/package-lock.json) --- ## 项目结构概览 ```mermaid graph TB subgraph LayoutGroup LayoutNode[RootLayout] --> BodyNode[Body] end subgraph PageGroup HomeNode[HomePage] --> ChallengeNode[DailyChallengeCard] HomeNode --> HabitNode[HabitTrackerSection] HomeNode --> AchievementNode[AchievementCard] end LayoutNode --> HomeNode classDef comp fill:#e8f5e9,stroke:#2e7d32; class LayoutNode,HomeNode,ChallengeNode,HabitNode,AchievementNode comp; ``` * **RootLayout**（`src/app/layout.tsx`）负责全局 HTML 框架、字体加载以及 `NotificationProvider` 包装。Sources: [layout.tsx](https://github.com/initialxko/writing/blob/main/src/app/layout.tsx) * **HomePage**（`src/app/page.tsx`）是首页入口，内部使用 `useAppStore` 拉取全局状态并渲染每日挑战、习惯追踪、成就卡片。Sources: [page.tsx](https://github.com/initialxko/writing/blob/main/src/app/page.tsx) --- ## 核心运行时流程 ### 1. 状态初始化与读取 ```mermaid graph TB StoreNode[useAppStore] --> ProgressNode[progress] StoreNode --> EssaysNode[essays] StoreNode --> SetDailyNode[setDailyChallenge] StoreNode --> AddAchNode[addAchievement] StoreNode --> UpdateHabitNode[updateHabitTracker] classDef store fill:#fff3e0,stroke:#ef6c00; class StoreNode,ProgressNode,EssaysNode,SetDailyNode,AddAchNode,UpdateHabitNode store; ``` * `useAppStore`（Zustand）在页面渲染时返回 **progress**（关卡、习惯追踪等）以及 **essays**（已写作文列表）。 * `setDailyChallenge`、`addAchievement`、`updateHabitTracker` 为状态写入函数，供后续交互调用。 ### 2. 每日挑战生成逻辑 ```mermaid graph TB GenerateNode[generateDailyChallenge] --> FilterNode[filterUnlockedTools] FilterNode --> PickToolNode[pickRandomTool] PickToolNode --> PickTaskNode[pickRandomTask] GenerateNode --> OutputNode[DailyChallenge对象] classDef func fill:#e3f2fd,stroke:#1565c0; class GenerateNode,FilterNode,PickToolNode,PickTaskNode,OutputNode func; ``` * `generateDailyChallenge` 只会从 **已解锁** 的工具中挑选（`writingTools.filter` + `progress.levels` 检查）。 * 若无可用工具，则回退到默认的 “自由写作”。 * 生成的对象包含 `date`, `task`, `streak`, `recommendedToolId` 等字段。Sources: [page.tsx](https://github.com/initialxko/writing/blob/main/src/app/page.tsx) ### 3. 挑战完成、换题、补签 ```mermaid graph TB CompleteNode[handleChallengeComplete] --> UpdateNode[setDailyChallenge] CompleteNode --> UnlockAchNode[addAchievement] SwapNode[handleSwapChallenge] --> NewTaskNode[generateNewTask] MakeupNode[handleMakeup] --> StreakNode[incrementStreak] classDef action fill:#f1f8e9,stroke:#558b2f; class CompleteNode,SwapNode,MakeupNode action; ``` * **完成**：标记 `completed:true`、递增 `streak`，并根据连续天数解锁对应成就（写作新手 / 一周坚持 / 写作达人）。 * **换题**：在已解锁工具中重新随机，若多次仍相同则追加随机后缀防止死循环。 * **补签**：仅在前一天未完成且 `canMakeup:true` 时可使用，单纯递增 `streak` 并同步到 `habitTracker`。 ### 4. 日期切换检测（`useEffect`） ```mermaid graph TB EffectNode[useEffect] --> TodayNode[today] EffectNode --> ChallengeDateNode[challengeDate] TodayNode -->|不同| NewChallengeNode[generateDailyChallenge] NewChallengeNode --> SetNode[setDailyChallenge] classDef hook fill:#fff8e1,stroke:#f9a825; class EffectNode,TodayNode,ChallengeDateNode,NewChallengeNode,SetNode hook; ``` * 每次渲染后比较当前日期与挑战日期，若跨天则生成新挑战并在未完成时开启一次补签机会。Sources: [page.tsx](https://github.com/initialxko/writing/blob/main/src/app/page.tsx) --- ## Tailwind 配置要点 Tailwind 通过 `tailwind.config.js` 扩展了 **莫兰迪色系**（`morandi`）以及自定义阴影、圆角、过渡等。 ```mermaid graph TB ConfigNode[tailwind.config.js] --> ColorsNode[morandi] ConfigNode --> ShadowNode[boxShadow] ConfigNode --> RadiusNode[borderRadius] ColorsNode --> BlueNode[blue] ColorsNode --> GreenNode[green] ColorsNode --> GrayNode[gray] classDef cfg fill:#e0f7fa,stroke:#006064; class ConfigNode,ColorsNode,ShadowNode,RadiusNode,BlueNode,GreenNode,GrayNode cfg; ``` * **颜色**：`morandi.blue`, `morandi.green`, `morandi.gray` 等在页面中用于背景渐变、文字、按钮等。 * **阴影**：`card`, `card-hover`, `glow` 系列在组件外层提供层次感。 * **圆角**：`xl`, `2xl`, `3xl` 对应 1rem、1.5rem、2rem，统一 UI 风格。 > 这些自定义值在 `src/app/page.tsx` 的类名（如 `bg-morandi-gray-100`、`shadow-card`）中直接引用。Sources: [tailwind.config.js](https://github.com/initialxko/writing/blob/main/tailwind.config.js) --- ## 调试技巧与常见问题 | 场景 | 推荐调试手段 | 关键观察点 | |------|--------------|------------| | **状态未更新** | 在 VS Code 中对 `useAppStore` 的 setter（如 `setDailyChallenge`）设置断点；使用 React DevTools 查看 Zustand store 快照。 | 确认 `progress`、`habitTracker` 是否被正确写回。 | | **每日挑战不切换** | 打印 `currentChallenge` 与 `new Date().toDateString()` 的比较结果；检查 `useEffect` 依赖数组是否包含 `currentChallenge`。 | 日期比较逻辑（`today !== challengeDate`）是否触发。 | | **换题循环卡死** | 在 `handleSwapChallenge` 中加入 `console.log(attempts)`，确认 `maxAttempts` 是否被触发。 | `available.some(tool => (tool.exercises?.length || 0) > 1)` 条件是否满足。 | | **Tailwind 样式未生效** | 运行 `npx tailwindcss -i ./src/input.css -o ./dist/output.css --watch` 检查是否生成对应类；确认 `tailwind.config.js` 的 `content` 路径覆盖了 `src/app/**/*.{js,ts,jsx,tsx,mdx}`。 | 类名拼写（如 `bg-morandi-beige-100`）是否在配置中存在。 | ### 常见错误代码示例 ```tsx // 错误：直接使用 # 作为注释会导致 Mermaid 解析错误 // 正确：使用 #35; 转义 // 示例：A->>B: C#35;语言 ``` > 上述示例说明在本页的 Mermaid 图中必须对 `#` 进行转义，否则会被当作注释。 --- ## 关键代码摘录 ### 1. `generateDailyChallenge`（核心生成函数） ```tsx const generateDailyChallenge = () => { const available = getAvailableToolsForChallenge(); const selected = available.length > 0 ? pickRandom(available) : writingTools[0]; const exercises = selected.exercises || []; const task = exercises.length > 0 ? pickRandom(exercises) : '自由写作：记录今天让你印象最深刻的一个瞬间（30字以内）'; return { date: new Date(), task, completed: false, streak: currentChallenge?.streak || 0, recommendedToolId: selected.id, canMakeup: false, }; }; ``` *仅使用已解锁工具，确保每日任务可执行。* Sources: [page.tsx](https://github.com/initialxko/writing/blob/main/src/app/page.tsx) ### 2. `handleChallengeComplete`（完成后状态更新） ```tsx const handleChallengeComplete = () => { const updatedChallenge = { ...currentChallenge!, completed: true, streak: (currentChallenge?.streak || 0) + 1 }; setCurrentChallenge(updatedChallenge); setDailyChallenge(updatedChallenge); // 成就解锁逻辑... }; ``` *递增 `streak` 并触发成就解锁。* Sources: [page.tsx](https://github.com/initialxko/writing/blob/main/src/app/page.tsx) ### 3. `RootLayout`（全局布局） ```tsx export default function RootLayout({ children }: { children: React.ReactNode }) { return (

{children}

); } ``` *提供全局字体、背景渐变以及通知上下文。* Sources: [layout.tsx](https://github.com/initialxko/writing/blob/main/src/app/layout.tsx) --- ## 结论本页梳理了 **本地运行与调试** 的完整链路：从依赖安装、Next.js 启动，到核心业务逻辑（每日挑战生成、完成、换题、补签）以及 Tailwind UI 配置。通过提供的 **Mermaid 流程图**、**状态表** 与 **调试要点**，开发者可以快速定位问题、扩展功能或迁移到其他环境。掌握这些要点后，您即可在本地高效迭代，确保每一次提交都保持业务逻辑的完整性与 UI 的一致性。