296 lines
8.4 KiB
Markdown
296 lines
8.4 KiB
Markdown
# 学业邑规划 (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)
|