# DevExpress252-2026

**Repository Path**: null_347_6860/dev-express252-2026

## Basic Information

- **Project Name**: DevExpress252-2026
- **Description**: 学习DevExpressXaf25.2项目
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-16
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Q2.Net - 基于 DevExpress XAF 25.2.5 的医疗信息系统框架

## 项目简介

Q2.Net 是庆阳市第二人民医院（庆阳Q2HIS）的企业级医疗信息系统框架，基于 DevExpress XAF (eXpress Application Framework) 25.2.5 构建。项目采用多模块化架构设计，支持 Blazor Server 和 Windows Forms 两种客户端界面，集成医保API对接能力，提供完整的用户认证、角色管理和权限控制系统。

## 技术栈

| 技术 | 版本/说明 |
|------|-----------|
| .NET | 10.0 |
| DevExpress XAF | 25.2.5 |
| ORM | XPO (eXtreme Persistent Objects) |
| Web 界面 | Blazor Server |
| 桌面界面 | Windows Forms |
| 数据库 | SQL Server (Microsoft.Data.SqlClient 7.0) |
| 日志 | NLog 6.1 |
| 认证 | JWT (System.IdentityModel.Tokens.Jwt 8.17) |
| Web API | Swagger (Swashbuckle.AspNetCore) + OData |
| 解决方案格式 | .slnx (新版 Visual Studio XML 格式) |

## 项目架构

```
Q2.Net/
├── Q2.Framework.Module/                   # 框架基础模块
│   ├── Q2.Base.Module/                    # 基础模块
│   │   ├── BusinessObjects/BaseImpl/      # 业务对象基类 (Q2BaseObject, Q2XPBaseObject等)
│   │   ├── Extensions/                    # 扩展方法 (JSON序列化、DES/MD5加密)
│   │   └── BaseServices/Logging/          # NLog日志服务 (INLoggingService)
│   │
│   ├── Q2.DataItem.Module/                # 数据字典模块
│   │   └── BusinessObjects/               # 数据项实体 (DataItemEntity, DataItemDetailEntity)
│   │
│   ├── Q2.MedicareApi.Module/             # 医保API对接模块
│   │   ├── BusinessObjects/Entitys/       # 医保业务对象 (数据项、日志、目录、下载历史)
│   │   ├── BusinessObjects/NewGsYiBao.Core/  # 100+ 医保接口DTO (1101~9102交易码)
│   │   └── Services/                      # 医保服务 (API调用、字典、下载、缓存)
│   │
│   └── Q2.Net.Module/                     # 核心整合模块 (项目名: Q2.NetCore.Module)
│       ├── BusinessObjects/               # ApplicationUser, Q_Role, 权限对象
│       ├── BusinessObjects/Q2_Base/       # Q_User, Q_Role, 过滤条件
│       ├── PermissionPolicy/              # 自定义权限编辑器
│       └── Controllers/                   # 共享控制器
│
├── Q2.Application.UI/                     # 应用界面层
│   ├── Qys2y.Net.Blazor.Server/           # Blazor Server Web应用
│   │   ├── Controllers/                   # API控制器 (认证等)
│   │   ├── Pages/                         # Razor页面
│   │   └── wwwroot/                       # 静态资源
│   │
│   └── Qys2y.Net.Win/                     # Windows Forms 桌面应用
│       └── Images/                        # 图片资源
│
├── EasyXaf.DynamicForm/                   # 动态表单模块 (平台无关)
├── EasyXaf.DynamicForm.Blazor/            # 动态表单 Blazor 渲染模块
│
├── Directory.packages.props               # 集中包版本管理
├── Sql/                                   # SQL脚本
└── Q2.Net.slnx                            # 解决方案文件
```

## 核心特性

### 基础模块 (Q2.Base.Module)

提供所有模块的底层基础设施：

| 文件/类 | 说明 |
|---------|------|
| `Q2BaseObject` | 业务对象基类，支持 GUID v7 主键自动生成，提供 OnSaving/OnLoaded 等 XAF 生命周期钩子 |
| `Q2XPBaseObject` | XPO 持久化对象基类 |
| `Q2BaseCommonObject` | 扩展通用基类，内置常用业务字段 |
| `INLoggingService` | 日志服务接口 |
| `NLogLoggingService` | 基于 NLog 的日志实现 |
| `DESEncrypt` | DES 加密工具类 |
| `Md5Helper` | MD5 哈希工具类 |
| `Extensions.Json` | JSON 序列化/反序列化扩展方法 |

### 数据字典模块 (Q2.DataItem.Module)

管理系统数据字典和基础数据：

| 类 | 说明 |
|----|------|
| `DataItemEntity` | 数据项/字典类别实体 |
| `DataItemDetailEntity` | 数据项明细实体 |

### 医保API模块 (Q2.MedicareApi.Module)

