Skip to content

README_EN.md

Latest commit

 

History

History
678 lines (528 loc) · 20.9 KB

README_EN.md

File metadata and controls

678 lines (528 loc) · 20.9 KB
Raw

Xiaoyaopeipei

AI Conversational PC Buying Assistant - Helps you take orders 24/7

License: MIT Python Vue FastAPI

English | 简体中文

Xiaoyaopeipei Poster

Introduction

Xiaoyaopeipei

Xiaoyaopeipei is an AI conversational PC buying assistant that provides an intelligent SaaS platform for PC shop owners to collect customer requirements and recommend configuration services. It collects customer needs through AI conversations and intelligently recommends suitable PC configuration solutions.

Core Features:

  • 🤖 AI Smart Chat - Natural language interaction with automatic customer intent recognition
  • 🎯 Precise Configuration Recommendations - Automatically matches the best PC configurations based on needs
  • 📊 Customer Lead Management - Automatically collects customer contact information, never missing a potential customer
  • 📈 Data Statistics & Analysis - Real-time view of marketing data and conversion effects to optimize business decisions
  • 🚀 Quick Deployment - Frontend-backend separation architecture, easy to deploy and scale
  • 💻 Dual Platform Support - B-end merchant backend + C-end customer chat interface
  • 📱 Responsive Design - Supports both desktop and mobile access

About the Author

dtsola

dtsola — IT Architect | One-Person Company Practitioner

🌐 Personal Website  |  📺 Bilibili  |  💬 WeChat: dtsola (Tech Discussion | Business Collaboration)

WeChat QR        Developer Group        User Group

WeChat Contact          Developer Group          User Group

Feature Preview

C-End - Smart Chat, Get Recommendations

Chat Home - Natural Language Interaction

Chat Home
  • 🎯 Natural language chat, express needs easily
  • 🤖 AI automatically recognizes user intent
  • ⚡ Real-time response, smooth interaction
  • 💬 Supports multi-turn conversations to refine needs

Configuration Recommendation - Intelligent Matching

Recommendations
  • 🎲 Intelligently matches best configuration
  • 💰 Transparent pricing at a glance
  • 📋 Clear configuration details
  • 🏷️ Supports multiple configuration types
Compare Plans
  • ⚖️ Compare multiple plans, choose with confidence
  • 📊 Visual display of configuration differences
  • 💡 Cost-performance analysis for better decisions

Lead Submission - Leave Contact Info

Contact Info
  • 📱 One-click contact submission
  • 🔔 Quick merchant follow-up
  • 🛒 Facilitate transaction conversion
  • 🔐 Privacy security protection
Success
  • ✅ Submission confirmation
  • ⏰ Merchant response time estimate
  • 🎯 Next step guidance

B-End - Merchant Backend, Efficient Management

Login/Register - Quick Onboarding

Login
  • 🔐 Simple and secure login/registration
  • ✉️ Email verification for account security
  • ⚡ Quick start, no training needed

Data Dashboard - Business Overview

Dashboard
  • 📊 Core metrics at a glance
  • 📈 Trend analysis for business insights
  • 🎯 Real-time key metrics tracking
  • 📉 Conversion funnel visualization

Configuration Management - SKU Lifecycle Management

SKU List
  • 💼 Unified configuration SKU management
  • 🔍 Quick search and filtering
  • 🏷️ Custom category tags
  • 📊 Real-time inventory status
SKU Edit
  • ✏️ Flexible SKU editing
  • 📷 Image support for better visualization
  • 📝 Detailed parameter configuration
  • 💰 Price setting and adjustment

Lead Management - Centralized Customer Leads

Lead List
  • 👥 Centralized customer lead management
  • 🔍 Multi-dimensional filtering
  • 📅 Timeline view
  • 🏷️ Status tag tracking
Lead Details
  • 📋 Complete lead details
  • 💬 Conversation history
  • 🎯 Recommendation records
  • 📝 Follow-up notes

Share Management - Exclusive Promotion QR Code

Share
  • 🎟️ Exclusive promotion QR code
  • 📤 One-click share to WeChat/Moments
  • 🔗 Permanent link, acquire customers anytime
  • 📊 Share data statistics

Profile - Membership & Recharge

Profile
  • 💳 Contact platform for recharge
  • ⏰ Package renewal management
  • 🔔 System reminder before expiration
  • ⚙️ Account settings center
Expired
  • 🔒 Auto-check membership status on login
  • ⚠️ Clear expired status display
  • 📧 Obvious contact renewal entry
  • 🛡️ Permission control for service security

Quick Start

Requirements

  • Node.js: >= 18.0.0
  • Python: 3.10
  • MySQL: 8.0
  • Git: Latest version

Method 1: Docker Deployment (Recommended)

For detailed deployment guide, see: Docker Deployment Documentation

Environment Variables Configuration:

Edit the docker/.env file and fill in the required configurations:

