# Framework Template - Backend

This is a .NET 10 backend framework template extracted from the MiAssessment project. It provides a clean architecture foundation with essential features for building mini-program backends.

## Features

- **Authentication & Authorization**: JWT + Refresh Token mechanism
- **User Management**: Basic user info, login logs
- **WeChat Integration**: Mini-program login, phone number retrieval
- **WeChat Pay**: V3 payment, callback verification, refunds
- **Address Management**: User shipping address CRUD
- **Configuration Management**: System configuration read/write
- **File Upload**: Local storage + Tencent Cloud COS dual mode
- **Admin RBAC**: Complete role-based access control system
- **Dictionary Management**: Static data + dynamic SQL query support
- **Payment Orders**: Generic payment order with reward handler mechanism
- **Redis Cache**: Cache service wrapper

## Project Structure

```
server/MiAssessment/
├── MiAssessment.sln
├── src/
│   ├── MiAssessment.Api/              # Web API Layer
│   │   ├── Controllers/
│   │   │   ├── AuthController.cs         # Authentication
│   │   │   ├── UserController.cs         # User management
│   │   │   ├── AddressController.cs      # Address management
│   │   │   ├── ConfigController.cs       # Configuration
│   │   │   ├── PayController.cs          # Payment
│   │   │   ├── NotifyController.cs       # Payment callbacks
│   │   │   └── HealthController.cs       # Health check
│   │   ├── Filters/
│   │   └── Program.cs
│   │
│   ├── MiAssessment.Core/             # Business Logic Layer
│   │   ├── Interfaces/
│   │   ├── Services/
│   │   └── Mappings/
│   │
│   ├── MiAssessment.Infrastructure/   # Infrastructure Layer
│   │   ├── Cache/
│   │   ├── External/
│   │   └── Modules/
│   │
│   ├── MiAssessment.Model/            # Data Model Layer
│   │   ├── Entities/
│   │   ├── Models/
│   │   ├── Data/
│   │   └── Base/
│   │
│   ├── MiAssessment.Admin/            # Admin RBAC
│   │   ├── Controllers/
│   │   ├── Services/
│   │   ├── Entities/
│   │   └── Data/
│   │
│   └── MiAssessment.Admin.Business/   # Admin Business Module
│       ├── Controllers/
│       └── Services/
│
├── scripts/                              # Database Scripts
│   ├── init_admin_db.sql                 # Admin database initialization
│   └── init_business_db.sql              # Business database initialization
│
├── tests/
│   └── MiAssessment.Tests/            # Unit & Property Tests
│
└── README.md
```

## Placeholder Locations

When generating a new project from this template, the following placeholders need to be replaced:

### Project Name Placeholders

| Placeholder | Description | Example |
|-------------|-------------|---------|
| `MiAssessment` | Project name (PascalCase) | `MyApp` |
| `MiAssessment` | Original project name to replace | → `MyApp` |

### Files Requiring Project Name Replacement

#### Solution & Project Files
- `MiAssessment.sln` → `MiAssessment.sln`
- `src/MiAssessment.Api/MiAssessment.Api.csproj` → `src/MiAssessment.Api/MiAssessment.Api.csproj`
- `src/MiAssessment.Core/MiAssessment.Core.csproj` → `src/MiAssessment.Core/MiAssessment.Core.csproj`
- `src/MiAssessment.Infrastructure/MiAssessment.Infrastructure.csproj` → `src/MiAssessment.Infrastructure/MiAssessment.Infrastructure.csproj`
- `src/MiAssessment.Model/MiAssessment.Model.csproj` → `src/MiAssessment.Model/MiAssessment.Model.csproj`
- `src/MiAssessment.Admin/MiAssessment.Admin.csproj` → `src/MiAssessment.Admin/MiAssessment.Admin.csproj`
- `src/MiAssessment.Admin.Business/MiAssessment.Admin.Business.csproj` → `src/MiAssessment.Admin.Business/MiAssessment.Admin.Business.csproj`
- `tests/MiAssessment.Tests/MiAssessment.Tests.csproj` → `tests/MiAssessment.Tests/MiAssessment.Tests.csproj`

#### Namespace Declarations (All .cs files)
Replace in all C# source files:
```csharp
// From:
namespace MiAssessment.Api.Controllers;
using MiAssessment.Core.Services;

// To:
namespace MiAssessment.Api.Controllers;
using MiAssessment.Core.Services;
```

#### Configuration Files
- `src/MiAssessment.Api/appsettings.json`
  - Connection strings
  - JWT settings
  - WeChat configuration
- `src/MiAssessment.Api/appsettings.Development.json`
- `src/MiAssessment.Admin/appsettings.json`

### Database Placeholders

| Placeholder | Description | Example |
|-------------|-------------|---------|
| `MiAssessment_Admin` | Admin database name | `MyApp_Admin` |
| `MiAssessment_Business` | Business database name | `MyApp_Business` |

### Configuration Placeholders (appsettings.json)

| Placeholder | Description | Example |
|-------------|-------------|---------|
| `{{DB_SERVER}}` | SQL Server 地址 | `localhost` |
| `{{DB_USER}}` | 数据库用户名 | `sa` |
| `{{DB_PASSWORD}}` | 数据库密码 | `YourPassword123` |
| `{{DB_NAME}}` | 业务数据库名 | `myapp_business` |
| `{{ADMIN_DB_NAME}}` | 管理后台数据库名 | `myapp_admin` |
| `{{REDIS_HOST}}` | Redis 地址 | `localhost` |
| `{{REDIS_PORT}}` | Redis 端口 | `6379` |
| `{{JWT_SECRET_AT_LEAST_32_CHARACTERS}}` | JWT 密钥 (至少32字符) | `MySecretKey123...` |
| `{{PROJECT_NAME}}` | 项目名称 | `MyApp` |
| `{{WECHAT_MCH_ID}}` | 微信支付商户号 | `1234567890` |
| `{{WECHAT_APP_ID}}` | 小程序 AppId | `wx1234567890abcdef` |
| `{{WECHAT_API_KEY}}` | 微信支付 API 密钥 | `your_api_key` |
| `{{WECHAT_NOTIFY_URL}}` | 支付回调地址 | `https://api.example.com/api/notify/wechat` |
| `{{API_BASE_URL}}` | API 基础地址 | `https://api.example.com` |
| `{{AMAP_API_KEY}}` | 高德地图 API Key | `your_amap_key` |