完整的医保网关对接能力，支持 100+ 交易码：

**核心服务：**

| 服务/类 | 说明 |
|---------|------|
| `MedicareApiService<TInput, TOutput>` | 医保API通用泛型服务，封装HTTP调用 |
| `MedicareDictService` | 医保字典数据服务 |
| `DownloadDataService` | 医保文件下载服务（支持大文件分片下载） |
| `MedicareDataCache` | 医保数据本地缓存服务 |
| `MedicareInitInfo` | 医保配置初始化数据 |

**业务实体：**

| 类 | 说明 |
|----|------|
| `Q_MedicareDataitem` | 医保数据项实体 |
| `Q_Medicare_Log` | 医保API调用日志 |
| `Q_Medicare_dir` | 医保目录数据 |
| `Q_MedicareDownload_History` | 下载历史记录 |
| `DepTypeTest` | 科室类型测试 |

**支持的医保交易码：**

| 交易码 | 功能 | 交易码 | 功能 |
|--------|------|--------|------|
| 1101 | 人员基本信息获取 | 1301/1307/1309~1318 | 药品/诊疗/耗材目录查询 |
| 1201 | 门诊挂号 | 1901 | 诊断信息 |
| 3101~3103 | 门诊结算 | 3201~3205 | 住院登记、结算 |
| 3260/3261 | 住院费用 | 3301/3302 | 住院结算汇总 |
| 3501~3570 | 其他住院业务 | 3605 | DRG分组 |
| 4103 | DRG费用 | 5201~5206 | 费用上传 |
| 5301~5304 | 费用查询 | 9001/9002 | 系统接口 |
| 9101/9102 | 文件下载 | | |

### 动态表单模块 (EasyXaf.DynamicForm)

自定义 XAF 动态表单扩展，支持运行时动态定义表单结构：

| 项目 | 说明 |
|------|------|
| `EasyXaf.DynamicForm` | 平台无关的动态表单核心（CriteriaConverter, ExpandoObject转换等） |
| `EasyXaf.DynamicForm.Blazor` | Blazor 端的动态表单渲染器（Razor Components） |

### 安全认证系统

- **JWT 令牌认证** - 基于标准的 JWT 认证机制，支持令牌生成与验证
- **用户管理** - ApplicationUser 实现 XAF 安全接口，支持完整用户生命周期
- **角色权限** - Q_Role / Q_RoleBase 实现细粒度权限控制，支持以下权限类型：
  - Type 权限（对象类型级别）
  - Object 权限（对象实例级别）
  - Member 权限（字段级别读写）
  - Action 权限（UI 操作控制）
  - Navigation 权限（导航菜单控制）
- **权限策略** - 支持 AllowSelected（仅允许已配置权限）和 AllowEverything（管理员全权限）两种模式

### 多客户端支持

- **Blazor Server** - 现代化 Web 界面，集成 Swagger API 文档和 OData 端点
- **Windows Forms** - 传统桌面应用，适合医院内部局域网使用

## 快速开始

### 环境要求

- Visual Studio 2022 或更高版本（需支持 .slnx 格式）
- .NET 10.0 SDK
- SQL Server 2019 或更高版本
- DevExpress Universal 订阅（版本 25.2.5）

### 安装步骤

**1. 克隆项目**

```bash
git clone https://gitee.com/null_347_6860/dev-express252-2026.git
```

**2. 还原 NuGet 包**

```bash
dotnet restore Q2.Net.slnx
```

**3. 配置数据库连接**

编辑 `Q2.Net/Q2.Application.UI/Qys2y.Net.Blazor.Server/appsettings.json`：

```json
{
  "ConnectionStrings": {
    "ConnectionString": "Server=your_server;Database=Q2NetDB;User Id=sa;Password=your_password;"
  }
}
```

WinForms 应用还需编辑 `Q2.Net/Q2.Application.UI/Qys2y.Net.Win/App.config` 中的连接字符串。

**4. 运行应用程序**

Blazor Server Web应用：
```bash
cd Q2.Net/Q2.Application.UI/Qys2y.Net.Blazor.Server
dotnet run
```

Windows Forms 桌面应用：
```bash
cd Q2.Net/Q2.Application.UI/Qys2y.Net.Win
dotnet run
```

### 数据库更新

应用程序支持命令行自动更新数据库架构：

```bash
# WinForms
Q2.Net.Win.exe --updateDatabase

# Blazor Server
dotnet run --updateDatabase

# 可选参数
# --forceUpdate  强制更新数据库
# --silent       静默模式，无需用户交互
```

### 默认账户

首次运行将自动创建管理员账户：

- **用户名**：`Admin`
- **密码**：`（空密码，首次登录需设置）`

## 构建配置

项目支持三种构建配置，所有项目均包含：