Parameter How to Get Description
MYSQL_ROOT_PASSWORD Custom
Generate: openssl rand -base64 16		 MySQL root password, use strong password
MYSQL_PASSWORD Custom
Generate: openssl rand -base64 16		 Database user password, use strong password
JWT_SECRET Custom
Generate: openssl rand -base64 32		 JWT secret key, must be random string (32+ chars)
QWEN_API_KEY Alibaba Cloud Bailian Platform
Create API-KEY after enabling service		 Qwen API key
OSS_ACCESS_KEY_ID Alibaba Cloud OSS Console
Get after creating AccessKey		 OSS access key ID
OSS_ACCESS_KEY_SECRET Alibaba Cloud OSS Console
Get after creating AccessKey		 OSS access key secret
OSS_BUCKET Alibaba Cloud OSS Console
Copy bucket name after creation		 OSS bucket name
OSS_ENDPOINT Select by region
• Shanghai: oss-cn-shanghai.aliyuncs.com
• Hangzhou: oss-cn-hangzhou.aliyuncs.com
• Beijing: oss-cn-beijing.aliyuncs.com		 OSS endpoint
OSS_HOST No custom domain: https://{bucket}.{endpoint}
Has custom domain: Fill in bound domain		 OSS file access URL
AES_KEY Custom
Generate: openssl rand -base64 24 | head -c 32		 AES encryption key, must be 32 characters
MEMBERSHIP_DEFAULT_DAYS Custom, default 7 Default membership days (granted on registration)
MEMBERSHIP_RENEWAL_THRESHOLD Custom, default 3 Membership renewal reminder threshold (days)

Quick Generate Random Keys:

# Generate JWT_SECRET (example)
openssl rand -base64 32

# Generate AES_KEY (must be 32 characters)
openssl rand -base64 24 | head -c 32

One-Command Start All Services:

# 1. Configure environment variables
cd docker
# Edit .env file, fill in real configurations

# 2. Start all services (database migration runs automatically)
docker-compose up -d

# 3. Check service status
docker-compose ps

Local Access URLs:

Advantages:

  • 🚀 One-command start, no manual configuration needed
  • 📦 Environment isolation, doesn't affect local system
  • 🔄 Auto-run database migrations
  • 🛠️ Consistent dev, test, and production environments

Method 2: Local Development

Backend Start

# 1. Enter backend directory
cd xiaoyaopeipei-user-merchant-backend

# 2. Create virtual environment (Windows)
py -3.10 -m venv venv
venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment variables
cp .env.example .env
# Edit .env file, fill in real configurations

# 5. Database migration
alembic upgrade head

# 6. Start service
uvicorn app.main:app --reload --port 8001

Backend runs at: http://localhost:8001 API Docs: http://localhost:8001/docs

C-End Frontend Start

# 1. Enter C-End frontend directory
cd xiaoyaopeipei-user-frontend

# 2. Install dependencies
pnpm install

# 3. Start dev server
pnpm dev

C-End runs at: http://localhost:3000

B-End Frontend Start

# 1. Enter B-End frontend directory
cd xiaoyaopeipei-mer-frontend

# 2. Install dependencies
pnpm install

# 3. Start dev server
pnpm dev

B-End runs at: http://localhost:3001

Method 3: Production Deployment

For detailed deployment guide, see: Deployment Documentation

Deployment Architecture:

  • Cloud Server: Alibaba Cloud ECS 2-core 4GB
  • Web Server: Nginx (reverse proxy + static file serving)
  • Process Manager: Supervisor

Domain Planning:

Project Domain
C-End user.example.com
B-End mer.example.com
API api.example.com

Usage Guide

Merchant Workflow (B-End)

  1. Register Account: Visit B-End, complete email registration
  2. Configuration Management: Add PC configuration SKUs, set prices and categories
  3. Generate QR Code: Get exclusive promotion QR code
  4. Share & Promote: Share QR code with potential customers
  5. View Leads: Receive customer leads in real-time, follow up quickly
  6. Data Statistics: View business data, optimize marketing strategies

Customer Workflow (C-End)

  1. Scan to Access: Scan merchant's exclusive QR code to enter chat page
  2. AI Chat: Express PC needs in natural language
  3. Get Recommendations: AI intelligently matches best configurations
  4. Compare & Select: View multiple recommended plans, compare and choose
  5. Submit Lead: Leave contact information, wait for merchant contact

Tech Stack

Backend

Technology Version Description
Python 3.10+ Backend development language
FastAPI 0.109+ High-performance web framework
SQLAlchemy 2.0+ ORM framework
Alembic Latest Database migration tool
Pydantic 2.x Data validation
Loguru 0.7+ Log management
LangChain 0.1+ AI agent framework
Qwen qwen-plus Large language model
MySQL 8.0+ Relational database
Alibaba Cloud OSS - File storage
JWT - User authentication

Frontend (C-End + B-End)

Technology Version Description
Vue 3.4+ Progressive frontend framework
Vite 5.0+ Next-generation build tool
TypeScript 5.0+ Type-safe JavaScript
Ant Design Vue 4.x Enterprise UI component library
Vue Router 4.2+ Official routing
Pinia 2.1+ New generation state management
Axios Latest HTTP client
ECharts 5.4+ Data visualization (B-End)