## Database Initialization

### Admin Database

The `scripts/init_admin_db.sql` script creates:

**Tables:**
- `departments` - Department hierarchy
- `admin_users` - Admin accounts
- `roles` - Role definitions
- `permissions` - Permission definitions
- `menus` - Menu configuration
- `admin_user_roles` - Admin-Role associations
- `role_menus` - Role-Menu associations
- `role_permissions` - Role-Permission associations
- `admin_user_menus` - User-specific menus
- `department_menus` - Department-Menu associations
- `operation_logs` - Operation audit logs
- `refresh_tokens` - Admin refresh tokens
- `admin_configs` - Admin configurations
- `dict_types` - Dictionary types
- `dict_items` - Dictionary items

**Default Data:**
- Default department: 总部 (HQ)
- Default roles: 超级管理员, 管理员
- Default admin user: `admin` / `admin123`
- Default permissions: System management, User management
- Default menus: System management tree
- Default dictionaries: user_status, gender, yes_no

### Business Database

The `scripts/init_business_db.sql` script creates:

**Tables:**
- `users` - User accounts (simplified)
- `user_details` - User extension fields
- `user_addresses` - Shipping addresses
- `user_refresh_tokens` - User refresh tokens
- `user_login_logs` - Login audit logs
- `payment_orders` - Generic payment orders
- `order_notifies` - Payment callback records
- `configs` - System configurations
- `pictures` - Image management
- `deliveries` - Delivery companies

**Default Data:**
- Default configs: wechat, wechat_pay, sms, system
- Default deliveries: SF, ZTO, YTO, YD, STO, JTSD, YZPY, JD, DBL

## Quick Start

### 1. Generate Project

Use the template generator script:

```powershell
./create-project.ps1 `
    -ProjectName "MyApp" `
    -AdminDbName "MyApp_Admin" `
    -BusinessDbName "MyApp_Business" `
    -SqlServerHost "localhost" `
    -SqlServerUser "sa" `
    -SqlServerPassword "YourPassword"
```

### 2. Configure Database

Update `appsettings.json` with your database connection strings:

```json
{
  "ConnectionStrings": {
    "AdminConnection": "Server=localhost;Database=MyApp_Admin;User Id=sa;Password=YourPassword;TrustServerCertificate=True",
    "DefaultConnection": "Server=localhost;Database=MyApp_Business;User Id=sa;Password=YourPassword;TrustServerCertificate=True"
  }
}
```

### 3. Initialize Databases

Run the initialization scripts:

```sql
-- Create Admin database
CREATE DATABASE [MyApp_Admin];
GO
-- Run init_admin_db.sql

-- Create Business database  
CREATE DATABASE [MyApp_Business];
GO
-- Run init_business_db.sql
```

### 4. Build and Run

```bash
cd server/MyApp
dotnet restore
dotnet build
dotnet run --project src/MyApp.Api
```

The API will be available at `http://localhost:5238`

### 5. Access Admin Panel

- URL: `http://localhost:5238/admin`
- Username: `admin`
- Password: `admin123`

## Extending the Template

### Adding Business Fields to User

Add fields to `user_details` table:

```sql
ALTER TABLE [dbo].[user_details]
ADD [Balance] DECIMAL(10,2) NOT NULL DEFAULT 0,
    [Points] INT NOT NULL DEFAULT 0,
    [Level] INT NOT NULL DEFAULT 1;
```

Update `UserDetail.cs` entity accordingly.

### Adding Payment Reward Handlers

Implement `IPaymentRewardHandler` interface:

```csharp
public class VipPurchaseRewardHandler : IPaymentRewardHandler
{
    public string OrderType => "vip_purchase";
    
    public async Task<RewardResult> ProcessRewardAsync(PaymentOrder order)
    {
        // Implement VIP activation logic
        return new RewardResult { Success = true, Message = "VIP activated" };
    }
}
```

Register in DI container:

```csharp
services.AddScoped<IPaymentRewardHandler, VipPurchaseRewardHandler>();
```

### Adding New Dictionary Types

Insert via SQL or Admin panel:

```sql
INSERT INTO [dict_types] ([code], [name], [source_type], [status])
VALUES ('order_status', N'订单状态', 1, 1);

INSERT INTO [dict_items] ([type_id], [label], [value], [css_class], [status], [sort])
VALUES 
    (@type_id, N'待支付', '0', 'warning', 1, 1),
    (@type_id, N'已支付', '1', 'success', 1, 2),
    (@type_id, N'已取消', '2', 'info', 1, 3);
```

## API Documentation

After starting the API, access Scalar documentation at:
- `http://localhost:5238/scalar/v1`

## Technology Stack

- **Framework**: ASP.NET Core (.NET 10)
- **ORM**: Entity Framework Core 8.0
- **Database**: SQL Server
- **Architecture**: Clean Architecture
- **DI Container**: Autofac
- **Authentication**: JWT Bearer
- **Logging**: Serilog
- **Object Mapping**: Mapster
- **API Documentation**: Scalar (OpenAPI)

## License

This template is provided as-is for internal use.