mi-assessment/server/MiAssessment/TEMPLATE_README.md

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:

// 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:

./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:

{
  "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:

-- 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

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:

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:

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:

services.AddScoped<IPaymentRewardHandler, VipPurchaseRewardHandler>();

Adding New Dictionary Types

Insert via SQL or Admin panel:

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.