# AI绘本项目

**Repository Path**: cuixc2018/ai-huiben

## Basic Information

- **Project Name**: AI绘本项目
- **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-04-11
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 绘童趣 — AI绘本创作平台

用户上传宝宝照片或输入故事，AI 自动生成图文并茂的专属绘本。包含 Web H5 端和微信小程序端。

---

## 项目结构

```
ai-huiben/
├── api/               # FastAPI 后端
│   ├── app/
│   │   ├── api/v1/    # 路由（auth/books/orders/transform/credits/admin）
│   │   ├── services/  # 业务服务（AI生成/支付/积分/存储/文字叠加/PDF）
│   │   ├── models/    # ORM 模型（User/Book/Order/TransformRecord/FreeToken）
│   │   └── core/      # 配置/安全/依赖注入/日志/事件埋点
│   ├── run.py         # 入口
│   ├── start.sh       # 服务管理脚本
│   ├── deploy.sh      # 环境初始化脚本
│   └── .env.example   # 配置模板
├── web/               # Web H5 前端 (React 19 + Vite 8 + Ant Design 6)
├── miniprogram/       # 微信小程序
└── docs/              # 设计文档 / 规划 / 日志
```

---

## 一、后端部署

### 1. 环境要求

| 依赖 | 版本 |
|------|------|
| Python | 3.10+ |
| PostgreSQL | 14+ |
| Redis | 6+（可选，当前未使用） |

### 2. 配置 .env

```bash
cd api
cp .env.example .env
vim .env
```

**必填项：**

```env
# 数据库
DATABASE_URL=postgresql+asyncpg://aihuiben:你的密码@localhost:5432/aihuiben

# JWT（务必修改为随机字符串）
SECRET_KEY=生成一段随机字符串

# 微信小程序
WECHAT_APPID=wx8e0251403efe0fce
WECHAT_SECRET=你的小程序secret

# AI 服务（至少配置 DeepSeek 和 RunningHub）
DEEPSEEK_API_KEY=sk-xxx
RUNNINGHUB_API_KEY=xxx
DASHSCOPE_API_KEY=sk-xxx

# 七牛云存储
QINIU_ACCESS_KEY=xxx
QINIU_SECRET_KEY=xxx
QINIU_BUCKET=aihuiben
QINIU_DOMAIN=http://你的域名.clouddn.com

# 邮件验证码
SMTP_HOST=smtp.163.com
SMTP_PORT=465
SMTP_USER=你的邮箱@163.com
SMTP_PASSWORD=你的SMTP授权码

# 微信支付（生产环境必填，开发环境自动走 Mock）
WECHAT_MCH_ID=你的商户号
WECHAT_APIV3_KEY=你的APIv3密钥
WECHAT_MCH_CERT_SERIAL_NO=证书序列号
WECHAT_MCH_PRIVATE_KEY=/data/ssl/wxpay/apiclient_key.pem
WECHAT_NOTIFY_URL=https://你的域名/api/orders/callback

# 新用户赠送积分
WELCOME_CREDITS=20
```

> **重要：** `.env.example` 中部分密钥已脱敏，部署时务必替换为真实值。

### 3. 初始化 & 启动

```bash
# 一键初始化：创建虚拟环境 + 安装依赖 + 环境检查
./deploy.sh init

# 启动
./start.sh start

# 查看状态
./start.sh status

# 实时日志
./start.sh logs
```

启动后访问：
- API: `http://localhost:8000`
- Swagger 文档: `http://localhost:8000/docs`
- 健康检查: `http://localhost:8000/health`

### 4. 管理命令

```bash
./start.sh start      # 启动
./start.sh stop       # 停止
./start.sh restart    # 重启
./start.sh status     # 查看状态
./start.sh logs       # 实时查看日志
```

### 5. 日志体系

| 日志文件 | 说明 |
|---------|------|
| `docs/log/api-{date}.log` | 全局应用日志 |
| `logs/app-{date}.log` | 应用结构化日志 (JSON) |
| `logs/payment-{date}.log` | 支付日志 (JSON) |
| `logs/credits-{date}.log` | 积分日志 (JSON) |
| `logs/events-{date}.log` | 行为事件埋点 (JSON) |

**5 个核心事件埋点：** `user.registered` / `book.created` / `book.story_generated` / `book.image_generated` / `user.recharged`。从这些事件可推导创作完成率、充值转化率、分享获客占比。

### 6. 数据库初始化

首次启动时 `init_db()` 会自动建表。如果已有旧数据库，新增的 `users` 字段（`invite_code`/`invited_by`/`last_active_at`）和 `free_tokens` 表也会自动生成。

---

## 二、Web H5 前端部署

### 环境要求

- Node.js 18+

### 开发模式

```bash
cd web
npm install
npm run dev
```

访问 `http://localhost:5173`，Vite 已配置代理将 `/api` 转发到 `localhost:8000`。

### 生产构建

```bash
npm run build
# 产物在 dist/
```

### Nginx 配置

```nginx
server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate     /etc/ssl/certs/your-domain.pem;
    ssl_certificate_key /etc/ssl/private/your-domain.key;

    root /opt/ai-huiben/web/dist;
    index index.html;

    # SPA fallback
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 反向代理（注意超时设长，AI 生图可能耗时）
    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}
```

