# t-twins

**Repository Path**: GhostMask/t-twins

## Basic Information

- **Project Name**: t-twins
- **Description**: 基础框架.net版本
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-28
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: t-twins

## README

# T-Twins

基于 .NET 8 的数字孪生平台后端框架，采用 SqlSugar ORM + MySQL。

Java 移植版本: [t-twins-j](https://gitee.com/GhostMask/t-twins-j)
前端项目: 见同级的 `t-twins-frontv`（Vue 3 + TypeScript + Element Plus）

## 技术栈

| 组件 | 技术 |
|------|------|
| 运行时 | .NET 8 |
| ORM | SqlSugar 5.1.4.x |
| 数据库 | MySQL 8.0 |
| 认证 | JWT Bearer（AES 密文比对）+ OAuth 2.0 + User-Agent Bypass |
| 缓存 | IMemoryCache（默认）/ StackExchange.Redis（可选）|
| 日志 | NLog |
| 验证码 | SkiaSharp / 内置 SVG 生成 |
| LDAP | Novell.Directory.Ldap |
| 密码哈希 | BCrypt.Net-Next（仅 OAuth client_secret） |
| 配置中心 | KeeperFile（独立微服务） |

> ⚠️ **安全提示**：用户密码采用 AES-CBC-256 可逆加密（非 hash），`/utils/aes-config` 等开发端点默认匿名暴露密钥；User-Agent Bypass（`CYQJ`）默认开启。**生产部署前务必阅读 [Docs/18-User-Agent跳过认证.md](./Docs/18-User-Agent跳过认证.md) 与 [Docs/36-全局测试计划.md §十](./Docs/36-全局测试计划.md) 关闭相关开关。**

## 解决方案结构

```
T-Twins.sln
├── Module-Common/        共享库：DTO、枚举、验证器、工具扩展、Options
│   ├── T.Twins.DTO
│   └── T.Twins.Extensions
├── Module-Base/          核心框架（端口 5001）
│   ├── T.Twins.Base.Bll      实体模型、JWT、缓存、调度、UserContext
│   ├── T.Twins.Base.Dal      数据访问：AuthService、OAuth、LDAP、各 XxDal
│   ├── T.Twins.Base.Web      控制器、中间件、鉴权属性、验证器、导出
│   └── T.Twins.Base.Host     启动入口（端口 5001）
├── Module-Twins/         数字孪生业务（端口 5002）
│   ├── T.Twins.Twins.Bll / Dal / Web / Host
├── Module-Dc/            低代码动态页面（端口 5003）
│   ├── T.Twins.Dc.Bll / Dal / Web / Host
├── Module-KeeperFile/    配置中心微服务（端口 5034）
│   └── T.Twins.KeeperFile.Service
└── tools/                代码生成与工具
    ├── TwinsDcGenerator/     DC 代码生成器（Core + Desktop WPF）
    └── Knife4jExtractor/
```

每个业务模块统一采用 **Bll / Dal / Web / Host 四层分包**，由 `BaseStartup` 通过程序集扫描自动注册。

## 快速开始

### 1. 准备数据库

在 MySQL 中创建 `twins` 库并执行建表脚本：

```bash
mysql -u root -p < Scripts/init-all-tables.sql
mysql -u root -p twins < Docs/SeedData.sql
```

### 2. 配置连接

修改 `Module-Base/Host/App_Data/config/appsettings.json` 中的数据库连接字符串与 JWT 密钥。

> `Jwt:Secret` 必填（缺失会抛异常）；`Auth:AesKeyBase64` / `Auth:AesIVBase64` 控制密码加密。

### 3. 启动

```bash
dotnet run --project Module-Base/Host
```

- Base.Host: http://localhost:5001
- Twins.Host: http://localhost:5002
- Dc.Host: http://localhost:5003
- KeeperFile: http://localhost:5034

种子账号见 `Docs/SeedData.sql`（超管 admin）。首次启动若库中无超管，会自动创建并输出密码到控制台。

### 4. Docker 部署

详见 [Docs/17-Docker部署.md](./Docs/17-Docker部署.md) 与 [Docs/26-本地打包部署发布手册.md](./Docs/26-本地打包部署发布手册.md)。

## 功能概览

- **认证**：JWT（8h Access + 7d Refresh，refresh 不轮换、存 IMemoryCache）+ OAuth 2.0（client_credentials / authorization_code + PKCE / refresh_token，BCrypt 校验）+ 可选 LDAP/AD 登录 + 图形验证码（SVG）
- **权限**：RBAC（用户-角色-权限），支持 Menu/Button/API 三种权限类型；`[PermissionAuthorize]` 按**动作推断后缀**鉴权；角色组（RoleGroup）、权限端点（PermissionEndpoint）、数据权限（DataScope，字段已建、查询过滤尚未落地）
- **通用 CRUD**：`BaseController<T>` 提供 9 个标准 POST 端点（getcount/getpagedata/getdata/top/getbyid/edit/del/delbyconditions/export）
- **动态条件引擎**：`ConditionsModel` 支持 AND/OR 分组、嵌套子条件、14 种操作符
- **低代码模块（Module-Dc）**：后台配置页面/字段/按钮/资源，运行时引擎读配置对任意业务表动态 SQL；配套 TwinsDcGenerator 代码生成器
- **日志三件套**：审计日志（中间件全量拦截 + 脱敏）/ 登录日志（仅 Login 写入）/ 操作日志（配置规则驱动，可读描述）
- **定时任务**：Cron 调度 HTTP 回调，支持启停/暂停/手动触发/重试/执行统计
- **文件管理**：上传/批量上传/下载/按业务关联，扩展名白名单校验
- **字典管理**：系统字典，查询接口全 `[AllowAnonymous]`
- **系统配置**：`sys_config` 表运行时配置（与 appsettings 三级优先级）
- **配置中心**：KeeperFile 独立微服务，统一分发 appsettings 与 NLog 模板

## 模块说明

| 模块 | 端口 | 说明 |
|------|------|------|
| Module-Base | 5001 | 核心：认证、用户、角色、角色组、权限、权限端点、部门、数据权限、字典、文件、系统配置、审计/登录/操作日志、定时任务、OAuth、LDAP、验证码 |
| Module-Twins | 5002 | 数字孪生业务（TwinsModelConfig 配置存储） |
| Module-Dc | 5003 | 低代码：配置驱动的动态 CRUD 页面 + 运行时引擎 |
| Module-KeeperFile | 5034 | 配置中心：统一配置分发 |

## 数据库表

共 **28 张表**（详见 [Docs/15-数据库表结构.md](./Docs/15-数据库表结构.md)）：

- **Base · 用户/角色/权限（9）**：`bm_user`、`bm_role`、`bm_permission`、`bm_permission_endpoint`、`bm_user_role`、`bm_role_permission`、`bm_role_group`、`bm_role_dept_scope`、`bm_dept`
- **Base · 日志（4）**：`bm_audit_log`、`bm_login_log`、`bm_operation_log`、`bm_operation_log_config`
- **Base · 定时任务（4）**：`bm_scheduled_task`、`bm_scheduled_jobs`、`bm_scheduled_log`、`bm_job_execution_logs`
- **Base · OAuth（3）**：`bm_oauth_client`、`bm_oauth_token`、`bm_oauth_authorization_code`
- **Base · 系统（3）**：`sys_dic`、`sys_file`、`sys_config`
- **Module-Dc（4）**：`dc_page_config`、`dc_field_config`、`dc_button_config`、`dc_resource_config`
- **Module-Twins（1）**：`twins_model_config`

## 文档

完整文档位于 [`Docs/`](./Docs/00-Index.md) 目录（共 32 篇编号文档），快速入口：

- 入门：[01-框架概述](./Docs/01-框架概述.md) / [02-快速开始](./Docs/02-快速开始.md)
- 权限：[08-用户权限系统](./Docs/08-用户权限系统.md) / [21-统一权限验证](./Docs/21-统一权限验证使用指南.md) / [31-角色组与数据权限](./Docs/31-角色组与数据权限.md)
- 认证：[12-跨模块认证](./Docs/12-跨模块认证.md) / [19-OAuth2.0集成](./Docs/19-OAuth2.0集成指南.md) / [33-验证码与LDAP](./Docs/33-验证码与LDAP登录.md)
- 低代码：[24-低代码模块(DC)](./Docs/24-低代码模块(DC).md) / [34-TwinsDcGenerator](./Docs/34-TwinsDcGenerator代码生成器.md)
- 日志：[25-日志三件套](./Docs/25-日志三件套.md)
- 数据库：[15-数据库表结构](./Docs/15-数据库表结构.md)
- 测试：[36-全局测试计划](./Docs/36-全局测试计划.md)（133 用例）
- 部署：[17-Docker部署](./Docs/17-Docker部署.md) / [26-本地打包部署](./Docs/26-本地打包部署发布手册.md)