Add LittleShop.Client SDK library with complete API wrapper
Features: - Complete .NET client SDK for LittleShop API - JWT authentication with automatic token management - Catalog service for products and categories - Order service with payment creation - Retry policies using Polly for resilience - Error handling middleware - Dependency injection support - Comprehensive documentation and examples SDK Components: - Authentication service with token refresh - Strongly-typed models for all API responses - HTTP handlers for retry and error handling - Extension methods for easy DI registration - Example console application demonstrating usage Test Updates: - Fixed test compilation errors - Updated test data builders for new models - Corrected service constructor dependencies - Fixed enum value changes (PaymentStatus, OrderStatus) Documentation: - Complete project README with features and usage - Client SDK README with detailed examples - API endpoint documentation - Security considerations - Deployment guidelines Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
sysadmin
281
PROJECT_README.md
Normal file
281
PROJECT_README.md
Normal file
@@ -0,0 +1,281 @@
|
||||
# LittleShop E-Commerce Platform
|
||||
|
||||
A complete e-commerce platform built with ASP.NET Core 9.0, featuring multi-cryptocurrency payment support and a privacy-focused design.
|
||||
|
||||
## 🎯 Features
|
||||
|
||||
### Core Functionality
|
||||
- **Product Management**: Categories, products with photos, weight-based pricing
|
||||
- **Order Management**: Complete order workflow from creation to delivery
|
||||
- **Multi-Cryptocurrency Payments**: Bitcoin, Monero, USDT, Litecoin, Ethereum, Zcash, Dash, Dogecoin
|
||||
- **Shipping Management**: Weight-based shipping rates with Royal Mail integration
|
||||
- **Admin Panel**: Full administrative interface for managing the store
|
||||
- **API**: RESTful API with JWT authentication for client applications
|
||||
|
||||
### Security & Privacy
|
||||
- **No KYC Requirements**: Privacy-focused design with minimal data collection
|
||||
- **Dual Authentication**: Cookie-based for admin panel, JWT for API
|
||||
- **Self-Hosted Payments**: BTCPay Server integration for cryptocurrency processing
|
||||
- **Secure Password Storage**: PBKDF2 with 100,000 iterations
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Prerequisites
|
||||
- .NET 9.0 SDK
|
||||
- SQLite (included)
|
||||
- BTCPay Server instance (for payments)
|
||||
|
||||
### Installation
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/yourusername/littleshop.git
|
||||
cd littleshop
|
||||
```
|
||||
|
||||
2. Restore dependencies:
|
||||
```bash
|
||||
dotnet restore
|
||||
```
|
||||
|
||||
3. Run the application:
|
||||
```bash
|
||||
dotnet run --project LittleShop/LittleShop.csproj
|
||||
```
|
||||
|
||||
4. Access the application:
|
||||
- Admin Panel: https://localhost:5001/Admin
|
||||
- API Documentation: https://localhost:5001/swagger
|
||||
- Default credentials: `admin` / `admin`
|
||||
|
||||
## 📁 Project Structure
|
||||
|
||||
```
|
||||
LittleShop/
|
||||
├── LittleShop/ # Main web application
|
||||
│ ├── Areas/Admin/ # Admin panel MVC
|
||||
│ ├── Controllers/ # API controllers
|
||||
│ ├── Services/ # Business logic
|
||||
│ ├── Models/ # Database entities
|
||||
│ ├── DTOs/ # Data transfer objects
|
||||
│ └── Data/ # Entity Framework context
|
||||
├── LittleShop.Client/ # .NET client SDK
|
||||
│ ├── Services/ # API client services
|
||||
│ ├── Models/ # Client models
|
||||
│ └── Http/ # HTTP handlers
|
||||
└── LittleShop.Tests/ # Test suite
|
||||
├── Unit/ # Unit tests
|
||||
├── Integration/ # API integration tests
|
||||
├── Security/ # Security tests
|
||||
└── UI/ # UI automation tests
|
||||
```
|
||||
|
||||
## 💻 Using the Client SDK
|
||||
|
||||
### Installation
|
||||
```bash
|
||||
dotnet add reference LittleShop.Client/LittleShop.Client.csproj
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
```csharp
|
||||
using LittleShop.Client.Extensions;
|
||||
|
||||
// Configure services
|
||||
services.AddLittleShopClient(options =>
|
||||
{
|
||||
options.BaseUrl = "https://localhost:5001";
|
||||
options.TimeoutSeconds = 30;
|
||||
options.MaxRetryAttempts = 3;
|
||||
});
|
||||
|
||||
// Use the client
|
||||
var client = serviceProvider.GetRequiredService<ILittleShopClient>();
|
||||
|
||||
// Authenticate
|
||||
await client.Authentication.LoginAsync("admin", "admin");
|
||||
|
||||
// Get products
|
||||
var products = await client.Catalog.GetProductsAsync();
|
||||
|
||||
// Create order
|
||||
var order = await client.Orders.CreateOrderAsync(new CreateOrderRequest
|
||||
{
|
||||
IdentityReference = "CUST001",
|
||||
ShippingName = "John Doe",
|
||||
ShippingAddress = "123 Main St",
|
||||
ShippingCity = "London",
|
||||
ShippingPostCode = "SW1A 1AA",
|
||||
ShippingCountry = "United Kingdom",
|
||||
Items = new[] { new CreateOrderItem { ProductId = productId, Quantity = 1 } }
|
||||
});
|
||||
```
|
||||
|
||||
## 🔌 API Endpoints
|
||||
|
||||
### Authentication
|
||||
- `POST /api/auth/login` - Login with username/password
|
||||
- `POST /api/auth/refresh` - Refresh JWT token
|
||||
|
||||
### Catalog (Requires Authentication)
|
||||
- `GET /api/catalog/categories` - Get all categories
|
||||
- `GET /api/catalog/categories/{id}` - Get category by ID
|
||||
- `GET /api/catalog/products` - Get products with filtering
|
||||
- `GET /api/catalog/products/{id}` - Get product by ID
|
||||
|
||||
### Orders (Requires Authentication)
|
||||
- `POST /api/orders` - Create new order
|
||||
- `GET /api/orders/by-identity/{id}` - Get orders by customer identity
|
||||
- `GET /api/orders/{id}` - Get order by ID
|
||||
- `POST /api/orders/{id}/payments` - Create crypto payment
|
||||
- `POST /api/orders/payments/webhook` - BTCPay webhook endpoint
|
||||
|
||||
## 🗄️ Database Schema
|
||||
|
||||
### Core Tables
|
||||
- **Users**: Staff/admin accounts only
|
||||
- **Categories**: Product categories
|
||||
- **Products**: Product catalog with pricing and weight
|
||||
- **ProductPhotos**: Product images with sorting
|
||||
- **Orders**: Customer orders with shipping details
|
||||
- **OrderItems**: Individual items in orders
|
||||
- **CryptoPayments**: Cryptocurrency payment records
|
||||
- **ShippingRates**: Weight-based shipping calculations
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
Run all tests:
|
||||
```bash
|
||||
dotnet test
|
||||
```
|
||||
|
||||
Run specific test categories:
|
||||
```bash
|
||||
# Unit tests only
|
||||
dotnet test --filter Category=Unit
|
||||
|
||||
# Integration tests
|
||||
dotnet test --filter Category=Integration
|
||||
|
||||
# Security tests
|
||||
dotnet test --filter Category=Security
|
||||
```
|
||||
|
||||
### Test Coverage
|
||||
- ✅ Unit tests for all services
|
||||
- ✅ Integration tests for all API endpoints
|
||||
- ✅ Security tests for authentication enforcement
|
||||
- ✅ UI automation tests with Playwright
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### appsettings.json
|
||||
```json
|
||||
{
|
||||
"ConnectionStrings": {
|
||||
"DefaultConnection": "Data Source=littleshop.db"
|
||||
},
|
||||
"Jwt": {
|
||||
"Key": "YourSuperSecretKeyThatIsAtLeast32CharactersLong!",
|
||||
"Issuer": "LittleShop",
|
||||
"Audience": "LittleShop",
|
||||
"ExpiryMinutes": 60
|
||||
},
|
||||
"BTCPayServer": {
|
||||
"Url": "https://your-btcpay.com",
|
||||
"StoreId": "your-store-id",
|
||||
"ApiKey": "your-api-key"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🚢 Deployment
|
||||
|
||||
### Production Checklist
|
||||
1. Update connection strings
|
||||
2. Configure BTCPay Server
|
||||
3. Set strong JWT secret key
|
||||
4. Enable HTTPS only
|
||||
5. Configure CORS for your domain
|
||||
6. Set up SSL certificates
|
||||
7. Configure logging
|
||||
8. Set up database backups
|
||||
|
||||
### Docker Support
|
||||
```dockerfile
|
||||
FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS base
|
||||
WORKDIR /app
|
||||
EXPOSE 80 443
|
||||
|
||||
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
|
||||
WORKDIR /src
|
||||
COPY . .
|
||||
RUN dotnet restore
|
||||
RUN dotnet build -c Release
|
||||
RUN dotnet publish -c Release -o /app/publish
|
||||
|
||||
FROM base AS final
|
||||
WORKDIR /app
|
||||
COPY --from=build /app/publish .
|
||||
ENTRYPOINT ["dotnet", "LittleShop.dll"]
|
||||
```
|
||||
|
||||
## 📊 Sample Data
|
||||
|
||||
The application includes sample data seeder that creates:
|
||||
- 3 Categories (Electronics, Clothing, Books)
|
||||
- 5 Products with various prices
|
||||
- 5 Shipping rates (Royal Mail options)
|
||||
- 5 Sample orders in different statuses
|
||||
- 3 Crypto payments demonstrating payment flow
|
||||
|
||||
## 🛡️ Security Considerations
|
||||
|
||||
- **Authentication Required**: All API endpoints require JWT authentication
|
||||
- **No Public Endpoints**: Client applications must authenticate first
|
||||
- **Password Security**: PBKDF2 with salt and 100,000 iterations
|
||||
- **Input Validation**: FluentValidation on all inputs
|
||||
- **SQL Injection Protection**: Entity Framework Core with parameterized queries
|
||||
- **XSS Protection**: Razor view encoding and validation
|
||||
- **CORS**: Configured for specific domains in production
|
||||
|
||||
## 📝 License
|
||||
|
||||
This project is proprietary software. All rights reserved.
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Add tests for new functionality
|
||||
5. Ensure all tests pass
|
||||
6. Submit a pull request
|
||||
|
||||
## 📞 Support
|
||||
|
||||
For issues, questions, or suggestions:
|
||||
- Open an issue on GitHub
|
||||
- Contact: support@littleshop.com
|
||||
|
||||
## 🏗️ Built With
|
||||
|
||||
- **ASP.NET Core 9.0** - Web framework
|
||||
- **Entity Framework Core** - ORM
|
||||
- **SQLite** - Database
|
||||
- **Bootstrap 5** - UI framework
|
||||
- **JWT** - API authentication
|
||||
- **BTCPay Server** - Cryptocurrency payments
|
||||
- **xUnit** - Testing framework
|
||||
- **Playwright** - UI automation
|
||||
- **Serilog** - Logging
|
||||
|
||||
## 📈 Version History
|
||||
|
||||
- **v1.0.0** - Initial release with core e-commerce functionality
|
||||
- Product catalog management
|
||||
- Order processing workflow
|
||||
- Multi-cryptocurrency payments
|
||||
- Admin panel and API
|
||||
- Client SDK library
|
||||
- Comprehensive test coverage
|
||||
Reference in New Issue
Block a user