Deployment

Technology Description
Nginx Web server / Reverse proxy
Supervisor Process management
Docker Container deployment (optional)

Project Structure

xiaoyaopeipei/
├── xiaoyaopeipei-user-frontend/         # C-End frontend (Vue 3)
│   ├── src/
│   │   ├── api/                         # API client
│   │   ├── views/                       # Page components
│   │   ├── components/                  # Common components
│   │   ├── stores/                      # State management (Pinia)
│   │   └── utils/                       # Utility functions
│   ├── package.json
│   └── vite.config.ts
│
├── xiaoyaopeipei-mer-frontend/          # B-End frontend (Vue 3)
│   ├── src/
│   │   ├── api/
│   │   ├── views/
│   │   ├── components/
│   │   ├── stores/
│   │   └── utils/
│   ├── package.json
│   └── vite.config.ts
│
├── xiaoyaopeipei-user-merchant-backend/ # Backend (FastAPI)
│   ├── app/
│   │   ├── api/                         # API routes
│   │   │   ├── user/                    # C-End endpoints
│   │   │   └── mer/                     # B-End endpoints
│   │   ├── core/                        # Core configuration
│   │   ├── models/                      # SQLAlchemy ORM models
│   │   ├── schemas/                     # Pydantic validation
│   │   ├── services/                    # Business logic
│   │   ├── utils/                       # Utility functions
│   │   └── middleware/                  # Middleware
│   ├── alembic/                         # Database migrations
│   ├── requirements.txt
│   └── .env.example
│
├── docs/                                # Documentation
│   ├── 00-mrd.md                        # Market requirements
│   ├── 01-prd.md                        # Product requirements
│   ├── 03-技术方案.md                    # Technical solution
│   ├── 代码架构.md                       # Code architecture
│   ├── 数据库文档.md                     # Database design
│   ├── 接口文档.md                       # API documentation
│   ├── 部署文档.md                       # Deployment guide
│   └── 产品文档/
│       ├── logos/                       # Brand assets
│       └── 产品截图/                    # Feature screenshots
│
└── README.md                            # This document

Documentation Index

Document Path Description
MRD docs/00-mrd.md Market requirements document
PRD docs/01-prd.md Product requirements document
Technical Solution docs/03-技术方案.md Technical architecture design
Code Architecture docs/代码架构.md Complete code structure
API Documentation docs/接口文档.md RESTful API design
Database Documentation docs/数据库文档.md Database design
Deployment Documentation docs/部署文档.md Production deployment guide

Core Features

C-End (Customer)

  • AI Smart Chat: Natural language interaction based on LangChain + Qwen
  • Intent Recognition: Automatically identifies customer needs (office, gaming, design, etc.)
  • Configuration Recommendation: Intelligently matches best configurations based on needs
  • Plan Comparison: Multi-plan comparison display for customer decisions
  • Lead Submission: One-click contact submission for transactions

B-End (Merchant)

  • Merchant Authentication: Email registration/login, JWT Token authentication
  • Configuration Management: CRUD operations for PC configuration SKUs
  • Lead Management: View customer lead list and details
  • Data Statistics: Dashboard for visits, leads, conversion rate, etc.
  • Share Management: Generate exclusive promotion QR codes, track sources
  • Profile: Account management, contact platform for recharge, package renewal

Development Standards

Code Standards

  • Python: Follow PEP 8, use black + isort for formatting
  • TypeScript: Follow ESLint + Prettier standards
  • Naming Conventions:
    • Python: snake_case (functions/variables), PascalCase (classes)
    • TypeScript: camelCase (variables/functions), PascalCase (classes/components)

Git Commit Standards

<type>(<scope>): <subject>

# Type Types
feat: New feature
fix: Bug fix
docs: Documentation update
style: Code formatting
refactor: Refactoring
test: Testing related
chore: Build/tools changes

For detailed standards, see CLAUDE.md

Contributing

Contributions, issues, and feature requests are welcome!

Development Process

  1. Fork this repository
  2. Create a feature branch (git checkout -b feature/AmazingFeature)
  3. Commit changes (git commit -m 'feat: Add some feature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Create a Pull Request

FAQ

Q: Which large models are supported?

A: Currently uses Alibaba Cloud Qwen (qwen-plus), with plans to expand to other models.

Q: How is data stored?

A: Uses MySQL 8.0 for structured data, Alibaba Cloud OSS for file storage.

Q: How to customize AI chat prompts?

A: Modify LangChain prompt templates in app/services/ai_service.py.

Q: Is mobile supported?

A: Yes. The frontend uses responsive design and works on mobile browsers.

Q: How to recharge and renew?

A: Contact the platform for recharge. Login to B-End profile to view membership expiration and renew. The system sends reminder notifications before expiration.

Q: What if membership expires?

A: Login automatically checks membership status. If expired, prompts to contact for renewal. All features restore after renewal.

License

This project is licensed under the MIT License

Contact

Xiaoyaopeipei: AI Conversational PC Buying Assistant - Helps You Take Orders 24/7

Made with ❤️ by Xiaoyao Team