BingLogyBlog-Frontend/.opencode/plans/PLAN.md

Nuxt4 + Nuxt-UI 博客前端开发提示词

项目概述

# 任务：构建 LinkShare Blog 前端应用

## 技术栈

- **框架**: Nuxt 4 (Vue 3 + Vite)
- **UI 库**: Nuxt UI (基于 Tailwind CSS + Headless UI)
- **状态管理**: Pinia
- **HTTP 客户端**: fetch / ofetch
- **Markdown 渲染**: @nuxt/content 或 markdown-it
- **代码规范**: ESLint + Prettier

## 后端 API 信息

- **地址**: http://localhost:3001 (开发) / https://api.example.com (生产)
- **认证**: Session Cookie (HttpOnly)
- **文档**: http://localhost:3001/api-docs

---

1. 项目初始化

请创建一个 Nuxt 4 项目，要求：

1. 安装 Nuxt UI: `npx nuxi@latest module add ui`
2. 配置 Tailwind CSS
3. 配置 Pinia 状态管理
4. 设置 API 请求拦截器（携带 Cookie）
5. 配置路由中间件（认证守卫）
6. 创建布局文件：default.vue、admin.vue

目录结构：

├── components/ │ ├── ui/ # Nuxt UI 组件封装 │ ├── layout/ # 布局组件 │ ├── article/ # 文章相关组件 │ ├── comment/ # 评论相关组件 │ └── admin/ # 管理后台组件 ├── composables/ │ ├── useAuth.ts # 认证逻辑 │ ├── useApi.ts # API 请求封装 │ └── useArticles.ts # 文章数据获取 ├── layouts/ │ ├── default.vue # 默认布局 │ └── admin.vue # 管理后台布局 ├── middleware/ │ ├── auth.global.ts # 全局认证检查 │ └── admin.ts # 管理员权限检查 ├── pages/ │ ├── index.vue # 首页（文章列表） │ ├── article/ │ │ └── [slug].vue # 文章详情 │ ├── login.vue # 登录页 │ ├── create.vue # 创建文章 │ └── admin/ │ ├── dashboard.vue # 管理后台首页 │ ├── articles.vue # 文章管理 │ ├── comments.vue # 评论管理 │ └── users.vue # 用户管理 ├── stores/ │ ├── auth.ts # 认证状态 │ └── article.ts # 文章状态 ├── types/ │ ├── api.ts # API 响应类型 │ └── models.ts # 数据模型 └── utils/ ├── constants.ts # 常量配置 └── validators.ts # 表单验证

---

2. API 类型定义

请根据后端 API 创建 TypeScript 类型定义：

### 用户模型 (User)

- id: number
- email: string
- username: string
- displayName: string | null
- avatarUrl: string | null
- role: 'admin' | 'moderator' | 'user'
- isActive: boolean
- createdAt: DateTime
- updatedAt: DateTime

### 文章模型 (Article)

- id: number
- slug: string
- title: string
- content: string | null (Markdown)
- excerpt: string | null
- coverImageUrl: string | null
- status: 'draft' | 'published' | 'archived'
- visibility: 'public' | 'unlisted' | 'private'
- viewCount: number
- publishedAt: DateTime | null
- createdAt: DateTime
- updatedAt: DateTime
- author: User (仅 id, username, displayName, avatarUrl)
- comments: Comment[] (已审核)
- reactions: Reaction[]

### 评论模型 (Comment)

- id: number
- articleId: number
- parentId: number | null
- content: string
- status: 'pending' | 'approved' | 'rejected' | 'suspicious'
- authorName: string | null
- authorEmail: string | null
- authorId: number | null
- createdAt: DateTime
- updatedAt: DateTime
- author: User | null
- replies: Comment[]

### 分页响应

{
items: T[]
total: number
page: number
limit: number
totalPages: number
}

### API 端点

#### 认证

- POST /login - { emailOrUsername, password } → { user }
- POST /logout - → { ok: true }
- GET /me - → { user }

#### 文章

- GET /articles?page=1&limit=20&status=&visibility=&authorId=
- GET /articles/:id
- GET /articles/slug/:slug
- POST /articles (需登录) - { title, content, excerpt?, coverImageUrl?, status, visibility }
- PUT /articles/:id (作者/管理员)
- DELETE /articles/:id (作者/管理员)

#### 评论

- GET /articles/:id/comments?status=approved
- POST /articles/:id/comments (需登录) - { content }

#### 管理后台 (需 admin 角色)

- GET /admin/comments?page=&limit=&articleId=&status=&authorId=
- PUT /admin/comments/:id/status?status=approved|rejected
- DELETE /admin/comments/:id
- GET /admin/comments/:id/audits
- GET /admin/articles?page=&limit=&status=
- GET /analytics-summary?days=30

---

3. 认证 Composable

