diff --git a/11. Non-Functional Requirements .txt b/11. Non-Functional Requirements .txt deleted file mode 100644 index 6d9b1d1..0000000 --- a/11. Non-Functional Requirements .txt +++ /dev/null @@ -1,227 +0,0 @@ -# Non-Functional Requirements -> **Document Version:** 1.0 -> -> **Product:** VeriCart AI -> -> **Section:** Non-Functional Requirements (NFR) -> -> **Standard:** ISO/IEC 25010 Software Quality Model ---- -# 12. Non-Functional Requirements -## 12.1 Introduction -Non-functional requirements define the quality attributes and operational characteristics of VeriCart AI. Unlike functional requirements, which describe **what** the system does, non-functional requirements describe **how well** the system performs. -These requirements ensure that VeriCart AI is secure, reliable, scalable, maintainable, and capable of supporting real-world usage while delivering an excellent user experience. ---- -# 12.2 Quality Attribute Overview -The system shall satisfy the following quality attributes: -| Quality Attribute | Description | -|-------------------|-------------| -| Performance | Fast response times and efficient processing | -| Reliability | Stable operation with minimal failures | -| Availability | Continuous system accessibility | -| Scalability | Ability to support increasing users and products | -| Security | Protection of user data and APIs | -| Maintainability | Easy modification and extension | -| Usability | Intuitive and responsive interface | -| Compatibility | Cross-browser and cross-device support | -| Portability | Docker-based deployment | -| AI Reliability | Consistent AI-generated outputs | ---- -# 12.3 Performance Requirements -### NFR-001 Response Time -Priority: **Must** -The system shall return standard REST API responses within **500 milliseconds** under normal operating conditions. ---- -### NFR-002 Product Search -Search results should appear within **2 seconds**. ---- -### NFR-003 Page Loading -The homepage shall load within **2 seconds** on a broadband connection. ---- -### NFR-004 Database Query Performance -Database queries should be optimized using indexes and complete within acceptable execution times. ---- -### NFR-005 AI Processing -AI-generated review summaries should normally be returned within **5–10 seconds**, depending on model response time. ---- -# 12.4 Scalability Requirements -### NFR-006 Horizontal Scalability -The backend architecture shall support horizontal scaling using Docker containers. ---- -### NFR-007 Modular Architecture -Each software module shall be independently maintainable and extensible. ---- -### NFR-008 AI Model Expansion -The architecture shall allow additional LLM providers to be integrated without major system redesign. ---- -### NFR-009 Product Growth -The database shall support future expansion to millions of product records. ---- -# 12.5 Reliability Requirements -### NFR-010 System Stability -The application shall recover gracefully from recoverable runtime errors. ---- -### NFR-011 AI Failure Handling -If an AI provider is unavailable, the system shall: -- Log the failure -- Return a user-friendly message -- Continue operating without affecting other modules ---- -### NFR-012 Database Recovery -Database backups shall be supported to prevent data loss. ---- -### NFR-013 Logging -Application errors shall be recorded for troubleshooting. ---- -# 12.6 Availability Requirements -### NFR-014 Service Availability -The application should maintain **99% availability** during normal operation. ---- -### NFR-015 API Availability -REST APIs shall remain accessible unless maintenance is in progress. ---- -### NFR-016 Graceful Degradation -If AI services become unavailable, standard shopping functionality shall remain operational. ---- -# 12.7 Security Requirements -### NFR-017 Authentication -JWT shall protect all authenticated APIs. ---- -### NFR-018 Authorization -Role-Based Access Control (RBAC) shall restrict access to protected resources. ---- -### NFR-019 Password Security -Passwords shall be encrypted using BCrypt before storage. ---- -### NFR-020 SQL Injection Prevention -Prepared statements and MyBatis parameter binding shall prevent SQL injection. ---- -### NFR-021 Cross-Site Scripting (XSS) -User-generated content shall be sanitized before display. ---- -### NFR-022 Cross-Origin Resource Sharing (CORS) -Only trusted frontend origins shall be permitted. ---- -### NFR-023 HTTPS -Production deployment shall use HTTPS for all client-server communication. ---- -### NFR-024 Sensitive Data Protection -API keys, JWT secrets, and database credentials shall never be exposed to the frontend. ---- -# 12.8 Maintainability Requirements -### NFR-025 Layered Architecture -The backend shall follow a layered architecture: -- Controller -- Service -- Mapper -- Database ---- -### NFR-026 Code Reusability -Reusable services and utility components should be created whenever practical. ---- -### NFR-027 Documentation -All public APIs shall be documented using OpenAPI/Swagger. ---- -### NFR-028 Version Control -Source code shall be managed using Git. ---- -# 12.9 Usability Requirements -### NFR-029 Responsive Design -The frontend shall support desktop, tablet, and mobile devices. ---- -### NFR-030 User-Friendly Navigation -Users should be able to reach any major feature within three navigation steps. ---- -### NFR-031 Accessibility -The interface should follow basic accessibility practices including readable typography, sufficient contrast, and keyboard navigation where applicable. ---- -### NFR-032 Error Messages -Validation and system errors shall be presented using clear, user-friendly language. ---- -# 12.10 Compatibility Requirements -### NFR-033 Browser Compatibility -The application shall support: -- Google Chrome -- Microsoft Edge -- Mozilla Firefox -- Safari (latest versions) ---- -### NFR-034 Operating Systems -The system shall function on: -- Windows -- Linux -- macOS ---- -# 12.11 AI Quality Requirements -### NFR-035 Explainability -Every AI recommendation shall include a concise explanation. ---- -### NFR-036 Transparency -The platform shall clearly indicate when content is AI-generated. ---- -### NFR-037 Confidence Score -Where practical, AI outputs should include a confidence level or supporting rationale. ---- -### NFR-038 Multi-LLM Routing -The AI gateway shall route requests to the appropriate model based on the requested capability. ---- -### NFR-039 Prompt Logging -System prompts and responses should be logged securely for debugging while protecting user privacy. ---- -### NFR-040 AI Extensibility -The AI integration layer shall support adding new providers (e.g., future open-source or commercial LLMs) with minimal code changes. ---- -# 12.12 Deployment Requirements -### NFR-041 Containerization -All services shall be deployable using Docker. ---- -### NFR-042 Environment Configuration -Application configuration shall be managed through environment variables. ---- -### NFR-043 Reverse Proxy -Nginx may be used as a reverse proxy in production deployments. ---- -# 12.13 Monitoring Requirements -### NFR-044 Application Logs -All critical operations shall be logged. ---- -### NFR-045 API Monitoring -REST API request and error statistics should be monitored. ---- -### NFR-046 AI Monitoring -AI request counts, response times, and failure rates should be tracked. ---- -# 12.14 Backup & Recovery Requirements -### NFR-047 Database Backup -Regular database backups shall be supported. ---- -### NFR-048 Restore Capability -The system shall support restoration from backups. ---- -# 12.15 Internationalization Requirements -### NFR-049 Multi-language Support -The platform architecture shall support multiple interface languages. ---- -### NFR-050 Unicode Support -The database and frontend shall fully support Unicode characters. ---- -# 12.16 Requirement Traceability -| Category | Requirement IDs | -|----------|-----------------| -| Performance | NFR-001–005 | -| Scalability | NFR-006–009 | -| Reliability | NFR-010–013 | -| Availability | NFR-014–016 | -| Security | NFR-017–024 | -| Maintainability | NFR-025–028 | -| Usability | NFR-029–032 | -| Compatibility | NFR-033–034 | -| AI Quality | NFR-035–040 | -| Deployment | NFR-041–043 | -| Monitoring | NFR-044–046 | -| Backup & Recovery | NFR-047–048 | -| Internationalization | NFR-049–050 | ---- -# 12.17 Chapter Summary -These non-functional requirements establish the quality standards that VeriCart AI must satisfy throughout its lifecycle. -By emphasizing performance, security, scalability, maintainability, and AI transparency, the project aims to deliver not only a functional e-commerce platform but also a reliable and extensible software system capable of supporting future enhancements and real-world deployment. \ No newline at end of file diff --git a/13. Database Design.txt b/13. Database Design.txt deleted file mode 100644 index af93496..0000000 --- a/13. Database Design.txt +++ /dev/null @@ -1,337 +0,0 @@ -# Database Design -> **Document Version:** 1.0 -> -> **Product:** VeriCart AI -> -> **Section:** Database Design -> -> **Database:** MySQL 8.0 -> -> **ORM Framework:** MyBatis ---- -# 14. Database Design ---- -# 14.1 Introduction -The VeriCart AI platform relies on a relational database management system (RDBMS) to store business data securely and efficiently. -The database is designed following Third Normal Form (3NF) to minimize redundancy while maintaining high query performance. -Primary objectives include: -- Data integrity -- High performance -- Scalability -- Maintainability -- Secure storage -- AI data support -The database supports both traditional e-commerce operations and AI-generated analytics. ---- -# 14.2 Database Technology -| Component | Technology | -|------------|------------| -| Database | MySQL 8.0 | -| ORM | MyBatis | -| Character Set | utf8mb4 | -| Engine | InnoDB | -| Primary Key | BIGINT AUTO_INCREMENT | -| Foreign Key | Supported | -| Transactions | ACID | ---- -# 14.3 Database Architecture -```mermaid -flowchart LR -Vue -↓ -SpringBoot -↓ -Service -↓ -MyBatis -↓ -MySQL -``` ---- -# 14.4 Database Modules -The database consists of five major domains. -```text -Authentication -↓ -Product -↓ -Order -↓ -Review -↓ -Artificial Intelligence -``` ---- -# 14.5 Entity Relationship Overview -```mermaid -erDiagram -USERS ||--o{ ORDERS : places -USERS ||--o{ REVIEWS : writes -PRODUCTS ||--o{ REVIEWS : receives -PRODUCTS ||--o{ ORDER_ITEMS : contains -ORDERS ||--o{ ORDER_ITEMS : includes -PRODUCTS ||--o{ AI_ANALYSIS : analyzed_by -PRODUCTS ||--|| TRUST_SCORE : owns -USERS ||--o{ CART : owns -CART ||--o{ CART_ITEMS : contains -PRODUCTS ||--o{ CART_ITEMS : added -``` ---- -# 14.6 Database Tables -The MVP contains the following tables. -| Table | Purpose | -|---------|---------| -| users | Customer information | -| roles | User roles | -| user_roles | User-role mapping | -| categories | Product categories | -| products | Product information | -| product_images | Product images | -| cart | Shopping cart | -| cart_items | Cart details | -| orders | Orders | -| order_items | Order details | -| reviews | Customer reviews | -| ai_analysis | AI analysis results | -| trust_scores | AI Trust Scores | -| recommendations | AI recommendations | -| ai_logs | AI request logs | -| notifications | User notifications | -Total Tables -16 ---- -# 14.7 Users Table -Table Name -users -Description -Stores customer accounts. -| Field | Type | Description | -|---------|------|-------------| -| id | BIGINT | Primary Key | -| username | VARCHAR(50) | Username | -| email | VARCHAR(100) | Email | -| password | VARCHAR(255) | BCrypt Password | -| phone | VARCHAR(20) | Phone | -| avatar | VARCHAR(255) | Image | -| created_at | DATETIME | Created Time | -| updated_at | DATETIME | Updated Time | ---- -# 14.8 Roles Table -Stores user roles. -Fields -- id -- role_name -- description -Examples -CUSTOMER -SELLER -ADMIN ---- -# 14.9 Products Table -Stores products. -| Field | Type | -|---------|------| -| id | BIGINT | -| category_id | BIGINT | -| name | VARCHAR(200) | -| description | TEXT | -| price | DECIMAL | -| stock | INT | -| image | VARCHAR | -| status | VARCHAR | -| created_at | DATETIME | ---- -# 14.10 Categories Table -Stores product categories. -Examples -Electronics -Fashion -Books -Home -Sports -Beauty ---- -# 14.11 Shopping Cart -Cart -↓ -Cart Items -Each customer owns one shopping cart. ---- -# 14.12 Orders -Stores -Order Number -Customer -Total Price -Status -Shipping Address -Order Time ---- -Statuses -Pending -Paid -Processing -Shipped -Delivered -Cancelled ---- -# 14.13 Reviews -Stores -Customer Reviews -Rating -Review Text -Review Time -Product -User ---- -# 14.14 AI Analysis Table -Stores AI-generated information. -Fields -- id -- review_id -- sentiment -- fake_probability -- confidence -- summary -- analyzed_at ---- -# 14.15 Trust Score Table -Stores AI Trust Scores. -Fields -- product_id -- score -- level -- updated_at -Example -Product -Laptop -Trust Score -96 -Level -Excellent ---- -# 14.16 Recommendation Table -Stores -Recommended Products -Recommendation Score -Recommendation Reason ---- -# 14.17 AI Log Table -Stores -Prompt -Model -Response Time -Status -Error -Purpose -AI Monitoring ---- -# 14.18 Notification Table -Stores -Messages -User -Status -Created Time ---- -# 14.19 Relationships -Users -↓ -Orders -1:N ---- -Users -↓ -Reviews -1:N ---- -Products -↓ -Reviews -1:N ---- -Products -↓ -Trust Score -1:1 ---- -Orders -↓ -Order Items -1:N ---- -Products -↓ -Order Items -1:N ---- -Cart -↓ -Cart Items -1:N ---- -# 14.20 Database Index Strategy -Indexes -PRIMARY KEY -FOREIGN KEY -UNIQUE -INDEX -Examples -email -username -product_name -category_id -order_no -review_date -trust_score ---- -# 14.21 Transactions -Transactions are required for -Checkout -↓ -Order Creation -↓ -Inventory Update -↓ -Payment Simulation -↓ -Commit -If failure -↓ -Rollback ---- -# 14.22 Data Integrity Rules -Email -Unique ---- -Username -Unique ---- -Rating -1~5 ---- -Trust Score -0~100 ---- -Price -Positive ---- -Stock -≥0 ---- -# 14.23 Future Database Expansion -Future tables -wishlist -seller -warehouse -coupon -payment -shipment -chat_history -product_embedding -vector_store -conversation_history -analytics ---- -# 14.24 Chapter Summary -The VeriCart AI database is designed to support both conventional e-commerce operations and AI-powered intelligence. -The schema follows normalization principles, supports transactional consistency, and separates AI-generated insights from operational business data. -By maintaining a modular relational structure, the database remains scalable, secure, and extensible for future features such as vector search, multilingual AI, and advanced analytics. \ No newline at end of file diff --git a/14. API Specification.txt b/14. API Specification.txt deleted file mode 100644 index ba61aad..0000000 --- a/14. API Specification.txt +++ /dev/null @@ -1,369 +0,0 @@ -# UI/UX Specification -> **Document Version:** 1.0 -> -> **Product:** VeriCart AI -> -> **Section:** UI/UX Specification -> -> **Design Framework:** Vue.js 3 + Element Plus -> -> **Design Principles:** Material Design + Human-Centered Design + AI-First Experience ---- -# 16. UI/UX Specification ---- -# 16.1 Introduction -The User Interface (UI) and User Experience (UX) of VeriCart AI are designed to provide a modern, responsive, intuitive, and trustworthy shopping experience. -Unlike traditional e-commerce platforms, VeriCart AI integrates Artificial Intelligence directly into the shopping workflow. Rather than hiding AI features behind separate pages, AI becomes a natural part of product discovery, evaluation, and purchasing. -The UI prioritizes: -- Simplicity -- Transparency -- Speed -- Explainability -- Accessibility -- Consistency ---- -# 16.2 Design Goals -The UI should enable users to: -- Find products quickly. -- Understand AI-generated insights. -- Compare products easily. -- Complete purchases efficiently. -- Trust AI recommendations. -- Navigate intuitively. ---- -# 16.3 Design Principles -## Principle 1 — Simplicity -Interfaces should avoid unnecessary complexity. -Users should never feel overwhelmed. ---- -## Principle 2 — Consistency -Every page should follow the same: -- Typography -- Colors -- Buttons -- Icons -- Cards -- Navigation ---- -## Principle 3 — Explainable AI -AI-generated content should always indicate: -- AI Summary -- AI Trust Score -- AI Recommendation -- AI Confidence -Users should always know when information is generated by AI. ---- -## Principle 4 — Mobile First -Every page should work on: -- Desktop -- Tablet -- Mobile ---- -## Principle 5 — Accessibility -Support: -- Keyboard navigation -- High contrast -- Readable fonts -- Clear labels -- Color accessibility ---- -# 16.4 Visual Identity -## Brand Name -VeriCart AI ---- -## Brand Personality -- Intelligent -- Modern -- Professional -- Transparent -- Trustworthy ---- -## Primary Colors -| Purpose | Color | -|----------|--------| -| Primary | #2563EB | -| Success | #10B981 | -| Warning | #F59E0B | -| Danger | #EF4444 | -| Background | #F8FAFC | -| Text | #1F2937 | ---- -## Typography -Primary Font -``` -Inter -``` -Fallback -``` -Roboto -Arial -sans-serif -``` ---- -# 16.5 Navigation Structure -```text -Home -├── Categories -├── Products -│ ├── Details -│ ├── Reviews -│ ├── Trust Score -│ └── AI Summary -├── Cart -├── Wishlist -├── Orders -├── AI Assistant -├── Profile -└── Admin -``` ---- -# 16.6 Page Architecture -The platform consists of the following primary pages. -| Page | Purpose | -|-------|----------| -| Home | Landing page | -| Login | Authentication | -| Register | Account creation | -| Product List | Browse products | -| Product Detail | Product information | -| AI Analysis | Trust insights | -| Cart | Shopping cart | -| Checkout | Order confirmation | -| Orders | Purchase history | -| Profile | User account | -| AI Chat | Shopping assistant | -| Admin Dashboard | Platform management | ---- -# 16.7 Homepage -Sections -``` -Navigation Bar -↓ -Hero Banner -↓ -Categories -↓ -Featured Products -↓ -Recommended Products -↓ -Top Trusted Products -↓ -Footer -``` ---- -Components -- Search Bar -- AI Recommendation Banner -- Product Cards -- Category Grid -- Trust Score Badges ---- -# 16.8 Product List Page -Features -- Search -- Filter -- Sort -- Pagination -Each Product Card displays: -- Image -- Name -- Price -- Rating -- Trust Score -- AI Recommendation Badge ---- -# 16.9 Product Detail Page -The Product Detail page is the most important page in VeriCart AI. -Layout -``` -Product Images -↓ -Product Information -↓ -Trust Score -↓ -AI Summary -↓ -Customer Reviews -↓ -Ask AI -↓ -Related Products -``` -Displayed Information -- Product Name -- Description -- Specifications -- Price -- Inventory -- Rating -- Trust Score -- AI Summary -- Fake Review Alert -- Buy Button ---- -# 16.10 AI Trust Card -Example -``` -★★★★★ -Trust Score -96 / 100 -Highly Trusted -AI Confidence -98% -Common Advantages -✓ Battery -✓ Build Quality -✓ Fast Delivery -Common Issues -• Packaging -``` ---- -# 16.11 Shopping Cart -Features -- Product List -- Quantity Selector -- Remove Product -- Total Price -- Checkout Button ---- -# 16.12 Checkout -Steps -Shipping Address -↓ -Order Review -↓ -Payment Simulation -↓ -Confirmation ---- -# 16.13 AI Shopping Assistant -Interface -``` -Chat Window -↓ -User Question -↓ -AI Response -↓ -Suggested Products -↓ -Related Questions -``` -Supported Questions -- Should I buy this? -- Which product is better? -- Is this trustworthy? -- What problems do customers mention? ---- -# 16.14 User Dashboard -Sections -- Personal Information -- Orders -- Reviews -- Wishlist -- Recommendations ---- -# 16.15 Admin Dashboard -Widgets -- User Statistics -- Product Statistics -- Orders -- AI Analytics -- Fake Reviews -- Trust Scores -- Revenue -- Activity Logs ---- -# 16.16 Responsive Design -Desktop -≥1200px ---- -Tablet -768–1199px ---- -Mobile -<768px ---- -# 16.17 Component Library -Vue Components -``` -Navbar -Footer -Sidebar -ProductCard -TrustCard -ReviewCard -ChatWindow -RecommendationCard -LoadingSpinner -Pagination -SearchBar -FilterPanel -``` ---- -# 16.18 User Flow -```mermaid -flowchart LR -Visitor ---> -Login ---> -Homepage ---> -Products ---> -Product Details ---> -AI Summary ---> -Cart ---> -Checkout ---> -Order ---> -Review ---> -AI Analysis -``` ---- -# 16.19 UX Metrics -The platform should achieve: -- Easy navigation -- Minimal clicks -- Fast loading -- Responsive interaction -- High readability -- Clear AI explanations ---- -# 16.20 Design System -Buttons -Primary -Secondary -Danger -Success ---- -Cards -Product Card -Review Card -Trust Card -AI Card ---- -Icons -Element Plus Icons ---- -Spacing -8px Grid System ---- -Border Radius -12px ---- -Shadow -Soft Material Shadow ---- -# 16.21 Chapter Summary -The UI/UX design of VeriCart AI emphasizes transparency, simplicity, and intelligent interaction. -Rather than presenting Artificial Intelligence as a separate feature, AI is embedded naturally into every stage of the shopping journey—from product discovery to post-purchase review analysis. -By combining Vue.js 3, Element Plus, responsive layouts, and explainable AI interfaces, the platform delivers a modern shopping experience that prioritizes customer trust and decision-making. \ No newline at end of file diff --git a/16. AI Architecture.txt b/16. AI Architecture.txt deleted file mode 100644 index 3243791..0000000 --- a/16. AI Architecture.txt +++ /dev/null @@ -1,405 +0,0 @@ -# AI Architecture -> **Document Version:** 1.0 -> -> **Product:** VeriCart AI -> -> **Section:** AI Architecture -> -> **Architecture Style:** Multi-LLM Intelligent Orchestration Platform -> -> **AI Models:** DeepSeek • Qwen • Tencent Hunyuan -> -> **Version:** AI Architecture v1.0 ---- -# 17. AI Architecture ---- -# 17.1 Introduction -Artificial Intelligence is the core innovation that differentiates VeriCart AI from conventional e-commerce platforms. -Most existing shopping platforms use AI only for recommendation algorithms or chatbots. VeriCart AI takes a different approach by integrating AI throughout the customer purchasing journey. -Rather than relying on a single Large Language Model (LLM), VeriCart AI adopts a **Multi-LLM Orchestration Architecture** that combines specialized AI models, each optimized for specific business functions. -This approach improves: -- Accuracy -- Explainability -- Scalability -- Maintainability -- Cost Optimization -- Future Expansion ---- -# 17.2 AI Design Objectives -The AI subsystem is designed to achieve the following objectives: -## AO-001 -Improve customer purchasing confidence. ---- -## AO-002 -Reduce fake review influence. ---- -## AO-003 -Generate explainable Trust Scores. ---- -## AO-004 -Summarize hundreds of customer reviews. ---- -## AO-005 -Provide intelligent shopping assistance. ---- -## AO-006 -Support multilingual reviews. ---- -## AO-007 -Allow future AI model integration. ---- -# 17.3 Multi-LLM Architecture -Unlike traditional AI systems that rely on a single model, VeriCart AI distributes intelligent tasks across multiple specialized models. -```mermaid -flowchart LR -Customer ---> -Vue["Vue.js 3"] ---> -Spring["Spring Boot"] ---> -Gateway["AI Gateway"] -Gateway --> DeepSeek -Gateway --> Qwen -Gateway --> Hunyuan -DeepSeek["DeepSeek"] -Qwen["Qwen"] -Hunyuan["Tencent Hunyuan"] -Gateway --> Database[(MySQL)] -Database --> Vue -``` ---- -# 17.4 Why Multi-LLM? -Every LLM has different strengths. -Instead of forcing one model to solve every problem, VeriCart AI selects the best model for each task. -Benefits include: -- Higher accuracy -- Better reasoning -- Lower operational cost -- Improved reliability -- Easier future upgrades ---- -# 17.5 AI Model Responsibilities -## DeepSeek -Primary Responsibilities -- Fake Review Detection -- Logical Reasoning -- Trust Score Analysis -- Explainability -- Review Consistency Analysis -Example -Input -``` -500 customer reviews -``` -Output -``` -Trust Score -94 -Fake Probability -7% -``` ---- -## Qwen -Primary Responsibilities -- Sentiment Analysis -- Product Recommendation -- Shopping Assistant -- Product Comparison -- Customer Question Answering -Example -Customer asks -``` -Should I buy this laptop? -``` -Qwen returns -``` -Advantages -Disadvantages -Recommendation -``` ---- -## Tencent Hunyuan -Primary Responsibilities -- Chinese NLP -- Review Summarization -- Translation -- Cross-language Review Understanding -Example -Chinese Reviews -↓ -English Summary -↓ -AI Recommendation ---- -# 17.6 AI Gateway -The AI Gateway acts as the intelligent controller responsible for routing AI requests. -Responsibilities -- Model Selection -- Request Routing -- Authentication -- Retry Logic -- Timeout Handling -- Response Aggregation -- Error Recovery -- Token Management ---- -Architecture -```mermaid -flowchart TB -SpringBoot -↓ -AI Gateway -↓ -Intent Detection -↓ -Task Router -↓ -DeepSeek -↓ -Qwen -↓ -Tencent Hunyuan -↓ -Response Aggregator -↓ -Spring Boot -``` ---- -# 17.7 AI Processing Pipeline -```mermaid -flowchart LR -Customer Review ---> -Review Validation ---> -Review Preprocessing ---> -AI Gateway ---> -Model Selection ---> -DeepSeek ---> -Qwen ---> -Hunyuan ---> -Response Merge ---> -Trust Score ---> -Database ---> -Frontend -``` ---- -# 17.8 AI Workflow -### Step 1 -Customer submits review. -↓ -### Step 2 -Spring Boot stores review. -↓ -### Step 3 -AI Gateway receives request. -↓ -### Step 4 -Gateway determines required AI services. -↓ -### Step 5 -DeepSeek -Analyzes -- Authenticity -- Fake Probability -- Trust -↓ -### Step 6 -Qwen -Analyzes -- Sentiment -- Product Opinion -- Recommendation -↓ -### Step 7 -Tencent Hunyuan -Generates -- Review Summary -- Translation -- Chinese Understanding -↓ -### Step 8 -Gateway combines all outputs. -↓ -### Step 9 -Results stored in MySQL. -↓ -### Step 10 -Vue.js displays AI insights. ---- -# 17.9 AI Service Routing -| Request Type | AI Model | -|---------------|----------| -| Fake Review Detection | DeepSeek | -| Trust Score | DeepSeek | -| Review Sentiment | Qwen | -| Recommendation | Qwen | -| Product Comparison | Qwen | -| Shopping Assistant | Qwen | -| Chinese Review | Tencent Hunyuan | -| Review Summary | Tencent Hunyuan | ---- -# 17.10 Prompt Engineering -Each AI model receives optimized prompts. ---- -## DeepSeek Prompt -Objective -Determine review authenticity. -Example -``` -Analyze this product review. -Determine: -1. Fake probability -2. Review consistency -3. Trust level -Return JSON. -``` ---- -## Qwen Prompt -``` -Analyze customer sentiment. -Classify -Positive -Neutral -Negative -Generate recommendation. -``` ---- -## Tencent Hunyuan Prompt -``` -Summarize customer reviews. -Generate: -Advantages -Disadvantages -Overall Opinion -Translate if required. -``` ---- -# 17.11 AI Response Format -All models return standardized JSON. -Example -```json -{ - "model":"DeepSeek", - "confidence":0.96, - "result":{ - "trustScore":95, - "fakeProbability":0.04 - } -} -``` ---- -# 17.12 AI Explainability -Every recommendation includes an explanation. -Example -``` -Trust Score -96 -Reason -✔ Verified customer reviews -✔ Consistent opinions -✔ Low fake review probability -✔ Positive sentiment -``` ---- -# 17.13 AI Confidence Score -Every AI result includes -Confidence -Example -``` -Confidence -98% -``` -Confidence helps customers understand AI reliability. ---- -# 17.14 AI Fallback Strategy -If one AI provider becomes unavailable: -```mermaid -flowchart LR -DeepSeek ---> -Unavailable ---> -Fallback ---> -Qwen ---> -Response -``` -If all AI providers fail -↓ -Display -``` -AI service temporarily unavailable. -Please try again later. -``` -The e-commerce platform continues functioning normally. ---- -# 17.15 AI Caching Strategy -Frequently requested AI results are cached. -Cache Examples -- Trust Score -- Review Summary -- Recommendation -Benefits -- Lower API cost -- Faster response -- Better user experience -Future -Redis Cache ---- -# 17.16 AI Security -Security measures include: -- API Key Encryption -- HTTPS -- Request Validation -- Rate Limiting -- Prompt Sanitization -- Response Validation -- Secret Management -- Secure Environment Variables ---- -# 17.17 AI Cost Optimization -To reduce operational costs: -- Cache AI responses. -- Reuse previous analyses. -- Batch review processing. -- Trigger analysis only when needed. -- Prioritize lightweight requests. ---- -# 17.18 Future AI Enhancements -Version 2.0 -- AI Image Search -- OCR Product Recognition -- Voice Shopping Assistant -- Personalized AI Agent -- RAG Knowledge Base -- Vector Database -- Semantic Product Search -- AI Trend Analysis ---- -# 17.19 AI Architecture Advantages -Compared with traditional AI systems: -| Traditional AI | VeriCart AI | -|----------------|-------------| -| Single Model | Multi-LLM | -| Limited Tasks | Specialized Models | -| Basic Chatbot | Intelligent Shopping Assistant | -| Static Recommendation | Explainable Recommendation | -| No Trust Analysis | AI Trust Score | -| Manual Review Reading | AI Review Summary | ---- -# 17.20 AI Architecture Summary -The Multi-LLM Architecture represents the technological foundation of VeriCart AI. -By orchestrating DeepSeek, Qwen, and Tencent Hunyuan through a dedicated AI Gateway, the platform delivers trustworthy, explainable, and intelligent shopping assistance while remaining scalable, secure, and extensible. -This architecture transforms Artificial Intelligence from a simple recommendation engine into the central decision-support system of the platform, enabling customers to shop with greater confidence and transparency. \ No newline at end of file diff --git a/17. Security Architecture.txt b/17. Security Architecture.txt deleted file mode 100644 index be922e4..0000000 --- a/17. Security Architecture.txt +++ /dev/null @@ -1,279 +0,0 @@ -# Security Architecture -> **Document Version:** 1.0 -> -> **Product:** VeriCart AI -> -> **Section:** Security Architecture -> -> **Security Standards:** OWASP Top 10 • JWT • RBAC • HTTPS ---- -# 18. Security Architecture ---- -# 18.1 Introduction -Security is a fundamental requirement of VeriCart AI because the platform processes sensitive information including user accounts, authentication credentials, orders, product reviews, and AI-generated insights. -The security architecture is designed according to the principle of **Defense in Depth**, where multiple independent security layers protect the application against common threats. -Primary objectives include: -- Protect user information -- Secure REST APIs -- Prevent unauthorized access -- Protect AI services -- Maintain data integrity -- Ensure secure deployment ---- -# 18.2 Security Principles -VeriCart AI follows these principles: -- Least Privilege -- Defense in Depth -- Secure by Default -- Zero Trust Authentication -- Input Validation -- Secure Communication -- Auditability ---- -# 18.3 Overall Security Architecture -```mermaid -flowchart TB -User -↓ -HTTPS -↓ -Vue.js 3 -↓ -JWT Authentication -↓ -Spring Security -↓ -REST Controllers -↓ -Business Services -↓ -MyBatis -↓ -MySQL -Business Services --> AI Gateway -AI Gateway --> DeepSeek -AI Gateway --> Qwen -AI Gateway --> TencentHunyuan -``` ---- -# 18.4 Authentication -Authentication uses JSON Web Tokens (JWT). -Workflow -```text -Login -↓ -Credential Validation -↓ -JWT Generation -↓ -Frontend Stores Token -↓ -Authenticated API Requests -↓ -JWT Validation -↓ -Business Logic -``` -JWT Payload -```json -{ - "userId":1001, - "username":"john", - "role":"CUSTOMER", - "exp":1750000000 -} -``` ---- -# 18.5 Authorization -Role-Based Access Control (RBAC) restricts access to protected resources. -| Role | Permissions | -|------|-------------| -| Customer | Browse products, place orders, submit reviews | -| Seller *(future)* | Manage own products and view analytics | -| Administrator | Full system management | -Example -```text -/admin/** -↓ -ADMIN only -``` ---- -# 18.6 Password Security -Passwords are never stored in plain text. -Algorithm -``` -BCrypt -``` -Requirements -- Minimum 8 characters -- Strong password validation -- Salted hashing ---- -# 18.7 HTTPS Communication -All communication between frontend, backend, and AI services should use HTTPS. -Protected Data -- JWT -- Login credentials -- User profiles -- Orders -- AI requests ---- -# 18.8 API Security -Every protected API requires: -``` -Authorization: -Bearer -``` -Security Measures -- Authentication -- Authorization -- Input validation -- Exception handling -- Request logging ---- -# 18.9 Input Validation -Every user input must be validated. -Examples -Registration -- Email format -- Password length -- Username uniqueness -Product Search -- Maximum keyword length -- Allowed characters -Review Submission -- Maximum review length -- Rating range (1–5) -Spring Validation annotations may include: -- `@NotBlank` -- `@Email` -- `@Size` -- `@Positive` -- `@Min` -- `@Max` ---- -# 18.10 Database Security -The backend protects the database through: -- MyBatis parameter binding -- Prepared statements -- Foreign key constraints -- Transactions -- Principle of least privilege for database accounts -Database credentials are stored in environment variables rather than source code. ---- -# 18.11 AI Security -AI integrations introduce additional security considerations. -Measures include: -- Secure storage of API keys -- Server-side AI requests only -- Prompt sanitization -- Response validation -- Request timeout handling -- Logging without exposing sensitive user data -Users never communicate directly with AI providers. ---- -# 18.12 Secret Management -Sensitive configuration values include: -- JWT Secret -- Database Password -- DeepSeek API Key -- Qwen API Key -- Tencent Hunyuan API Key -Example -```text -.env -↓ -SPRING_DATASOURCE_URL -SPRING_DATASOURCE_USERNAME -SPRING_DATASOURCE_PASSWORD -JWT_SECRET -DEEPSEEK_API_KEY -QWEN_API_KEY -HUNYUAN_API_KEY -``` -Secrets must never be committed to Git. ---- -# 18.13 OWASP Top 10 Mitigation -| OWASP Risk | Mitigation | -|------------|------------| -| Broken Access Control | RBAC + Spring Security | -| Cryptographic Failures | BCrypt + HTTPS | -| Injection | MyBatis parameter binding | -| Insecure Design | Layered Architecture | -| Security Misconfiguration | Secure environment configuration | -| Vulnerable Components | Dependency updates | -| Authentication Failures | JWT + password policy | -| Data Integrity Failures | Input validation + transactions | -| Logging Failures | Centralized audit logging | -| SSRF | Restrict outbound AI service communication | ---- -# 18.14 Logging & Audit Trail -Important events are recorded. -Examples -- Login -- Logout -- Failed login -- Password change -- Product updates -- Order creation -- Review submission -- AI request -- Administrator actions -Audit logs help diagnose problems and support security investigations. ---- -# 18.15 Error Handling -The system should not expose internal implementation details. -Example -Instead of: -```text -SQL Syntax Error... -``` -Return: -```json -{ - "code":500, - "message":"An unexpected error occurred." -} -``` -Detailed information is written only to server logs. ---- -# 18.16 Rate Limiting -Recommended limits -| Endpoint | Suggested Limit | -|-----------|-----------------| -| Login | 5 requests/minute/IP | -| Register | 3 requests/minute/IP | -| AI Chat | 20 requests/minute/user | -| Review Analysis | 30 requests/minute/user | -| Product Search | 100 requests/minute/IP | ---- -# 18.17 File Upload Security -If product images or avatars are supported: -- Restrict file types -- Limit maximum file size -- Rename uploaded files -- Scan uploads when possible -- Store files outside executable directories ---- -# 18.18 Security Monitoring -Monitor: -- Failed logins -- Suspicious API usage -- AI request failures -- Authentication errors -- Database connection failures -- High request rates -Future versions may integrate centralized monitoring platforms. ---- -# 18.19 Disaster Recovery -Recovery measures include: -- Database backups -- Configuration backups -- Docker image versioning -- Log retention -- Restore procedures -These practices reduce downtime after unexpected failures. ---- -# 18.20 Security Summary -VeriCart AI adopts a layered security architecture combining Spring Security, JWT authentication, Role-Based Access Control, HTTPS, secure password storage, input validation, and protected AI integrations. -By following OWASP security recommendations and modern software engineering practices, the platform protects user information while providing a secure foundation for AI-powered e-commerce functionality. \ No newline at end of file diff --git a/18. Deployment Architecture.txt b/18. Deployment Architecture.txt deleted file mode 100644 index ebfa83d..0000000 --- a/18. Deployment Architecture.txt +++ /dev/null @@ -1,383 +0,0 @@ -# Deployment Architecture -> **Document Version:** 1.0 -> -> **Product:** VeriCart AI -> -> **Section:** Deployment Architecture -> -> **Deployment Platform:** Docker + Docker Compose + Nginx -> -> **Backend:** Spring Boot 3 -> -> **Frontend:** Vue.js 3 -> -> **Database:** MySQL 8.0 -> -> **AI Platform:** AI Gateway + DeepSeek + Qwen + Tencent Hunyuan ---- -# 19. Deployment Architecture ---- -# 19.1 Introduction -Deployment architecture defines how VeriCart AI is packaged, deployed, configured, monitored, and maintained across different environments. -The deployment strategy follows modern DevOps principles using containerization to ensure: -- Consistent deployments -- Simplified maintenance -- Environment isolation -- Easy scalability -- High availability -- Portable infrastructure -Docker is selected as the primary deployment technology because it enables the development, testing, and production environments to remain consistent. ---- -# 19.2 Deployment Objectives -The deployment architecture aims to: -- Simplify application deployment -- Isolate application services -- Support scalable infrastructure -- Reduce environment inconsistencies -- Enable future cloud migration -- Improve maintainability ---- -# 19.3 Overall Deployment Architecture -```mermaid -flowchart TB -User -↓ -Browser -↓ -Nginx Reverse Proxy -↓ -Vue.js Container -↓ -Spring Boot Container -↓ -MySQL Container -Spring Boot Container --> AI Gateway -AI Gateway --> DeepSeek API -AI Gateway --> Qwen API -AI Gateway --> Tencent Hunyuan API -``` ---- -# 19.4 Deployment Components -| Component | Responsibility | -|------------|---------------| -| Vue.js Container | Frontend Application | -| Spring Boot Container | Business Logic | -| MySQL Container | Data Storage | -| AI Gateway | AI Request Routing | -| Nginx | Reverse Proxy | -| Docker Network | Internal Communication | ---- -# 19.5 Container Architecture -```mermaid -flowchart LR -Docker Network -Vue -SpringBoot -MySQL -Nginx -AIGateway -Vue --> Nginx -Nginx --> SpringBoot -SpringBoot --> MySQL -SpringBoot --> AIGateway -``` ---- -# 19.6 Docker Containers -## Container 1 -Vue.js Frontend -Purpose -Serve web interface. -Technology -Node.js -Nginx ---- -## Container 2 -Spring Boot Backend -Purpose -Business Logic -REST API -Authentication -AI Integration ---- -## Container 3 -MySQL -Purpose -Persistent Data Storage ---- -## Container 4 -AI Gateway *(Recommended Architecture)* -Purpose -- AI Routing -- Prompt Management -- Response Aggregation -- API Token Management ---- -## Container 5 -Nginx -Purpose -- Reverse Proxy -- HTTPS -- Static Content -- Load Balancer (future) ---- -# 19.7 Docker Network -All containers communicate using a private Docker bridge network. -```text -vericart-network -↓ -Vue -↓ -Spring Boot -↓ -MySQL -↓ -AI Gateway -``` -Benefits -- Isolation -- Secure communication -- Easy scaling ---- -# 19.8 Environment Configuration -Configuration is managed using environment variables. -Example -```text -SPRING_PROFILES_ACTIVE=prod -MYSQL_HOST=mysql -MYSQL_PORT=3306 -MYSQL_DATABASE=vericart -MYSQL_USERNAME=root -MYSQL_PASSWORD=****** -JWT_SECRET=******** -DEEPSEEK_API_KEY=******** -QWEN_API_KEY=******** -HUNYUAN_API_KEY=******** -``` -Sensitive information is never stored in source code. ---- -# 19.9 Deployment Environments -## Development -Purpose -Local development -Characteristics -- Debugging enabled -- Local database -- Local Docker Compose ---- -## Testing -Purpose -Integration testing -Characteristics -- Test database -- Automated testing -- API verification ---- -## Staging -Purpose -Pre-production validation -Characteristics -- Production-like configuration -- User Acceptance Testing ---- -## Production -Purpose -Live deployment -Characteristics -- HTTPS enabled -- Optimized builds -- Monitoring enabled -- Secure configuration ---- -# 19.10 Docker Compose Architecture -```mermaid -flowchart TB -docker-compose.yml -↓ -Nginx -↓ -Vue -↓ -Spring Boot -↓ -MySQL -↓ -AI Gateway -``` -Docker Compose manages: -- Container startup -- Networking -- Environment variables -- Volume mounting -- Restart policies ---- -# 19.11 Persistent Storage -Persistent Docker volumes are used for: -- MySQL database -- Uploaded images -- Application logs -Example -```text -mysql-data -uploads -logs -``` -This ensures data is retained even if containers are recreated. ---- -# 19.12 Reverse Proxy -Nginx responsibilities include: -- HTTPS termination -- Static frontend hosting -- API forwarding -- Compression -- Security headers -Routing Example -```text -/ -↓ -Vue.js -/api -↓ -Spring Boot -``` ---- -# 19.13 CI/CD Pipeline (Future) -Recommended workflow -```mermaid -flowchart LR -Developer -↓ -GitHub -↓ -GitHub Actions -↓ -Build -↓ -Unit Tests -↓ -Docker Image -↓ -Deploy -``` -Pipeline Stages -1. Code Push -2. Build -3. Test -4. Package -5. Docker Image -6. Deployment ---- -# 19.14 Monitoring -Recommended monitoring includes: -Application -- CPU -- Memory -- Response Time -Database -- Query performance -- Connection count -AI -- API latency -- Token usage -- Failure rate -System -- Container health -- Disk usage -- Network traffic ---- -# 19.15 Logging -Centralized logs should capture: -Frontend -- JavaScript errors -Backend -- API requests -- Exceptions -- Authentication events -AI Gateway -- AI requests -- Model selection -- Response times -Database -- Slow queries ---- -# 19.16 Backup Strategy -Database Backup -Daily -↓ -Compressed Backup -↓ -Secure Storage -↓ -Restore Testing -Uploaded Files -Weekly backup -Application Configuration -Version-controlled through Git ---- -# 19.17 High Availability (Future) -Future deployment improvements may include: -- Multiple Spring Boot instances -- Load balancing -- Database replication -- Redis caching -- Kubernetes orchestration -These enhancements are outside the MVP but supported by the modular architecture. ---- -# 19.18 Cloud Deployment (Future) -The architecture can be migrated to cloud platforms such as: -- Alibaba Cloud -- Tencent Cloud -- AWS -- Microsoft Azure -- Google Cloud -Possible cloud services include: -- Managed databases -- Container orchestration -- Object storage -- Monitoring services ---- -# 19.19 Deployment Workflow -```mermaid -sequenceDiagram -Developer->>GitHub: Push Code -GitHub->>CI: Trigger Build -CI->>Docker: Build Images -Docker->>Registry: Store Images -Registry->>Server: Pull Images -Server->>Docker Compose: Start Services -Docker Compose-->>Users: Application Available -``` ---- -# 19.20 Disaster Recovery -Recovery procedures include: -- Database restoration from backups -- Redeployment using Docker Compose -- Configuration recovery from version control -- AI Gateway reconnection -- Log inspection for root-cause analysis -Recovery objectives should minimize downtime and data loss. ---- -# 19.21 Scalability Strategy -The deployment architecture supports future growth through: -- Stateless backend services -- Independent AI Gateway scaling -- Separate database layer -- Containerized deployment -- Horizontal expansion of frontend and backend services ---- -# 19.22 Deployment Checklist -Before production deployment, verify: -- Docker images built successfully -- Environment variables configured -- Database migrations completed -- HTTPS configured -- JWT secret configured -- AI API keys validated -- Health checks passing -- Backup strategy enabled -- Logging configured -- Monitoring operational ---- -# 19.23 Chapter Summary -VeriCart AI adopts a containerized deployment architecture based on Docker, Docker Compose, and Nginx to provide a portable, scalable, and maintainable deployment solution. -By separating the frontend, backend, database, and AI Gateway into independent services, the architecture supports future cloud migration, horizontal scaling, and continuous integration while maintaining secure communication and operational reliability. -This deployment strategy ensures that VeriCart AI can evolve from an academic project into a production-ready platform with minimal architectural changes. \ No newline at end of file diff --git a/9. User Journey & User Stories .txt b/9. User Journey & User Stories .txt deleted file mode 100644 index a35fcd2..0000000 --- a/9. User Journey & User Stories .txt +++ /dev/null @@ -1,436 +0,0 @@ -# User Journey & User Stories -> **Document Version:** 1.0 -> **Product:** VeriCart AI -> **Section:** User Journey & User Stories ---- -# 10. User Journey & User Stories -## 10.1 Introduction -A successful product is built around the needs of its users rather than the technologies behind it. -This chapter describes how different users interact with VeriCart AI throughout their journey. It defines complete user journeys and detailed user stories that serve as the foundation for system design, UI/UX development, API implementation, database design, software testing, and AI integration. -The primary objective is to ensure that every feature implemented in VeriCart AI directly addresses a real user need. ---- -# 10.2 User Journey Overview -The overall customer journey consists of six major stages. -```text -Discover - │ - ▼ -Explore Products - │ - ▼ -Evaluate Products - │ - ▼ -Purchase - │ - ▼ -Post-Purchase - │ - ▼ -Review & AI Learning -``` -Each stage introduces opportunities for Artificial Intelligence to improve customer decision-making. ---- -# 10.3 Customer Journey -## Stage 1 — Registration -### Goal -Create a secure customer account. -### User Actions -- Register -- Login -- Verify credentials -### System Response -- Validate information -- Create account -- Generate JWT Token -### Success Criteria -Customer successfully logs in. ---- -## Stage 2 — Product Discovery -Customer actions -- Browse categories -- Search products -- Apply filters -System actions -- Search database -- Display matching products -- Recommend products ---- -## Stage 3 — Product Evaluation -Customer views -- Product details -- Customer reviews -- Trust Score -- AI Summary -Customer asks AI -> Should I buy this product? -AI responds -- Advantages -- Disadvantages -- Recommendation ---- -## Stage 4 — Purchase -Customer -↓ -Shopping Cart -↓ -Checkout -↓ -Order Confirmation ---- -## Stage 5 — Review -Customer writes review. -↓ -System stores review. -↓ -AI analyzes review. -↓ -Trust Score updates. ---- -## Stage 6 — Continuous Learning -The AI system continuously improves product analysis by processing newly submitted reviews. ---- -# 10.4 Customer Journey Map -| Stage | Customer Goal | AI Support | -|---------|--------------|------------| -| Register | Create Account | Authentication | -| Browse | Find Products | Recommendation | -| Compare | Evaluate Products | Trust Score | -| Purchase | Buy Product | Shopping Assistant | -| Review | Share Experience | Sentiment Analysis | -| Return | Future Shopping | Personalized Recommendation | ---- -# 10.5 Seller Journey -Seller -↓ -Login -↓ -Manage Products -↓ -Monitor Reviews -↓ -Analyze AI Reports -↓ -Improve Products -↓ -Increase Customer Trust ---- -Seller Objectives -- Add products -- Edit products -- Remove products -- Understand customer opinions -- Monitor Trust Scores ---- -# 10.6 Administrator Journey -Administrator -↓ -Login -↓ -Dashboard -↓ -Manage Users -↓ -Manage Products -↓ -Monitor Reviews -↓ -Review AI Analytics -↓ -Maintain Platform ---- -Responsibilities -- User management -- Product approval -- Review moderation -- AI monitoring -- Platform maintenance ---- -# 10.7 AI Shopping Assistant Journey -Customer asks question -↓ -Spring Boot API -↓ -AI Gateway -↓ -DeepSeek -↓ -Qwen -↓ -Tencent Hunyuan -↓ -AI Response -↓ -Frontend Display ---- -# 10.8 Customer User Stories ---- -## Authentication -### US-001 -As a visitor, -I want to register an account -so that I can purchase products. -Priority -Critical ---- -### US-002 -As a customer, -I want to login securely -so that I can access my account. -Priority -Critical ---- -### US-003 -As a customer, -I want to reset my password -so that I can recover my account. -Priority -High ---- -# Product Module ---- -### US-004 -As a customer, -I want to browse products -so that I can find products I like. -Priority -Critical ---- -### US-005 -As a customer, -I want to search products -so that I can quickly locate items. -Priority -Critical ---- -### US-006 -As a customer, -I want to filter products -so that I can narrow my search. -Priority -High ---- -### US-007 -As a customer, -I want to compare products -so that I can choose the best option. -Priority -High ---- -# Review Module ---- -### US-008 -As a customer, -I want to read customer reviews -so that I understand product quality. -Priority -Critical ---- -### US-009 -As a customer, -I want to write reviews -so that I can share my experience. -Priority -Critical ---- -### US-010 -As a customer, -I want to edit my review -so that I can correct mistakes. -Priority -Medium ---- -# Shopping Cart ---- -### US-011 -As a customer, -I want to add products to my cart -so that I can purchase later. -Priority -Critical ---- -### US-012 -As a customer, -I want to remove products -so that I can update my shopping cart. -Priority -High ---- -### US-013 -As a customer, -I want to place an order -so that I can purchase products. -Priority -Critical ---- -# AI Features ---- -### US-014 -As a customer, -I want AI to summarize reviews -so that I do not need to read hundreds of reviews. -Priority -Critical ---- -### US-015 -As a customer, -I want to see the AI Trust Score -so that I know whether a product is trustworthy. -Priority -Critical ---- -### US-016 -As a customer, -I want AI to detect fake reviews -so that I avoid misleading information. -Priority -Critical ---- -### US-017 -As a customer, -I want personalized recommendations -so that I discover relevant products. -Priority -High ---- -### US-018 -As a customer, -I want to ask AI shopping questions -so that I receive intelligent purchasing advice. -Priority -Critical ---- -# Seller User Stories ---- -### US-019 -As a seller, -I want to add new products -so that customers can purchase them. -Priority -Critical ---- -### US-020 -As a seller, -I want AI to summarize customer feedback -so that I understand product strengths and weaknesses. -Priority -High ---- -### US-021 -As a seller, -I want to monitor Trust Scores -so that I can improve customer confidence. -Priority -Medium ---- -# Administrator User Stories ---- -### US-022 -As an administrator, -I want to manage users -so that platform security is maintained. -Priority -Critical ---- -### US-023 -As an administrator, -I want to approve products -so that platform quality remains high. -Priority -Critical ---- -### US-024 -As an administrator, -I want AI to identify suspicious reviews -so that moderation becomes more efficient. -Priority -Critical ---- -### US-025 -As an administrator, -I want to monitor AI analytics -so that I understand platform health. -Priority -High ---- -# AI User Stories ---- -### US-026 -As the AI system, -I want to analyze customer reviews -so that Trust Scores remain accurate. ---- -### US-027 -As the AI system, -I want to detect spam reviews -so that customers receive reliable information. ---- -### US-028 -As the AI system, -I want to recommend products -so that customers enjoy personalized shopping. ---- -### US-029 -As the AI system, -I want to explain my recommendations -so that customers trust AI decisions. ---- -# 10.9 User Story Prioritization -| Priority | Description | -|------------|-------------| -| Critical | Required for MVP | -| High | Strongly Recommended | -| Medium | Nice to Have | -| Low | Future Enhancement | ---- -# 10.10 MVP User Stories -The MVP includes: -✓ Registration -✓ Login -✓ Product Search -✓ Product Details -✓ Shopping Cart -✓ Checkout -✓ Reviews -✓ Trust Score -✓ Review Summary -✓ Fake Review Detection -✓ Shopping Assistant ---- -# 10.11 Acceptance Criteria Examples -### US-015 -**Title** -View AI Trust Score -**Acceptance Criteria** -- Trust Score displayed on every product page. -- Score automatically updates after new reviews. -- Score ranges from 0–100. -- Trust level displayed (Low, Medium, High). -- User can view AI explanation. ---- -### US-018 -**Title** -Ask AI Before Buying -**Acceptance Criteria** -- Customer submits a question. -- AI processes product data and reviews. -- Response generated within a reasonable response time. -- AI provides explanation with recommendation. -- Response displayed in chat interface. ---- -# 10.12 Story Traceability Matrix -| User Story | Related Module | -|------------|----------------| -| US-001 | Authentication | -| US-004 | Product | -| US-011 | Cart | -| US-013 | Order | -| US-015 | AI Trust | -| US-016 | Fake Review Detection | -| US-018 | AI Shopping Assistant | -| US-024 | AI Moderation | ---- -# 10.13 Chapter Summary -This chapter defines the complete user journeys and user stories that guide the development of VeriCart AI. -By understanding the needs of customers, sellers, administrators, and the AI system itself, the development team can build features that deliver measurable value while maintaining a user-centered design philosophy. -The user stories documented here provide the foundation for the next chapter, **Functional Requirements**, where each system capability will be formally specified using Software Requirements Specification (SRS) methodology with requirement IDs, priorities, and acceptance criteria. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..4812290 --- /dev/null +++ b/README.md @@ -0,0 +1,192 @@ +# VeriCart AI + +**AI-Powered E-Commerce Trust Platform** + +VeriCart AI is an intelligent e-commerce platform that leverages multiple LLM providers (DeepSeek, Qwen, Hunyuan) to deliver AI-driven product reviews analysis, authenticity verification, and smart shopping recommendations — building trust between buyers and sellers. + +--- + +## Tech Stack + +| Layer | Technology | +| ----------- | --------------------------------------------------------------- | +| **Backend** | Spring Boot 3.2.0, Java 17, MyBatis 3.0.3, Spring Security + JWT | +| **Frontend**| Vue 3.4, Vite 5, Pinia, Vue Router, Element Plus, Axios | +| **Database**| MySQL 8.0 (production), H2 (testing) | +| **AI** | DeepSeek (deepseek-chat), Qwen (qwen-plus), Hunyuan (hunyuan-lite) | +| **Infra** | Docker Compose | + +--- + +## Project Structure + +``` +VeriCart AI/ +├── backend/ # Spring Boot backend +│ ├── src/main/java/com/vericart/ +│ │ ├── config/ # Security, AI, CORS configuration +│ │ ├── controller/ # REST API controllers +│ │ ├── dto/ # Data transfer objects +│ │ ├── entity/ # MyBatis entity classes +│ │ ├── mapper/ # MyBatis mapper interfaces +│ │ ├── service/ # Business logic & AI gateway +│ │ └── util/ # Utility classes +│ ├── src/main/resources/ +│ │ ├── mapper/ # MyBatis XML SQL mappings +│ │ ├── schema.sql # Database DDL (10 tables) +│ │ └── application.yml # Main configuration +│ └── src/test/ # JUnit tests (H2 in-memory) +├── frontend/ # Vue 3 SPA frontend +│ ├── src/ +│ │ ├── components/ # Reusable Vue components +│ │ ├── views/ # Page-level views +│ │ ├── router/ # Vue Router config +│ │ ├── stores/ # Pinia state stores +│ │ └── api/ # Axios API clients +│ └── vite.config.js +├── docs/ # Project documentation & reports +├── PRD/ # Product requirements documents +├── docker-compose.yml # Full-stack Docker deployment +└── README.md +``` + +--- + +## Quick Start + +### Prerequisites + +- **Java 17** + Maven 3.8+ +- **Node.js 18+** + npm +- **MySQL 8.0** (local or Docker) +- **Docker & Docker Compose** (optional) + +### 1. Clone & Environment + +```bash +git clone https://github.com/simul49/VeriCart-AI.git +cd VeriCart-AI +``` + +Set your API keys and database password via environment variables (or create a `.env` file): + +```bash +export DB_PASSWORD=your_mysql_password +export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx +export QWEN_API_KEY=sk-xxxxxxxxxxxxxxxx +export HUNYUAN_API_KEY=sk-xxxxxxxxxxxxxxxx +export JWT_SECRET=your_jwt_secret +``` + +### 2. Start with Docker (Recommended) + +```bash +docker-compose up -d +``` + +This starts MySQL, the Spring Boot backend (port 8080), and the Vue frontend (port 80) in one command. + +### 3. Manual Start + +**Database** — Create the MySQL database: + +```sql +CREATE DATABASE IF NOT EXISTS vericart + CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +``` + +Tables are auto-created by `schema.sql` on startup. + +**Backend** (port 8080): + +```bash +cd backend +mvn spring-boot:run +``` + +**Frontend** (port 5173): + +```bash +cd frontend +npm install +npm run dev +``` + +Open http://localhost:5173 in your browser. + +--- + +## Database + +10 MySQL tables managing the full e-commerce trust lifecycle: + +| Table | Purpose | +| ------------------ | ------------------------------------- | +| `user` | User accounts (buyers & sellers) | +| `product` | Product listings | +| `category` | Product categories | +| `cart_item` | Shopping cart items | +| `wishlist` | User wishlists | +| `orders` | Purchase orders | +| `order_item` | Line items within orders | +| `review` | Product reviews & ratings | +| `ai_analysis_log` | AI review analysis results | +| `notification` | System notifications | + +Testing uses H2 in-memory with MySQL compatibility mode (`MODE=MySQL`). + +--- + +## API Endpoints + +Base URL: `http://localhost:8080/api` + +| Method | Endpoint | Description | +| ------ | ------------------------- | ------------------------ | +| POST | `/auth/register` | User registration | +| POST | `/auth/login` | User login (JWT) | +| GET | `/products` | List products | +| GET | `/products/{id}` | Product detail | +| GET | `/products/{id}/reviews` | Product reviews | +| POST | `/reviews/analyze` | AI review analysis | +| GET | `/cart` | View cart | +| POST | `/cart/add` | Add to cart | +| GET | `/wishlist` | View wishlist | +| POST | `/orders` | Place order | +| GET | `/orders/{id}` | Order detail | + +--- + +## AI Features + +The platform integrates 3 LLM providers through a unified gateway: + +- **DeepSeek** — Core engine for review sentiment analysis and authenticity scoring +- **Qwen (Alibaba)** — Product description generation and multilingual support +- **Hunyuan (Tencent)** — Lightweight fallback for basic analysis tasks + +Each provider is configured in `application.yml` with environment-variable API keys. + +--- + +## Running Tests + +**Backend** (JUnit + H2 in-memory): + +```bash +cd backend +mvn test +``` + +**Frontend** (Vitest): + +```bash +cd frontend +npm test +``` + +--- + +## License + +This project is developed for academic/learning purposes as part of an internship training program.