# 学业邑规划 (MiAssessment) - 后端服务

基于 .NET 10 的多元智能测评小程序后端服务，采用清洁架构设计，提供小程序 API 和后台管理系统。

## 技术栈

| 组件 | 技术 |
|------|------|
| 框架 | ASP.NET Core (.NET 10) |
| ORM | Entity Framework Core |
| 数据库 | SQL Server 2022 |
| 缓存 | Redis |
| 认证 | JWT Bearer + Refresh Token |
| 日志 | Serilog |
| 对象映射 | Mapster |
| API 文档 | Scalar (OpenAPI) |
| DI 容器 | Autofac |

## 功能特性

- **用户认证**: 微信小程序登录、JWT 认证、Token 刷新
- **微信集成**: 小程序登录、手机号获取
- **微信支付**: V3 支付、回调验签、退款
- **用户管理**: 用户信息、登录日志、地址管理
- **测评系统**: 题库管理、测评记录、报告生成
- **订单系统**: 支付订单、分销佣金
- **后台管理**: 完整的 RBAC 权限控制
- **字典管理**: 静态数据 + 动态 SQL 查询

## 项目结构

```
server/MiAssessment/
├── MiAssessment.sln                    # 解决方案文件
├── scripts/                            # 数据库脚本
│   ├── init_admin_db.sql               # 后台管理数据库初始化
│   ├── init_business_db.sql            # 业务数据库初始化
│   ├── init_business_dict.sql          # 业务字典数据
│   └── seed_business_permissions.sql   # 业务权限种子数据
│
├── src/
│   ├── MiAssessment.Api/               # 小程序 API 接口层
│   │   ├── Controllers/                # API 控制器
│   │   ├── Filters/                    # 过滤器
│   │   └── Program.cs                  # 程序入口
│   │
│   ├── MiAssessment.Admin/             # 后台管理系统
│   │   ├── admin-web/                  # 前端代码 (Vue 3 + TypeScript)
│   │   ├── Controllers/                # 管理 API 控制器
│   │   ├── Services/                   # 管理服务
│   │   ├── Entities/                   # 管理实体
│   │   ├── Data/                       # 数据库上下文
│   │   ├── Filters/                    # 权限过滤器
│   │   └── Models/                     # DTO 模型
│   │
│   ├── MiAssessment.Admin.Business/    # 后台业务模块 (主要开发区域)
│   │   ├── Controllers/                # 业务管理控制器
│   │   ├── Services/                   # 业务服务
│   │   │   └── Interfaces/             # 服务接口
│   │   ├── Entities/                   # 业务实体
│   │   ├── Models/                     # 请求/响应模型
│   │   ├── Data/                       # 业务数据库上下文
│   │   └── Attributes/                 # 自定义特性
│   │
│   ├── MiAssessment.Core/              # 核心业务逻辑层
│   │   ├── Interfaces/                 # 服务接口
│   │   ├── Services/                   # 服务实现
│   │   ├── Mappings/                   # 对象映射配置
│   │   └── Constants/                  # 常量定义
│   │
│   ├── MiAssessment.Infrastructure/    # 基础设施层
│   │   ├── Cache/                      # Redis 缓存
│   │   ├── External/                   # 外部服务集成
│   │   └── Modules/                    # 功能模块
│   │
│   └── MiAssessment.Model/             # 数据模型层
│       ├── Entities/                   # 数据库实体
│       ├── Models/                     # DTO 模型
│       ├── Data/                       # 数据库上下文
│       └── Base/                       # 基类
│
└── tests/
    └── MiAssessment.Tests/             # 单元测试 & 属性测试
```

## 后台管理前端

前端代码位于 `src/MiAssessment.Admin/admin-web/`，技术栈：

- **框架**: Vue 3 + TypeScript
- **构建工具**: Vite
- **UI 组件**: Element Plus (或其他)
- **状态管理**: Pinia
- **HTTP 客户端**: Axios

```bash
# 进入前端目录
cd src/MiAssessment.Admin/admin-web

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建生产版本
npm run build
```

## 快速开始

### 1. 环境要求

- .NET 10 SDK
- SQL Server 2022
- Redis
- Node.js 18+ (前端开发)

### 2. 配置数据库

修改 `appsettings.json` 中的连接字符串：