创建 useAuth composable，实现：

### 状态管理

- user: Ref<User | null>
- isAuthenticated: ComputedRef<boolean>
- isAdmin: ComputedRef<boolean>
- isLoading: Ref<boolean>

### 方法

- login(credentials): Promise<User>
- logout(): Promise<void>
- fetchUser(): Promise<User | null>
- checkAuth(): Promise<boolean>

### 要求

- 自动携带 Cookie (credentials: 'include')
- 错误处理（401 清除用户状态）
- SSR 兼容（useFetch + useNuxtApp）
- 登录成功后自动跳转回上一页

---

4. 文章列表页

创建首页文章列表，要求：

### 布局

- 顶部导航栏（Logo、菜单、登录/用户头像）
- 响应式网格布局（移动端 1 列，桌面 3 列）
- 分页组件（使用 Nuxt UI 的 UPagination）

### 文章卡片 (UCard 组件)

- 封面图（可选，使用 UImage）
- 标题（UButton 样式，链接到详情页）
- 摘要（最多 150 字）
- 作者信息（头像 + 名称）
- 发布时间（相对时间，如"3 天前"）
- 查看数（UIcon + 数字）
- 状态标签（UBadge：已发布/草稿/归档）

### 筛选功能

- 搜索框（按标题）
- 状态下拉框（全部/已发布/草稿/归档）
- 作者筛选（可选）
- URL 同步筛选参数（使用 useRouteQuery）

### 加载状态

- 骨架屏（USkeleton）
- 空状态（UEmpty：无文章时显示）
- 错误状态（UAlert：加载失败时）

### SEO

- useSeoMeta 设置 title、description
- Open Graph 标签

---

5. 文章详情页

创建文章详情页（/article/[slug]），要求：

### 页面结构

- 文章头部：标题、作者信息、发布时间、查看数
- 封面图（如果有）
- Markdown 内容渲染区
- 文章底部：标签、分享按钮

### Markdown 渲染

- 使用 @nuxt/content 或 markdown-it
- 支持代码高亮（Prism.js / Shiki）
- 支持表格、引用、列表
- 响应式图片（懒加载）

### 评论系统

- 评论列表（嵌套回复，最多 2 层）
- 评论表单（登录后可评论）
- 评论状态提示（待审核/已通过/已拒绝）
- 实时刷新（提交后刷新评论列表）

### 侧边栏（桌面端）

- 目录（TOC，基于文章标题自动生成）
- 相关文章推荐
- 作者信息卡片

### 功能

- 文章版本历史（如果有多版本）
- 密码保护文章（输入密码后查看）
- 私密文章验证（通过 token 访问）
- 阅读进度条（顶部固定）

### 交互

- 点赞/表情反应（ULikeButton 风格）
- 分享功能（复制链接、Twitter、微信）
- 返回目录（滚动监听）

---

6. 创建/编辑文章页

创建文章编辑器（/create 和 /article/[id]/edit），要求：

### 编辑器布局

- 左右分栏（左侧编辑，右侧预览）
- 可切换全屏编辑模式
- 实时预览（防抖，500ms）

### 表单字段 (使用 UForm + UInput)

- 标题（UInput，最大 200 字，必填）
- Slug（自动生成，可手动修改）
- 内容（UTextarea，支持 Markdown 语法提示）
- 摘要（UTextarea，最大 500 字，可选）
- 封面图 URL（UInput，可选）
- 状态（URadio：草稿/已发布/归档）
- 可见性（URadio：公开/未列出/私密）
- 访问令牌（私密文章时显示）

### 验证规则

- 标题：必填，1-200 字
- 内容：必填
- 摘要：可选，0-500 字
- 自动保存草稿（每 60 秒）

### 功能

- Markdown 工具栏（粗体、斜体、链接、图片、代码块）
- 图片上传（拖拽上传，返回 URL）
- 发布确认对话框
- 版本历史（显示编辑记录）

### 权限

- 仅作者和管理员可编辑
- 未授权时显示 403 页面

---

7. 登录页

创建登录页（/login），要求：

### 表单设计 (UCard 居中布局)

- 邮箱/用户名输入框（UInput）
- 密码输入框（UInput type="password"）
- 记住我复选框（UCheckbox）
- 登录按钮（UButton，带加载状态）
- 忘记密码链接（可选）

### 验证

- 邮箱/用户名：必填
- 密码：必填，最少 6 位
- 错误提示（UAlert 显示在表单顶部）

### 功能

- 限流处理（5 次/分钟，显示重试时间）
- 登录成功后跳转到来源页面
- 已登录用户自动跳转到首页
- Social 登录按钮（预留位置）

### 安全

- CSRF Token（如后端需要）
- HTTPS 强制（生产环境）

---

8. 管理后台

创建管理后台（/admin/\*），要求：