---

## 三、微信小程序部署

### 开发调试

1. 下载[微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)
2. 导入项目，目录选择 `ai-huiben/miniprogram/`
3. AppID 填写 `wx8e0251403efe0fce`（或你的 AppID）
4. 本地设置 → 勾选「不校验合法域名」
5. 修改 `miniprogram/app.js` 中的 `baseUrl`：
   ```js
   baseUrl: 'https://你的域名/api'
   ```

### 发布上线

1. 确认 `app.js` 中 `baseUrl` 为线上地址
2. 开发者工具点击「上传」
3. 登录 [微信公众平台](https://mp.weixin.qq.com/) → 版本管理 → 提交审核
4. 审核通过后发布

### 线上必配

- **服务器域名白名单：** 在公众平台 → 开发管理 → 开发设置 中配置 `request合法域名`、`uploadFile合法域名`、`downloadFile合法域名`
- **订阅消息模板：** 在公众平台 → 订阅消息 中申请模板，填入 `miniprogram/pages/preview/preview.js` 的 `tmplIds` 数组

---

## 四、运营看板

部署后访问 `/admin/dashboard`（需登录），可查看：

| 指标 | 计算方式 |
|------|---------|
| 注册用户 | `users` 表 within range |
| 创作完成率 | 有生成图片的绘本数 / 创建的绘本数 |
| 充值转化率 | 付费用户数 / 注册用户数 |
| 分享获客占比 | 被邀请注册的用户数 / 注册用户数 |
| 增长漏斗 | 注册 → 创作 → 故事 → 图片 → 充值 |
| 套餐收入排行 | 各套餐的订单数和收入 |

支持按今日/7日/30日/全部切换时间范围。

---

## 五、增长系统

### 分享裂变

```
用户 A 分享绘本 → 好友 B 通过邀请链接打开 → B 注册
  → A 获得 5 积分（invite_reward）
  → B 获得 10 积分（invite_bonus）
```

分享链接自动携带邀请码，注册时后端记录 `invited_by` 关系并发放双方奖励。小程序端 `app.js` 在 `onShow` 中提取链接中的 `invite_code`。

### 新人首本免费券

新用户注册时自动发放"首本绘本免费券"（3天有效）。创作第一本绘本时，故事生成和画面生成均不消耗积分——用户可完整体验一次创作流程。

### 订阅消息

绘本预览页加载完成后引导用户订阅（模板 ID 需在微信公众平台配置）。后端 `SubscribeMessageService` 可下发消息到指定用户。

---

## 六、积分体系

| 操作 | 消耗 | 备注 |
|------|------|------|
| 生成故事 | 5 积分 | 有免费券时跳过 |
| 生成单页画面 | 2 积分/页 | 有免费券时跳过 |
| 照片转绘 | 3 积分 | |
| 重新生成单页 | 2 积分 | |
| 文字叠加 | 免费 | |
| 下载 PDF | 免费 | |
| 图片分析 | 免费 | |
| 智能分页 | 免费 | |

- 新用户注册赠送 20 积分 + 首本免费券
- 所有积分操作为预扣模式，失败自动退款
- 积分套餐：6 元起，共 4 档

---

## 七、AI 服务

| 服务 | API | 模型 | 用途 |
|------|-----|------|------|
| DeepSeek | `https://api.deepseek.com` | `deepseek-chat` | 故事生成、智能分页、文案精简 |
| RunningHub | `https://www.runninghub.cn` | 自定义图片生成 | 文生图、图生图 |
| DashScope | `https://dashscope.aliyuncs.com` | `qwen-vl-plus` | 图片场景分析、角色外貌提取 |
| 智谱 AI | `https://open.bigmodel.cn` | `glm-4` | 备用（当前未启用） |

---

## 八、支付系统

| 场景 | 支付方式 | 说明 |
|------|---------|------|
| 小程序 | JSAPI (`wx.requestPayment`) | 生产环境 |
| 公众号 H5 | JSAPI (`WeixinJSBridge`) | 生产环境 |
| 浏览器 H5 | MWEB（跳转微信） | 生产环境 |
| 开发测试 | Mock | 自动启用，弹窗模拟 |

开发环境下 `MockPaymentService` 自动启用，无需配置微信商户信息即可跑通充值流程。

---

## 九、技术栈

| 模块 | 技术 |
|------|------|
| 后端框架 | FastAPI + Uvicorn |
| ORM | SQLAlchemy 2.0 async |
| 数据库 | PostgreSQL（生产）/ SQLite（开发） |
| 认证 | JWT + 微信 OAuth |
| H5 前端 | React 19 + TypeScript + Vite 8 + Ant Design 6 |
| 设计体系 | Material Design 3 (Material You)，主色 `#6750A4` |
| 小程序 | 原生 WXML/WXSS/JS |
| 存储 | 七牛云 |
| 支付 | 微信支付 API v3 |

---

## 十、设计文档

完整的产品分析和运营方案见：

- [项目诊断与迭代路线图](docs/superpowers/specs/2026-05-21-project-review-and-roadmap.md)
- [商业化运营方案](docs/superpowers/specs/2026-05-21-growth-and-monetization-plan.md)