# qingke

**Repository Path**: chging/qingke

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-06
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 青刻纪念（QingKe Memories）

> **AI 驱动的毕业纪念品定制系统** · 上传照片 · AI 定制画芯 · 亚克力夹画立牌

[![线上地址](https://img.shields.io/badge/线上地址-qingmems--fhhztngd.manus.space-blue)](https://qingmems-fhhztngd.manus.space)
[![技术栈](https://img.shields.io/badge/技术栈-React%2019%20%2B%20tRPC%20%2B%20Express%204%20%2B%20MySQL-green)](#技术栈)

---

![image-20260513203540677](README.assets/image-20260513203540677.png)

![image-20260513203634322](README.assets/image-20260513203634322.png)

## 项目简介

青刻纪念是一款面向毕业季场景的 AI 定制纪念品电商平台。用户上传个人照片后，系统通过 AI 图像生成技术（字节火山方舟 Seedream-5.0-lite）自动创作画芯图，并合成到亚克力夹画立牌产品效果图中，最终由商家完成实物生产与发货。

**核心特性**：

- 7 步引导式定制流程，上传照片到看到效果图约 30 秒
- 支持 4 种场景（单人款/宿舍纪念/致敬恩师/班级合照）× 6 种 AI 风格
- 完整的订单管理、支付确认、人工复核/精修工单流程
- 管理后台覆盖全部运营动作，无需开发技术能力
- AI 模型可插拔，通过后台配置切换，无需修改代码

---

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | React 19 · Wouter · TanStack Query · tRPC Client · Tailwind CSS 4 · shadcn/ui · Framer Motion |
| 后端 | Express 4 · tRPC Server · Drizzle ORM · Superjson |
| 数据库 | MySQL / TiDB（通过 `DATABASE_URL` 连接） |
| 文件存储 | AWS S3 兼容存储（通过 Manus Forge API 代理） |
| 认证 | Manus OAuth + JWT Session Cookie |
| AI 图像生成 | 字节火山方舟 Seedream-5.0-lite（可配置切换） |
| 构建工具 | Vite 6 · esbuild · TypeScript 5 · pnpm |

---

## 本地开发

### 前置要求

- Node.js >= 20
- pnpm >= 9
- MySQL 数据库（或 TiDB Cloud 免费版）
- Manus 平台账号（用于 OAuth 和 Forge API）

### 1. 克隆项目

```bash
git clone <repo-url>
cd qingke-memories
pnpm install
```

### 2. 配置环境变量

在项目根目录创建 `.env` 文件（参考 `.env.example`）：

```bash
# 数据库
DATABASE_URL=mysql://user:password@host:3306/qingke_memories

# JWT 签名密钥（随机字符串，至少 32 位）
JWT_SECRET=your-super-secret-jwt-key-at-least-32-chars

# Manus OAuth（从 Manus 平台获取）
VITE_APP_ID=your-manus-app-id
OAUTH_SERVER_URL=https://api.manus.im
VITE_OAUTH_PORTAL_URL=https://manus.im

# Manus Forge API（从 Manus 平台获取）
BUILT_IN_FORGE_API_URL=https://api.manus.im
BUILT_IN_FORGE_API_KEY=your-forge-api-key
VITE_FRONTEND_FORGE_API_KEY=your-frontend-forge-key
VITE_FRONTEND_FORGE_API_URL=https://api.manus.im

# 项目 Owner 信息（Manus 平台用户 ID）
OWNER_OPEN_ID=your-manus-open-id
OWNER_NAME=your-name
```

> **注意**：以 `VITE_` 开头的变量会暴露给前端，请勿将敏感密钥放入 `VITE_` 变量。

### 3. 初始化数据库

```bash
# 推送数据库 Schema（创建所有表）
pnpm db:push

# 查看数据库 Schema（可选）
pnpm db:studio
```

### 4. 启动开发服务器

```bash
pnpm dev
```

服务启动后访问 `http://localhost:3000`。

前端 Vite 开发服务器运行在同一端口（通过 Vite 代理转发 `/api/*` 到 Express）。

### 5. 配置 AI 模型

启动后进入管理后台（`/admin`），在 **系统配置 → 模型配置** 中新增 AI 模型：

| 字段 | 值 |
|------|----|
| 模型名称 | `Seedream-5.0-lite` |
| 服务商 | `字节火山方舟` |
| 模型代码 | `doubao-seedream-5-0-260128` |
| API 端点 URL | `https://ark.cn-beijing.volces.com/api/v3/images/generations` |
| API 密钥 | 你的火山方舟 API Key |

创建后点击"启用"，即可使用 AI 生成功能。

### 6. 配置支付收款码

进入管理后台 **系统配置 → 支付配置**，上传微信/支付宝收款二维码图片，填写客服联系方式。

---

## 数据库迁移

项目使用 Drizzle ORM 管理数据库 Schema，所有表定义在 `drizzle/schema.ts`。

```bash
# 修改 schema.ts 后，推送变更到数据库
pnpm db:push

# 生成迁移文件（可选，用于版本控制）
pnpm db:generate

# 可视化数据库管理界面
pnpm db:studio
```

> **警告**：`pnpm db:push` 会直接修改数据库结构，生产环境请先备份数据。

---

## 项目结构

```
qingke-memories/
├── client/src/
│   ├── pages/
│   │   ├── Home.tsx              # 主页
│   │   ├── customize/            # 定制流程（7步）
│   │   ├── ticket/               # 工单页面
│   │   └── admin/                # 管理后台（14个页面）
│   ├── components/               # 公共组件
│   └── lib/trpc.ts               # tRPC 客户端
├── server/
│   ├── routers/                  # tRPC 路由模块（13个）
│   ├── _core/                    # 框架核心（OAuth/存储/AI）
│   ├── db.ts                     # 数据库查询函数
│   └── aiGeneration.ts           # AI 生成逻辑
├── drizzle/
│   └── schema.ts                 # 数据库表定义（16张表）
└── shared/                       # 前后端共享常量
```

---

## 常用命令

```bash
pnpm dev          # 启动开发服务器
pnpm build        # 构建生产版本
pnpm start        # 启动生产服务器
pnpm test         # 运行 Vitest 测试
pnpm db:push      # 推送数据库 Schema 变更
pnpm db:studio    # 打开 Drizzle Studio（数据库可视化）
pnpm db:generate  # 生成迁移文件
```

---

## 部署上线

### 方式一：Manus 平台一键发布（推荐）

本项目基于 Manus WebDev 平台开发，支持一键发布：

1. 在 Manus 平台打开项目管理界面
2. 点击右上角 **Publish** 按钮
3. 等待约 2-3 分钟完成构建和部署
4. 访问自动分配的域名（格式：`xxx.manus.space`）

发布后可在 **Settings → Domains** 中绑定自定义域名。

> **注意**：发布前必须先创建 Checkpoint（检查点），Publish 按钮在有 Checkpoint 时才会激活。

### 方式二：自托管部署

如需自行部署，请确保满足以下条件：

**服务器要求**：
- Node.js >= 20
- 内存 >= 512MB
- 可访问外网（用于调用 AI API）

**部署步骤**：

```bash
# 1. 安装依赖
pnpm install --frozen-lockfile

# 2. 构建前端
pnpm build

# 3. 配置环境变量（参考上方"配置环境变量"章节）
cp .env.example .env
# 编辑 .env 填写所有必要变量

# 4. 推送数据库 Schema
pnpm db:push

# 5. 启动服务
pnpm start
# 或使用 PM2 管理进程
pm2 start "pnpm start" --name qingke-memories
```

**Nginx 反向代理配置（可选）**：

```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_bypass $http_upgrade;
        
        # 文件上传大小限制
        client_max_body_size 20M;
    }
}
```

**HTTPS 配置**：推荐使用 [Let's Encrypt](https://letsencrypt.org/) + Certbot 自动申请 SSL 证书。

> **重要**：自托管部署时，Manus OAuth 和 Forge API 功能需要有效的 Manus 平台账号和 API Key，否则登录和 AI 生成功能将不可用。

---

## 管理后台

访问 `/admin` 路径进入管理后台，需要账号角色为 `admin`。

**首次设置管理员**：通过数据库直接修改 `users` 表中目标用户的 `role` 字段为 `admin`：

```sql
UPDATE users SET role = 'admin' WHERE open_id = 'your-open-id';
```

**后台功能模块**：

| 菜单 | 路径 | 功能 |
|------|------|------|
| 仪表盘 | `/admin` | 订单/用户/收入统计 |
| 订单管理 | `/admin/orders` | 全部订单列表、状态更新、发货 |
| 工单管理 | `/admin/tickets` | 复核/精修工单处理 |
| 用户管理 | `/admin/users` | 用户列表、权限管理 |
| 套餐配置 | `/admin/packages` | 基础款/礼盒款价格和物料 |
| 场景配置 | `/admin/scenes` | 场景名称/字段/免费次数 |
| 风格配置 | `/admin/styles` | AI 生成风格管理 |
| 提示词配置 | `/admin/prompts` | AI 生成提示词模板 |
| 模型配置 | `/admin/models` | AI 图像生成模型管理 |
| 支付配置 | `/admin/payment` | 收款码/客服联系方式 |
| 系统配置 | `/admin/config` | 全局参数配置 |

---

## 注意事项

**图片存储**：所有图片必须通过 `manus-upload-file --webdev` 上传到 CDN，不允许在项目目录中存放图片文件，否则会导致部署超时。

**手机端兼容性**：系统使用直接代理模式（而非 307 重定向）提供图片服务，兼容微信内置浏览器等对跨域重定向有限制的环境。

**AI 生成配额**：每个用户在每个场景下享有固定免费生成次数（默认 3 次），可在后台系统配置中调整。超出配额的用户可申请人工复核（免费补发配额）或人工精修（付费）。

**支付模式**：当前采用手动确认收款模式，管理员在后台核实到账后手动确认。如需自动收款，需接入微信/支付宝官方支付 API（需企业资质）。

---

## 许可证

本项目为私有项目，未经授权不得复制、修改或分发。

---

*文档最后更新：2026年5月*