### 布局 (admin.vue)

- 侧边栏导航（文章管理、评论管理、用户管理、数据分析）
- 顶部栏（返回首页、用户信息、退出登录）
- 权限检查（仅 admin 角色可访问）

### 评论管理页 (/admin/comments)

- 表格展示（UTable）
  - 评论内容（截断）
  - 文章标题（链接）
  - 作者（名称/邮箱）
  - 状态（UBadge：待审核/通过/拒绝/可疑）
  - 创建时间
  - 操作（审核通过/拒绝/删除/查看日志）
- 筛选：文章 ID、状态、作者、分页
- 批量操作（批量通过/拒绝/删除）
- 审核日志弹窗（显示 AI 审核记录）

### 文章管理页 (/admin/articles)

- 表格展示
  - 标题 + 封面图缩略图
  - 作者
  - 状态（UBadge）
  - 可见性（UIcon）
  - 查看数
  - 发布时间
  - 操作（编辑/删除/强制发布/归档）
- 筛选：状态、可见性、作者、分页
- 强制操作（管理员可编辑/删除任何文章）

### 用户管理页 (/admin/users)

- 表格展示
  - 用户信息（头像 + 名称 + 邮箱）
  - 角色（UBadge：admin/moderator/user）
  - 状态（激活/禁用）
  - 创建时间
  - 操作（编辑角色/禁用/删除）
- 创建用户按钮（弹窗表单）

### 数据分析页 (/admin/analytics)

- 数据卡片（UStat）
  - 总文章数
  - 总评论数
  - 总用户数
  - 近 30 天查看数
- 图表（使用 Chart.js 或 ECharts）
  - 每日查看趋势
  - 热门文章 Top 10
  - 评论审核统计

---

9. 评论组件

创建评论系统组件，要求：

### 评论列表 (CommentList.vue)

- 嵌套结构（父评论 + 回复列表）
- 头像 + 用户名 + 时间
- 内容（支持简单 Markdown）
- 状态标签（待审核/已审核）
- 回复按钮（登录后可用）
- 点赞数（可选）

### 评论表单 (CommentForm.vue)

- 文本域（最小 3 行，支持 Markdown）
- 字符计数器（最大 2000 字）
- 提交按钮（带加载状态）
- 登录提示（未登录时显示）
- 预览功能（可选）

### 回复表单 (ReplyForm.vue)

- 简化版评论表单
- 内联显示（点击回复后展开）
- 取消按钮

### 审核提示

- 提交成功：显示"评论待审核"
- 审核通过：自动刷新显示评论
- 审核拒绝：显示拒绝原因（如果公开）

### 权限

- 仅登录用户可评论
- 作者/管理员可删除评论
- 管理员可在后台审核

---

10. 全局组件

创建以下全局通用组件：

### 导航栏 (AppHeader.vue)

- Logo（左侧）
- 菜单（首页、关于、管理后台）
- 搜索框（可选）
- 用户菜单（头像下拉：个人中心、退出登录）
- 登录/注册按钮（未登录时）
- 移动端汉堡菜单

### 页脚 (AppFooter.vue)

- 版权信息
- 友情链接
- Social 图标
- ICP 备案（如果需要）

### 加载器 (AppLoading.vue)

- 全局加载中（USpinner）
- 页面切换进度条（NuxtPageTransition）

### 错误页 (AppError.vue)

- 404 页面（UEmpty + 返回首页按钮）
- 403 页面（无权限提示）
- 500 页面（服务器错误）

### SEO 组件 (SeoMeta.vue)

- 动态设置 title、description
- Open Graph 标签
- Twitter Card 标签
- JSON-LD 结构化数据

---

11. Pinia Store

创建以下 Pinia stores：

### auth store (stores/auth.ts)

- State: user, isLoading, error
- Getters: isAuthenticated, isAdmin, userRole
- Actions: login, logout, fetchUser, checkAuth, refreshUser

### article store (stores/article.ts)

- State: articles, currentArticle, loading, pagination
- Getters: publishedArticles, draftArticles, totalArticles
- Actions: fetchArticles, fetchArticle, createArticle, updateArticle, deleteArticle

### comment store (stores/comment.ts)

- State: comments, loading
- Getters: approvedComments, pendingComments
- Actions: fetchComments, createComment, approveComment, rejectComment, deleteComment

### admin store (stores/admin.ts)

- State: stats, loading
- Getters: commentStats, articleStats, userStats
- Actions: fetchStats, updateCommentStatus, deleteUser

---

12. 样式与主题

配置 Nuxt UI 主题：

### 颜色方案 (nuxt.config.ts)

```ts
export default defineNuxtConfig({
  ui: {
    primary: 'indigo',
    gray: 'slate',
    theme: {
      dark: true, // 支持暗色模式
    },
  },
});
```

