来源：https://basicapp.docs.xihanfun.com/why

# 为什么选择曦寒

完整能力清单在 [功能清单](./features)，这一页不重复。它只回答三个问题：

1. 它究竟替我省掉什么？
2. 我这个项目适合拿它当起点吗？
3. 它和别的中后台方案有什么不同？

中后台的选型成本主要不在「能不能跑起来」，而在**三年后还改不改得动**。所以这一页会把代价和亮点写在一起。

## 30 秒结论

::: tip 适合这样的项目
- **企业内部系统 / 行业业务系统 / B 端 SaaS**：用户有组织归属，权限要按人按数据切
- **需要多租户**：一套代码服务多个客户，且要能按版本卖不同的功能包
- **有合规与审计要求**：谁在什么时候改了哪条数据、动了谁的权限，都要留痕可查
- **.NET 后端 + Vue 前端**的团队，希望前后端两侧都有现成规范可循
:::

::: warning 这些情况建议先别选
- **面向 C 端的门户 / 交易 / 高并发系统**：它是中后台内核，设计目标不是极限吞吐
- **被锁在旧版 .NET**，或团队已深度绑定 EF Core：底座是当前 .NET 版本 + SqlSugar
- **前端团队是 React 技术栈**：前端是 Vue，迁移等于重写
- **只需要一个「有登录和菜单」的小后台**：权限、租户、审计这套模型对小系统是过度设计
:::

## 一、它替你省掉的那几个月

每个中后台项目开工时都要重做一遍下面这些东西。它们不产生业务价值，但每一样做不好都会在半年后变成事故：

| 你本来要写 | 它已经内置 |
| --- | --- |
| 登录、令牌刷新、多端会话、找回密码 | [JWT 双令牌](./backend/authentication)、账号密码 / 邮箱短信验证码 / OAuth2 / 2FA、会话管理 |
| 角色菜单权限，然后被业务追问「他只能看自己部门的」 | [RBAC](./backend/permission) + 数据范围 + 字段级脱敏（数据范围目前接入用户列表） |
| 组织架构，然后发现部门树的上下级查询很慢 | [部门闭包表](./backend/organization) + 岗位 + 用户多部门归属 |
| 多租户，然后在每个查询里手动加 `where tenant_id =` | [字段级隔离](./backend/multi-tenancy)内建于数据层，写路径有越权写守卫 |
| 操作日志，然后发现密码和令牌被明文记进了库 | [七类审计日志](./backend/logging)，落库前自动脱敏 |
| 增删改查页面，一张表写一遍 | [代码生成](./backend/code-generation)：实体 → DTO → API → 前端页一键产出 |
| 站内信、邮件、短信、群机器人各写一套 | [消息中心](./backend/messaging) 四渠道扇出 + 模板渲染 + SignalR 实时推送 |

内置 **89 张表**的数据模型与 **50 多个后台页面**，是这些能力落地后的实际体量。

## 二、五个真正拉开差距的地方

「有这个功能」和「这个功能经得起用」是两件事。下面五点是它与常见后台模板的实质差异。

### 1. 权限不止「角色—菜单」两层

大多数后台模板的权限模型到「角色绑菜单、菜单绑按钮」为止。业务一追问「他只能看本部门的人」「客服不能看全手机号」「出纳和会计不能是同一个人」，就得改代码。

曦寒在权限码之外又建了三个维度，再加三套治理机制。各维度的落地程度不同，下表按当前实现写：

| 维度 | 回答的问题 | 当前落地 |
| --- | --- | --- |
| 权限码（如 `saas:user:read`） | 你能不能做这个操作 | 每次请求实时查授权快照：角色继承、用户直授、委托与租户版本白名单合并后判定 |
| 数据范围（本人 / 本部门 / 本部门及下级 / 全部 / 自定义部门） | 这个操作能作用到哪些数据 | 用户列表与用户导出按范围收窄；其它列表尚未接入 |
| ABAC 属性条件 | 授权在满足哪些 `subject.` / `resource.` / `environment.` 属性时才成立 | 角色授权与用户直授都可挂条件，每次鉴权按当前请求求值；全部条件可盘点，某人某权限可按模拟的时间、IP 试算 |
| 字段级脱敏 | 同一条数据里，哪些列你看得见明文 | 服务端统一脱敏，读取、导出、排序过滤与写入校验同一口径 |

- **约束规则引擎**：可维护职责分离、互斥、基数、先决条件、时间、位置等规则；当前执行的是静态职责分离（SSD），在分配角色、调整角色继承、审批通过角色申请时拦截互斥角色组合，「拒绝」与「需审批」都直接阻断，「警告」与「仅记录」放行并写日志
- **权限委托**：委托人 → 被委托人 → 权限范围 → 生效与到期时间窗，可随时撤销，全程留痕
- **访问策略**：不看授权，按 IP、地区、时段、用户、角色、接口等条件整体放行、拒绝或只记录请求，超管同样受约束；新建一律只记录，启用拦截前先拿当前请求试一次，不会把自己锁在外面；登录失败过多的 IP 可自动封禁

