# inkcop_web_frontend

**Repository Path**: ipbasecc/inkcop_web_frontend

## Basic Information

- **Project Name**: inkcop_web_frontend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-29
- **Last Updated**: 2026-01-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Inkcop Frontend

基于 Astro 构建的现代化前端应用，集成 Strapi CMS 后端。

## 项目特性

- 🚀 **Astro 框架**: 现代化的静态站点生成器
- 🎨 **Tailwind CSS**: 实用优先的 CSS 框架
- 🧩 **组件库**: 基于 shadcn/ui 的完整组件系统
- 📱 **响应式设计**: 移动端优先的设计理念
- 🌐 **国际化支持**: 内置多语言支持
- 🔌 **Strapi 集成**: 完整的 CMS 后端集成

## 技术栈

- **前端框架**: Astro 4.x
- **样式框架**: Tailwind CSS
- **组件库**: shadcn/ui
- **类型系统**: TypeScript
- **包管理器**: pnpm
- **后端 CMS**: Strapi

## 快速开始

### 环境要求

- Node.js 18+
- pnpm 8+

### 安装依赖

```bash
pnpm install
```

### 环境变量配置

创建 `.env` 文件：

```env
# Strapi 后端配置（客户端可访问的必须使用 PUBLIC_ 前缀）
PUBLIC_STRAPI_URL=http://localhost:1337
# 可选：仅在服务端使用时仍可保留
STRAPI_URL=http://localhost:1337
STRAPI_API_TOKEN=your_api_token_here
```

### 开发服务器

```bash
pnpm dev
```

访问 http://localhost:4321

### 构建生产版本

```bash
pnpm build
```

### 预览构建结果

```bash
pnpm preview
```

## 项目结构

```
src/
├── components/          # 可复用组件
│   └── ui/             # shadcn/ui 组件
├── interfaces/          # TypeScript 接口定义
│   ├── article.ts      # 文章接口
│   └── pages.ts        # 页面接口
├── layouts/             # 页面布局
├── lib/                 # 工具库
├── pages/               # 页面路由
└── styles/              # 全局样式
```

## 数据接口

### Article (文章)

文章内容类型，支持富文本内容和封面图片。

**字段结构:**
- `title`: 文章标题 (string, 必填)
- `description`: 文章描述 (text, 可选)
- `cover`: 封面图片 (media, 可选)
- `content`: 文章内容 (richtext, 必填)

**API 端点:**
- `GET /api/articles` - 获取文章列表
- `GET /api/articles?populate=cover` - 获取文章列表（包含封面图片）
- `GET /api/articles/{id}` - 获取单篇文章

### Page (页面)

页面内容类型，支持多种页面结构和媒体内容。

**字段结构:**
- `title`: 页面标题 (string, 必填)
- `description`: 页面描述 (text, 可选)
- `slug`: 页面标识 (enum: "services" | "updates" | "about" | "contact")
- `icon`: 页面图标 (media, 可选)
- `header_image`: 头部图片 (media, 可选)
- `group`: 页面分组 (string, 可选)
- `sub_pages`: 子页面 (relation, 可选)
- `parent_pages`: 父页面 (relation, 可选)
- `sections`: 页面区块 (component, 可选)

**API 端点:**
- `GET /api/pages` - 获取页面列表
- `GET /api/pages/{id}` - 获取单个页面

## 组件库

项目使用 shadcn/ui 组件库，包含以下组件：

- **基础组件**: Button, Input, Label, Card
- **导航组件**: Navigation Menu, Breadcrumb, Pagination
- **反馈组件**: Alert, Dialog, Toast, Progress
- **数据展示**: Table, Tabs, Accordion, Badge
- **布局组件**: Sheet, Sidebar, Resizable, Separator

## 开发指南

### 添加新组件

1. 使用 shadcn/ui CLI 添加组件：
```bash
pnpm dlx shadcn@latest add [component-name]
```

2. 组件将自动添加到 `src/components/ui/` 目录

### 创建新页面

1. 在 `src/pages/` 目录下创建 `.astro` 文件
2. 使用 `Layout.astro` 作为基础布局
3. 导入必要的组件和接口

### 添加新接口

1. 在 `src/interfaces/` 目录下创建 `.ts` 文件
2. 定义 TypeScript 接口
3. 在需要的地方导入使用

## 部署

### 静态部署

项目构建后生成静态文件，可部署到：

- Vercel
- Netlify
- GitHub Pages
- 任何静态文件托管服务

### 环境变量

确保在生产环境中正确配置：

- `STRAPI_URL`: Strapi 后端地址
- `STRAPI_API_TOKEN`: API 访问令牌

## 故障排除

### 常见问题

1. **Strapi 连接失败**
   - 检查后端服务是否运行
   - 验证环境变量配置
   - 确认网络连接

2. **组件样式问题**
   - 确保 Tailwind CSS 正确配置
   - 检查组件是否正确导入

3. **类型错误**
   - 运行 `pnpm type-check` 检查类型
   - 更新接口定义以匹配后端 schema

### 调试工具

- 使用 `/test` 页面测试 Strapi 连接
- 检查浏览器开发者工具
- 查看构建日志

## 贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

## 许可证

MIT License

## Users & Permissions 设置（Strapi）

- **启用邮箱提供者**: 在 Strapi 管理台 > Plugins > Users & Permissions > Providers，确保 Email 启用。
- **允许注册**: 管理台 > Plugins > Users & Permissions > Advanced settings，开启 Enable signups（根据需要）。
- **重置密码 URL**: 在 Advanced settings 配置 Reset password page 为前端地址，例如：
  - 开发：`http://localhost:4321/reset-password`
  - 多语言：也可使用 `/zh-CN/reset-password`（Strapi 会附带 `?code=...`）
- **CORS**: 确保后端允许来自前端域名的跨域（开发时 http://localhost:4321）。
- **环境变量**:
  ```env
  PUBLIC_STRAPI_URL=http://localhost:1337
  STRAPI_URL=http://localhost:1337
  ```
- **客户端调用**: 本项目使用 axios 调用 `/api/auth/local`, `/api/auth/local/register`, `/api/auth/forgot-password`, `/api/auth/reset-password`，参考官方文档。

参考文档：[Strapi Users & Permissions](https://docs.strapi.io/cms/features/users-permissions)