自定义样式 (assets/css/main.css)

• 全局字体（Inter / Noto Sans SC）
• 文章排版样式（prose 类）
• 代码块主题（One Dark / GitHub）
• 响应式断点调整

暗色模式切换

• 使用 useDark() 和 useToggle()
• 切换按钮（UIcon：sun/moon）
• 持久化到 localStorage
• 系统偏好自动检测

---

## 13. SEO 优化

```markdown
实现 SEO 优化：

### 动态 Meta 标签 (useSeoMeta)
- title / titleTemplate
- description
- canonical URL
- robots

### Open Graph
- og:title
- og:description
- og:image（文章封面）
- og:url
- og:type

### Twitter Card
- twitter:card
- twitter:title
- twitter:description
- twitter:image

### 结构化数据 (JSON-LD)
- Article Schema（文章页）
- BreadcrumbList（面包屑）
- Organization（网站信息）

### Sitemap
- @nuxtjs/sitemap 模块
- 自动生成文章路由
- 静态路由配置

---

14. 性能优化

实现性能优化：

### 图片优化

- Nuxt Image 模块（自动 WebP）
- 懒加载（loading="lazy"）
- 响应式图片（srcset）
- LQIP（低质量占位图）

### 代码分割

- 路由懒加载（默认启用）
- 组件异步加载（defineAsyncComponent）
- 第三方库按需引入

### 缓存策略

- API 响应缓存（useFetch + cache）
- 静态资源 CDN
- Service Worker（可选）

### 渲染优化

- 骨架屏（Skeleton）
- 虚拟滚动（长列表）
- 防抖/节流（搜索、滚动）
- 预加载（hover 时预加载文章）

---

15. 测试

编写测试：

### 单元测试 (Vitest)

- Composables 测试
- Utils 函数测试
- Stores 测试

### 组件测试 (Vue Test Utils)

- 按钮点击
- 表单验证
- 条件渲染

### E2E 测试 (Playwright)

- 登录流程
- 文章创建/编辑
- 评论提交
- 管理后台操作

### 测试覆盖率

- 目标：80%+
- 关键路径：认证、文章 CRUD、评论审核

---

16. 环境变量配置

配置环境变量：

### .env 文件

```env
NUXT_PUBLIC_API_BASE=http://localhost:3001
NUXT_PUBLIC_SITE_URL=http://localhost:3000
NUXT_PUBLIC_SITE_NAME=LinkShare Blog
```

nuxt.config.ts

runtimeConfig: {
  public: {
    apiBase: process.env.NUXT_PUBLIC_API_BASE,
    siteUrl: process.env.NUXT_PUBLIC_SITE_URL,
  }
}

类型安全

declare module '@nuxt/schema' {
  interface RuntimeConfig {
    public: {
      apiBase: string;
      siteUrl: string;
    };
  }
}

---

## 17. 部署配置

```markdown
部署配置：

### Dockerfile
```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["node", ".output/server/index.mjs"]

Docker Compose

services:
  frontend:
    build: .
    ports:
      - '3000:3000'
    environment:
      - NUXT_PUBLIC_API_BASE=http://api:3001

Nginx 配置

• 反向代理到 Nuxt
• 静态资源缓存
• Gzip 压缩
• HTTPS 配置

---

## 开发优先级

1. **第一阶段 - 核心功能**
   - 项目初始化
   - 认证系统（登录/登出）
   - 文章列表页
   - 文章详情页
   - 评论系统

2. **第二阶段 - 内容创作**
   - 文章创建/编辑页
   - Markdown 编辑器
   - 图片上传

3. **第三阶段 - 管理后台**
   - 管理后台布局
   - 评论管理
   - 文章管理
   - 用户管理

4. **第四阶段 - 优化与完善**
   - SEO 优化
   - 性能优化
   - 测试覆盖
   - 部署配置

---

## 后端 API 参考

### 数据库模型 (Prisma Schema)

详见 `prisma/schema.prisma`，主要模型：
- User（用户）
- Article（文章）
- Comment（评论）
- ArticleVersion（文章版本）
- CommentAudit（评论审核日志）
- OAuth2Token（OAuth2 令牌）
- AnalyticsEvent（分析事件）

### 认证机制

- **Web 端**: Session Cookie（HttpOnly，Secure）
- **API 端**: OAuth2 Bearer Token
- **角色**: admin、moderator、user
- **限流**: /login 和 /oauth2/token 接口 5 次/分钟

### 内容审核

- **规则审核**: 敏感词、长度限制
- **AI 审核**: OpenRouter API（异步）
- **状态**: pending → approved/rejected/suspicious
- **审计**: 所有审核操作记录到 CommentAudit

---

**创建日期**: 2026-03-28
**后端版本**: 1.0.0
**适用框架**: Nuxt 4 + Nuxt UI