# claude_code_test

**Repository Path**: chjgfg/claude_code_test

## Basic Information

- **Project Name**: claude_code_test
- **Description**: claude code 测试
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-19
- **Last Updated**: 2026-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude Code 博客

基于 **Next.js + React + MySQL** 的个人博客完整示例：公开前台、管理后台、互动能力、访问分析与复杂 SQL 查询层。

适合作为学习 / 演示项目：前后端一体、表结构完整（32 张表）、后台可发文运营。

---

## 目录

- [技术栈](#技术栈)
- [功能一览](#功能一览)
- [快速开始](#快速开始)
- [环境变量](#环境变量)
- [数据库](#数据库)
- [项目结构](#项目结构)
- [路由与 API](#路由与-api)
- [自测清单](#自测清单)
- [设计约定](#设计约定)
- [生产注意](#生产注意)
- [常用命令](#常用命令)

---

## 技术栈

| 层级 | 选型 |
|------|------|
| 框架 | Next.js **16**（App Router）+ React **19** |
| 样式 | Tailwind CSS **v4** + 自定义 CSS 变量（浅/暗主题） |
| 数据库 | MySQL **8** + `mysql2` 连接池 |
| 鉴权 | JWT（`jose`）+ httpOnly Cookie + `bcryptjs` |
| 内容 | Markdown（`react-markdown` / GFM / 代码高亮） |
| 后台编辑 | `@uiw/react-md-editor` |
| 图表 | `recharts`（数据大盘） |
| 工具 | TypeScript、dayjs |

---

## 功能一览

### 前台

| 能力 | 说明 |
|------|------|
| 首页 | Banner、站点统计、最新文章、分类导航、标签云 |
| 文章详情 | Markdown、TOC、上下篇、相关文章（标签共现）、所属系列 |
| 分类 / 标签 | 列表 + 归档分页 |
| 归档 / 搜索 | 按月归档；全文检索（FULLTEXT + ngram） |
| 系列专栏 | 系列列表 + 系列内文章顺序 |
| 独立内容 | 关于、项目、留言板、友链、通用页 `/p/[slug]` |
| 互动 | 点赞、收藏、表情回应、评论、评论点赞、邮件订阅 |
| SEO / 订阅 | RSS（`/feed.xml`）、Sitemap、robots、邮件退订页 |
| 主题 | 浅色 / 暗色切换 |
| 站点配置 | 名称、描述、页脚、备案号等可读 `settings` 表（缺省回落代码配置） |

### 后台（`/admin`）

| 模块 | 能力 |
|------|------|
| 登录 | JWT 会话，默认 `admin` / `123456` |
| 数据大盘 | PV/UV、趋势、热门文章/标签、设备与来源分布、搜索热词、评论时段 |
| 文章 | 列表筛选、Markdown 编辑、分类/标签、置顶、状态、**历史版本载入/回滚** |
| 分类 / 标签 | 增删改（分类支持父子层级） |
| 评论 | 审核（通过 / 待审 / 垃圾）、删除 |
| 系列 | 增删改、绑定文章（回填已选） |
| 独立页 | 增删改（Markdown） |
| 轮播 / 友链 / 媒体 | 增删改；媒体支持 URL 登记 |
| 菜单 | header / footer 菜单项增删改 |
| 设置 | 站点 KV 配置 |
| 订阅 | 列表、退订/恢复、删除 |
| 通知 | 新评论自动通知；单条/全部已读、删除 |
| 用户 | 列表、新建、改角色/状态/密码、禁用 |

### 数据与 SQL 亮点

- 32 张表，字段/表均有中文 COMMENT，逻辑外键在注释中标明
- 递归 CTE：分类树、评论树、菜单树
- 标签共现、相关文章排序、窗口函数趋势
- 访问埋点、搜索日志、每日物化汇总
- **无物理 FOREIGN KEY**（关联字段 + 索引 + 应用层一致性）

---

## 快速开始

### 环境要求

- Node.js 18+（建议 20+）
- 本地 MySQL 8（默认账号见下）

### 1. 安装依赖

```bash
npm install
```

### 2. 初始化数据库

确保 MySQL 已启动，然后：

```bash
npm run db:init
```

脚本会：

1. 执行 `db/schema.sql` 建库建表  
2. 执行 `db/seed.sql` 写入演示内容  
3. 程序化生成访问/分析类模拟数据  

默认连接：

| 项 | 默认值 |
|----|--------|
| Host | `127.0.0.1` |
| Port | `3306` |
| User | `root` |
| Password | `123456` |
| Database | `claude_code_test` |

可用环境变量覆盖（见 [环境变量](#环境变量)）。

### 3. 启动开发服务

```bash
npm run dev
```

| 入口 | 地址 |
|------|------|
| 前台 | http://localhost:3000 |
| 后台 | http://localhost:3000/admin |
| 默认账号 | `admin` / `123456` |

### 4. 生产构建（可选）

```bash
npm run build
npm start
```

---

## 环境变量

复制示例文件后按需修改：

```bash
cp .env.example .env.local
```

| 变量 | 说明 | 默认 |
|------|------|------|
| `DB_HOST` | MySQL 主机 | `127.0.0.1` |
| `DB_PORT` | 端口 | `3306` |
| `DB_USER` | 用户 | `root` |
| `DB_PASSWORD` | 密码 | `123456` |
| `DB_NAME` | 库名 | `claude_code_test` |
| `JWT_SECRET` | JWT 签名密钥 | 开发用固定值（**生产必改**） |
| `COMMENT_REVIEW` | `1` 时新评论进入待审 | 未设置则直接通过 |

连接与站点默认值也在 `src/config/site.ts` 中定义。

---

## 数据库

### 相关文件

| 文件 | 用途 |
|------|------|
| `db/schema.sql` | 建库建表 + 表/字段注释（含逻辑外键说明） |
| `db/seed.sql` | 演示数据（用户、文章、分类、菜单等） |
| `db/drop-fk.sql` | 批量删除历史物理外键（若库中曾有 FK） |
| `db/alter-comments.sql` | 给**已有库**补全表/字段注释（不删数据） |
| `scripts/init-db.ts` | 一键初始化（`npm run db:init`） |

### 表分组（共 32 张）

| 分组 | 表 |
|------|----|
| 账户 | `users` `sessions` `login_logs` |
| 内容 | `categories` `tags` `posts` `post_categories` `post_tags` `post_meta` `post_revisions` `series` `series_posts` `pages` |
| 互动 | `comments` `comment_likes` `likes` `reactions` `bookmarks` `subscriptions` |
| 站点 | `settings` `menus` `menu_items` `friend_links` `media` `banners` |
| 分析 | `visitor_sessions` `page_views` `search_logs` `events` `analytics_daily` `api_logs` `notifications` |

### 仅补注释（已有数据时）

```bash
mysql -uroot -p123456 claude_code_test < db/alter-comments.sql
```

### 完全重建

```bash
npm run db:init
```

会 `DROP` 后重建表并重新灌数，**现有数据会清空**。

---

## 项目结构

```
claude_code_test/
├── db/
│   ├── schema.sql              # DDL + 注释
│   ├── seed.sql                # 种子数据
│   ├── drop-fk.sql             # 移除物理外键
│   └── alter-comments.sql      # 补注释
├── scripts/
│   └── init-db.ts              # 数据库初始化
├── src/
│   ├── app/
│   │   ├── (public)/           # 前台页面（Route Group）
│   │   ├── admin/              # 后台页面
│   │   │   ├── login/
│   │   │   └── (dashboard)/    # 带侧栏的后台布局
│   │   ├── api/                # REST API
│   │   │   ├── admin/          # 需登录的后台 API
│   │   │   ├── auth/           # 登录 / 登出 / 当前用户
│   │   │   ├── comments/       # 评论
│   │   │   ├── like/           # 点赞
│   │   │   ├── bookmark/       # 收藏
│   │   │   ├── react/          # 表情
│   │   │   ├── comment-like/   # 评论点赞
│   │   │   ├── subscribe/      # 订阅 / 退订
│   │   │   └── track/          # 访问埋点
│   │   ├── layout.tsx          # 根布局
│   │   └── globals.css         # 设计系统 / 组件类
│   ├── components/
│   │   ├── admin/              # 后台壳、图表、通用 UI
│   │   ├── layout/             # Header / Footer / 主题
│   │   ├── markdown/           # Markdown 渲染
│   │   └── post/               # 卡片、评论、互动条、TOC…
│   ├── config/
│   │   └── site.ts             # DB / JWT / 站点默认配置
│   ├── lib/
│   │   ├── adminFetch.ts       # 后台 fetch 封装
│   │   └── format.ts           # 日期 / 数字格式化
│   └── server/
│       ├── apiHelpers.ts       # withAdmin 鉴权包装
│       ├── auth.ts             # 登录会话
│       ├── db/pool.ts          # 连接池 + 事务
│       ├── queries/            # 按领域拆分的 SQL 层
│       ├── types.ts            # 共享类型
│       └── utils.ts            # 分页 / UA / 指纹等
├── .env.example
├── AGENTS.md / CLAUDE.md       # AI 协作说明（Next 文档路径）
├── package.json
└── README.md
```

**分层约定：**

- 页面 / Route Handler → `server/queries/*` → `db/pool`  
- 后台写操作统一走 `withAdmin`（鉴权失败 401）  
- 业务 SQL 尽量集中在 `queries`，避免页面内拼复杂 SQL  

---

## 路由与 API

### 前台页面

| 路径 | 说明 |
|------|------|
| `/` | 首页 |
| `/posts/[slug]` | 文章详情 |
| `/categories` `/category/[slug]` | 分类 |
| `/tags` `/tag/[slug]` | 标签 |
| `/archive` | 归档 |
| `/search` | 搜索 |
| `/series` `/series/[slug]` | 系列 |
| `/links` `/guestbook` `/about` `/projects` | 友链 / 留言 / 关于 / 项目 |
| `/p/[slug]` | 通用独立页 |
| `/unsubscribe` | 邮件退订 |
| `/feed.xml` | RSS |
| `/sitemap.xml` `/robots.txt` | SEO |

### 后台页面

| 路径 | 说明 |
|------|------|
| `/admin/login` | 登录 |
| `/admin` | 数据大盘 |
| `/admin/posts` `/admin/posts/[id]` | 文章列表 / 编辑（`new` 为新建） |
| `/admin/categories` `/admin/tags` | 分类 / 标签 |
| `/admin/comments` | 评论审核 |
| `/admin/series` | 系列 |
| `/admin/pages` `/admin/pages/[id]` | 独立页 |
| `/admin/banners` `/admin/links` `/admin/media` | 轮播 / 友链 / 媒体 |
| `/admin/menus` | 菜单 |
| `/admin/settings` | 站点设置 |
| `/admin/subscriptions` | 邮件订阅 |
| `/admin/notifications` | 通知 |
| `/admin/users` | 用户 |

### 公开 API（节选）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST/GET | `/api/like` | 文章点赞 toggle / 是否已赞 |
| POST/GET | `/api/bookmark` | 收藏 |
| POST/GET | `/api/react` | 表情回应 |
| POST | `/api/comment-like` | 评论点赞 |
| GET/POST | `/api/comments` | 评论列表 / 提交（会通知管理员） |
| POST/DELETE | `/api/subscribe` | 订阅 / 按 token 退订 |
| POST | `/api/track` | 访问埋点 |
| POST/DELETE/GET | `/api/auth` | 登录 / 登出 / 当前用户 |

### 后台 API

前缀 `/api/admin/*`，均需登录 Cookie。覆盖：

`posts`（含 `revisions`）、`categories`、`tags`、`comments`、`series`、`pages`、`banners`、`links`、`media`、`menus`、`settings`、`subscriptions`、`notifications`、`users`。

响应格式统一为：

```json
{ "ok": true, "data": ... }
// 或
{ "ok": false, "message": "..." }
```

---

## 自测清单

### 最短路径（约 10 分钟）

1. `npm run db:init` → `npm run dev`  
2. 打开前台，浏览首页与一篇文章  
3. 登录 `/admin`（`admin` / `123456`）  
4. **新建并发布**一篇文章  
5. 前台打开该文：点赞、收藏、表情、发评论、评论点赞  
6. 后台：**评论**可见；**通知**有新评论提醒  
7. **设置**改站点名 → 刷新前台 Header/Footer  
8. 文章编辑页保存两次 → 侧栏**历史版本**可载入/回滚  

### 前台互动

| 操作 | 预期 |
|------|------|
| 点赞 / 收藏 | 数字变化，刷新后状态保持（指纹） |
| 表情 | 对应计数增加 |
| 评论 | 提交成功；未开审核时列表可见 |
| 页脚订阅 | 成功或「已订阅」提示（非裸 JSON 页） |

### 后台 CRUD

- 分类/标签/系列/菜单/友链/轮播：增、**改**、删  
- 系列「绑定文章」：打开后勾选状态应回填  
- 用户：新建 editor → 改密 → 禁用后不可登录  
- 订阅：退订 / 恢复 / 删除  

### 常见问题

| 现象 | 处理 |
|------|------|
| 连不上库 | 检查 MySQL 是否启动、账号密码、`.env` |
| 登录后立刻掉线 | 清 Cookie；确认 `JWT_SECRET` 稳定 |
| 站点名不更新 | 前台部分页面 `revalidate=60`，硬刷新或等 1 分钟 / 重启 dev |
| 评论不显示 | 若 `COMMENT_REVIEW=1`，需后台审核 |
| 搜索无结果 | 换 seed 中已有关键词；确认 FULLTEXT 索引存在 |
| 初始化失败 | 看终端报错；确认 root 可连、端口 3306 |

---

## 设计约定

1. **逻辑外键**：表间用 `*_id` + 索引，不建物理 `FOREIGN KEY`；注释中写 `逻辑外键 → 表.列`。  
2. **冗余计数**：`posts.like_count` / `comment_count` 等与明细表同步维护，读多写少。  
3. **访客指纹**：点赞/收藏用 IP+UA 哈希，无需登录。  
4. **settings 优先**：前台展示名等优先读 DB，`siteConfig` 作默认回落。  
5. **Next 版本**：本仓库 Next 可能与旧教程 API 不同，写代码前参考 `node_modules/next/dist/docs/`（见 `AGENTS.md`）。

---

## 生产注意

- [ ] 修改 `JWT_SECRET`、数据库密码，不要用默认 `admin/123456`  
- [ ] 使用 HTTPS，Cookie 可考虑 `secure`  
- [ ] 关闭或限制 `COMMENT_REVIEW`、注册等开关  
- [ ] 媒体目前为 **URL 登记**，未接对象存储；上线需自行接上传  
- [ ] 定期备份 MySQL；分析表会随访问增长  

---

## 常用命令

```bash
npm install          # 安装依赖
npm run db:init      # 初始化 / 重建数据库
npm run dev          # 开发模式 http://localhost:3000
npm run build        # 生产构建
npm start            # 启动生产服务
npm run lint         # ESLint
```

补注释（不重建）：

```bash
mysql -uroot -p123456 claude_code_test < db/alter-comments.sql
```

---

## License

私有演示项目（`private: true`）。按需自行约定授权。