| 配置 | 说明 |
|------|------|
| Debug | 调试版本，包含完整调试信息 |
| Release | 发布版本，启用代码优化 |
| EasyTest | XAF 内置测试框架模式 |

## 配置说明

### JWT 配置

在 `appsettings.json` 中配置：

```json
{
  "Jwt": {
    "SecretKey": "your-secret-key",
    "Issuer": "q2.net",
    "Audience": "q2.net",
    "ExpirationMinutes": 60
  }
}
```

### 医保API配置

医保API模块需要配置医保网关参数：

```json
{
  "MedicareApi": {
    "MedicareConfig": "加密的医保配置信息"
  }
}
```

### NLog 日志配置

日志配置文件位于各模块的 `XmlConfig/NLog.config`，应用程序启动时会自动加载。支持文件日志、控制台日志等多种输出目标。

## 开发指南

### 添加新业务对象

1. 在对应模块的 `BusinessObjects` 目录中创建实体类
2. 继承 `Q2BaseObject` 或 `XPCustomObject`
3. 定义属性和关联关系
4. 运行应用程序，自动更新数据库架构

```csharp
using DevExpress.Xpo;
using Q2.Base.BaseImpl;

public class MyBusinessObject : Q2BaseObject
{
    public MyBusinessObject(Session session) : base(session) { }

    private string _Name;
    public string Name
    {
        get => _Name;
        set => SetPropertyValue(nameof(Name), ref _Name, value);
    }
}
```

### 添加医保接口

参考 `Q2.MedicareApi.Module/BusinessObjects/NewGsYiBao.Core/` 目录下的现有实现：

1. 创建输入实体类（继承 `Q2_BaseInput`）
2. 创建输出实体类（继承 `Q2_BaseOutput`）
3. 使用 `MedicareApiService<TInput, TOutput>` 泛型服务调用接口

### 创建新模块

标准 XAF 模块创建流程：

1. 创建 .NET 10.0 类库项目
2. 在 `Directory.packages.props` 中添加所需 NuGet 包版本
3. 在项目 `.csproj` 中引用包
4. 创建继承自 `ModuleBase` 的模块类
5. 在 `Q2.NetCore.Module` 中添加项目引用和 `RequiredModuleTypes`

### 项目命名约定

- 物理目录名：`Qys2y.Net.*`（早期命名）
- 程序集/项目名：`Q2.Net.*`（当前统一命名）
- 模块代码命名空间：`Q2.*`

## 主要依赖包

| 包名 | 版本 | 用途 |
|------|------|------|
| DevExpress.ExpressApp | 25.2.5 | XAF 核心框架 |
| DevExpress.ExpressApp.Xpo | 25.2.5 | XPO ORM 支持 |
| DevExpress.ExpressApp.Security.Xpo | 25.2.5 | 安全认证模块 |
| DevExpress.ExpressApp.Blazor | 25.2.5 | Blazor 界面支持 |
| DevExpress.ExpressApp.Win | 25.2.5 | WinForms 界面支持 |
| DevExpress.ExpressApp.Validation | 25.2.5 | 数据验证 |
| DevExpress.ExpressApp.ConditionalAppearance | 25.2.5 | 条件外观 |
| Microsoft.Data.SqlClient | 7.0.0 | SQL Server 数据库连接 |
| NLog | 6.1.2 | 日志记录 |
| Newtonsoft.Json | 13.0.4 | JSON 处理 |
| System.IdentityModel.Tokens.Jwt | 8.17.0 | JWT 令牌处理 |
| NPinyin.Core | 3.0.0 | 汉字转拼音 |
| Azure.Identity | 1.20.0 | Azure 身份认证 |
| Swashbuckle.AspNetCore | 6.9.0 | Swagger API 文档 |
| SharpZipLib | 1.4.2 | 压缩文件处理 |
| Microsoft.Extensions.Http | 10.0.6 | HTTP 客户端（医保API调用） |
| Microsoft.Extensions.Http.Polly | 10.0.6 | HTTP 弹性策略（重试/熔断） |

## API 参考

### 认证接口

```
POST /api/Authentication/Authenticate
Content-Type: application/json

{
  "userName": "Admin",
  "password": "your_password"
}
```

**响应示例**：

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600
}
```

### Swagger 文档

启动 Blazor Server 应用后，访问 `/swagger` 路径查看完整 API 文档（标题："庆阳市第二人民医院 Api"）。

## 许可证

本项目使用 DevExpress 25.2.5 组件，需要有效的 DevExpress 许可证。项目源码许可证见 [LICENSE.txt](LICENSE.txt)。

## 版本信息

- 版本号：1.0.*
- 目标框架：.NET 10.0
- DevExpress 版本：25.2.5
- 解决方案格式：.slnx

## 贡献指南

欢迎提交 Issue 和 Pull Request。

## 技术支持

如有问题，请通过 Gitee 平台联系项目维护者。