```json
{
  "ConnectionStrings": {
    "AdminConnection": "Server=localhost;Database=MiAssessment_Admin;User Id=sa;Password=YourPassword;TrustServerCertificate=True",
    "DefaultConnection": "Server=localhost;Database=MiAssessment_Business;User Id=sa;Password=YourPassword;TrustServerCertificate=True"
  },
  "Redis": {
    "Host": "localhost",
    "Port": 6379
  }
}
```

### 3. 初始化数据库

```sql
-- 创建管理后台数据库
CREATE DATABASE [MiAssessment_Admin];
GO
-- 执行 scripts/init_admin_db.sql

-- 创建业务数据库
CREATE DATABASE [MiAssessment_Business];
GO
-- 执行 scripts/init_business_db.sql
-- 执行 scripts/init_business_dict.sql
-- 执行 scripts/seed_business_permissions.sql
```

### 4. 启动服务

```bash
# 还原依赖
dotnet restore

# 构建项目
dotnet build

# 启动小程序 API (端口 5238)
dotnet run --project src/MiAssessment.Api

# 启动后台管理 API (端口 5239)
dotnet run --project src/MiAssessment.Admin
```

### 5. 访问服务

| 服务 | 地址 |
|------|------|
| 小程序 API | http://localhost:5238 |
| 小程序 API 文档 | http://localhost:5238/scalar/v1 |
| 后台管理 API | http://localhost:5239 |
| 后台管理前端 | http://localhost:5173 (开发模式) |

### 6. 默认管理员账号

- 用户名: `admin`
- 密码: `admin123`

## 数据库说明

### 管理后台数据库 (MiAssessment_Admin)

| 表名 | 说明 |
|------|------|
| departments | 部门层级 |
| admin_users | 管理员账号 |
| roles | 角色定义 |
| permissions | 权限定义 |
| menus | 菜单配置 |
| admin_user_roles | 管理员-角色关联 |
| role_menus | 角色-菜单关联 |
| role_permissions | 角色-权限关联 |
| operation_logs | 操作审计日志 |
| refresh_tokens | 刷新令牌 |
| dict_types | 字典类型 |
| dict_items | 字典项 |

### 业务数据库 (MiAssessment_Business)

| 表名 | 说明 |
|------|------|
| users | 用户账号 |
| user_details | 用户扩展信息 |
| user_addresses | 收货地址 |
| user_login_logs | 登录日志 |
| payment_orders | 支付订单 |
| order_notifies | 支付回调记录 |
| configs | 系统配置 |
| assessment_* | 测评相关表 |

## 配置项说明

| 配置项 | 说明 |
|--------|------|
| `ConnectionStrings:AdminConnection` | 管理后台数据库连接 |
| `ConnectionStrings:DefaultConnection` | 业务数据库连接 |
| `Redis:Host` | Redis 服务器地址 |
| `Redis:Port` | Redis 端口 |
| `Jwt:Secret` | JWT 密钥 (至少32字符) |
| `Jwt:Issuer` | JWT 签发者 |
| `Jwt:Audience` | JWT 受众 |
| `WeChat:AppId` | 小程序 AppId |
| `WeChat:AppSecret` | 小程序 AppSecret |
| `WeChatPay:MchId` | 微信支付商户号 |
| `WeChatPay:ApiKey` | 微信支付 API 密钥 |
| `WeChatPay:NotifyUrl` | 支付回调地址 |

## API 接口规范

### 路由格式

```
小程序 API: /api/{module}/{action}
后台管理 API: /api/admin/{module}/{action}
```

### 请求方式

- **GET**: 查询操作，参数通过 Query String 传递
- **POST**: 新增、修改、删除操作，参数通过 JSON Body 传递

### 响应格式

```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

### 分页响应

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  }
}
```

## Docker 部署

```bash
# 构建小程序 API 镜像
docker build -t miassessment-api -f src/MiAssessment.Api/Dockerfile .

# 构建后台管理 API 镜像
docker build -t miassessment-admin -f src/MiAssessment.Admin/Dockerfile .

# 构建后台管理前端镜像
docker build -t miassessment-admin-web -f src/MiAssessment.Admin/admin-web/Dockerfile src/MiAssessment.Admin/admin-web
```

## 开发规范

详细开发规范请参考 `docs/开发规范/` 目录下的文档：

- 编程规约 (命名风格、代码风格、注释规约)
- 异常日志 (日志规约、异常处理)

## 相关文档

- [需求文档](../docs/需求文档.md)
- [数据库设计文档](../docs/数据库设计文档.md)
- [开发文档](../docs/开发文档.md)