> 完整模型见 [权限模型](./backend/permission) 与 [审批与约束](./backend/approval)。

### 2. 多租户是内建维度，不是补丁

多租户如果做成「在业务代码里记得加过滤条件」，那么漏一处就是数据泄露。这里它落在数据层：租户过滤由框架统一施加，全局数据用 `TenantId=0` 约定，写路径另有守卫防止租户态误改全局行。

配套的还有商业化需要的那部分：租户版本（Edition）以权限白名单在运行时门控功能，开通时一站式建管理员与授权，降级自动回收越权授权。超级管理员可在平台态切入任意租户代为运维。

> 见 [多租户与版本](./backend/multi-tenancy)。

### 3. 菜单、路由、权限码只有一份真源

后台系统最常见的腐化点，是菜单在数据库里、路由在前端代码里、权限码在第三个地方，三份逐渐对不上。

这里后端的 `PageRegistry` 统一登记页面码、路由路径、前端组件路径、权限码与国际化键，菜单种子据此同步；前端按后端下发的结果生成路由。**新增一个页面只在一处登记**，前端不再维护第二份清单。

> 见 [菜单与路由](./frontend/routing)。

### 4. 列表页由配置生成，且三重感知

中后台八成的页面是「搜索 + 表格 + 导出」。这里它们由 Schema 配置生成，内置列设置、密度切换、高级搜索（时间区间、枚举多选）、个人视图保存、树形模式与列宽拖拽。

关键在于它对三件事有感知：**权限**（页面、字段、操作三级按权限码过滤，字段级脱敏）、**租户**、**个人偏好**（列设置与搜索条件同步到后端，换台电脑还在）。

> 见 [Schema 驱动页面](./frontend/schema-page)。

### 5. 底座可以单独带走

它的后端建立在 [XiHan.Framework](https://framework.docs.xihanfun.com/) 之上，而框架是 **66 个可独立引用的 NuGet 包**，本身就是公开发布的产品。

这意味着两个方向都通：你可以拿整套 BasicApp 起步，也可以只借走框架的某几个模块用在自己的项目里。BasicApp 使用的全部是框架公开的接口，**没有内部特权 API**——所以「先用模板上线，之后逐步换成自己的实现」这条路是通的，不需要换底座。

## 三、中后台方案的四条路线

同类方案不在一个平面上，而是四条路线。下面只描述路线特征，不做优劣评判——**很多时候「不选曦寒」才是对的**。

| 路线 | 代表 | 你得到什么 | 你付出什么 | 什么时候选它 |
| --- | --- | --- | --- | --- |
| **A. 从零自建** | ASP.NET Core + Vue + 自选组件 | 完全贴合业务，没有多余抽象 | 身份、权限、租户、审计要自己写并维护多年 | 系统形态特殊，且团队有稳定架构能力 |
| **B. 商业中后台 / 低代码平台** | 各类商业 aPaaS 与低代码平台 | 有 SLA、有实施支持、非开发者也能配置 | 授权费用、平台绑定，深度定制受平台能力边界限制 | 需求以配置为主，且预算与合规要求指向商业产品 |
| **C. 开源后台管理模板** | YuebonCore 等 | 开箱就是一套完整后台，社区素材多 | 底座常与模板一体，长大后拆解成本高 | 需求接近标准后台，追求最快上线 |
| **D. 框架 + 中后台内核** | ABP 官方启动模板、曦寒基础应用 | 既有可投产的成品，又有可独立演进的底座 | 需要理解底座的模块化与分层概念，学习曲线更陡 | 系统会长期长大，且不希望被模板绑死 |

**曦寒站在 D。** 与路线 C 最实质的区别是：模板部分可以逐块替换，底座不用换。与路线 B 的区别是：全部代码在你手上，MIT 许可，没有功能墙，代价是没有商业支持。

## 四、用最小成本验证

别信任何一页文档的自述，点一遍最快：

| 花多久 | 做什么 | 你会验证到什么 |
| --- | --- | --- |
| **10 分钟** | 打开 [在线用例](https://basicapp.xihanfun.com)，用 `superadmin` / `SuperAdmin@123` 登录 | 交互质感与能力广度是否够用 |
| **半天** | 跟着 [快速开始](./getting-started) 在本地跑起前后端 | 上手成本，以及你的环境是否顺畅 |
| **一天** | 读 [目录结构与代码地图](./project-structure) → [请求生命周期](./backend/request-lifecycle) → [二次开发](./backend/development) | 「加一个业务功能要动几个文件」这个真实成本 |

::: warning 演示环境
在线用例是公开演示环境，数据会被定期重置，请勿录入任何真实数据。
:::

## 下一步

- [快速开始](./getting-started)：在本地把系统跑起来
- [系统概述](./overview)：定位、技术栈、按角色的阅读路线
- [功能清单](./features)：逐领域的完整能力列表
- [为什么选择曦寒框架](https://framework.docs.xihanfun.com/why)：如果你要的是底座而不是成品