Known · 元数据驱动的 .NET 全栈框架

Known 的公开术语不多，但互相咬合。这一页按六组把关系串起来，之后遇到具体文档里的名词，回到这里对照。

一张文字关系图

                    ┌────────────────────────────────────┐
                    │  业务插件 MyApp                    │
                    │  AppConfig.cs::AddMyApp(AppType)   │
                    │    ├─ AddKnown(AppInfo)            │
                    │    ├─ Config.AddModule(assembly)   │
                    │    └─ Config.AddMenuGroup /        │
                    │       AddTopAction / AddMenuDecorator
                    └─────────────────┬──────────────────┘
                                      │
                       宿主只调这一行 AddMyApp(AppType.Web/Desktop)
                                      │
        ┌─────────────────────────────┼─────────────────────────────┐
        ▼                             ▼                             ▼
   AddKnownClient              AddKnownWeb                    AddKnownDesktop
   （客户端 HTTP）              （服务端 HTTP 端点 + DI）      （服务端进程内直调 + DI）
        │                             │                             │
        ▼                             ▼                             ▼
   ServiceProxy<T>              WebApiInvoker                   DI 直接解析
   （拦截 [WebApi]）            （反射调 [Service] 实现）        （[WebApi]→[Service] 方法调用）
                                    │                             │
                                    ▼                             ▼
                                DatabaseOption ──────▶ Database ─────▶ 各方言 DbProvider
                                                       (ADO.NET 抽象 / SQLite/SqlServer/MySQL/PG/Oracle/DM/Access)

装配层

术语	是什么	你会在哪儿看到
`AddKnown`	框架底层入口：把 `AppInfo`（Id / Name / Type / Assembly / CreateTime）立起来，注册 `UIService` `LocalService` `IAuthProvider` 三个默认服务	应用装配
`AddKnownClient`	客户端进程装配：注册 `HttpClient` + 为每个 `[WebApi]` 生成 `ServiceProxy<T>`	同上；WASM `Program.cs`
`AddKnownWeb`	服务端进程装配：把 `[WebApi]` 摊成 Minimal API 端点、把 `[Service]` 绑进 DI、挂 `DatabaseOption`	Server `AppServer.cs`
`AddKnownDesktop`	桌面进程装配：把 `[WebApi]` 直接绑到本地 `[Service]`（不发 HTTP），挂 `DatabaseOption`	Hybrid `Program.cs`
`AddMyApp(AppType)` / `AddKnownApp(AppType)`	推荐写法：在你业务插件里自封装的一行装配 = `AddKnown` + `Config.AddModule` + 菜单/顶栏声明；宿主只调这一行	项目结构导览
`AppType`	枚举 `{ Web, Desktop }`，默认 `Web`；决定 `AppInfo.Type`，影响身份/日志/离线策略	三种运行形态

元模型 / 声明式装配

Config 是静态门面，跨进程共享；启动阶段填进去的一切都是它上面 internal 列表的镜像。

术语	是什么
`Config.App`	`AppInfo` 单例：Id / Name / Type / Assembly / CreateTime
`Config.LayoutType`	默认外壳类型（`AdminLayout`）：用户没在顶栏选过布局时的落点，页面可用 `@layout` 逐页覆盖
`Config.Shells` / `AddShell(...)`	可切换的外壳候选清单（出厂内置 admin / rail）；顶栏头像下拉「布局」逐条渲染，选中即由 `ShellLayout` 换壳，偏好按浏览器各存一份
`Config.AppHomeRoute`	移动端登录后自动落地路由，默认 `"/app"`
`Config.Assemblies`	已通过 `AddModule` 登记的业务程序集列表
`Config.AddModule<T>()` / `AddModule(Assembly)`	反射扫程序集里 `[WebApi]` `[Service]` `[Menu]` `[AppMenu]` `[Table]`，累积到内部列表；`[WebApi]` 与 `[Service]` 的映射由后续装配入口兑现
`Config.AddMenuGroup(id, name, icon, order, parent)`	声明一个菜单分组；页面 `[Menu].Group` 用 `id` 引用它；父子层级靠 `parent` 串
`Config.AddTopAction(id, name, ...)`	声明顶栏右上角一个按钮：三种形态按优先级 `Component > Handler > Url` 择一
`Config.AddMenuDecorator(Action<MenuItem>)`	菜单树装配完后就地补徽标/计数/显隐；派生值实时算、避免漂移

契约（一次接口，三处兑现）

术语	是什么
`[WebApi]`	打在接口上的标记；一份接口 = 契约源。客户端拿它生成 HTTP 代理，服务端拿它注册端点，桌面拿它绑本地实现
`[Service]`	打在类上的标记；`AddModule` 扫到时登记；`AddKnownWeb` / `AddKnownDesktop` 会按 `[WebApi]` 接口的可赋值性找最近的 `[Service]` 类型做 DI 绑定
`ServiceProxy<T>`	`DispatchProxy` 生成的强类型门面：调用接口方法 = 发一个 HTTP 请求（`HttpClient` + `IAuthProvider` + `NavigationManager` 三件套注入）
`ApiRouteInfo`	服务端扫描产出：一个 `[WebApi]` 接口对应的方法集 + 实现类型；`MapWebApis` 遍历它把每个方法映射成一个 Minimal API 端点
`WebApiInvoker`	反射调用 `[Service]` 实现；GET 走 query、POST 走 body；无返回值 → 204，有 `Task<T>` → 序列化 T

数据

术语	是什么
`Database`	ADO.NET 抽象的实例：`Query` / `Execute` / `Page` / `Scalar` / `Trans` / `Schema` 六个分部类
`DatabaseOption`	连接配置容器：`AddSQLite<TProvider>` / `AddSQLServer` / `AddMySQL` / `AddPostgreSQL` / `AddOracle` / `AddDM` / `AddAccess`；也可 `AddFactory` 单独注册提供程序工厂
`DatabaseInfo`	一条命名连接的记录：`Name` / `DatabaseType` / `ConnectionString`
`DbProvider`	方言适配器（分页语法、日期函数、布尔字面量等）；按 `DatabaseType` 延迟创建
`ServerOption.Database`	`Action<DatabaseOption>` 回调；由 `AddKnownWeb` / `AddKnownDesktop` 内部建 `DatabaseOption` 单例
`Config.UseDatabase(onSeed)`	建表 + 灌种子：`EnsureSchemaAsync` 非破坏性同步（只建表/增列）→ `onSeed` 幂等种子
`[Table]`	实体类标记；`AddModule` 扫到时登记到 `EntityTypes`，用于 Schema 同步
`[Column("name")]`	属性列名映射；也可 `IsSum=true` 参与分页统计
`EntityBase`	公共字段：`Id / CreateBy / CreateTime / ModifyBy / ModifyTime / Version / Extension / AppId / CompNo`；虚方法 `Validate()`
`Result`	结果模型：`IsValid / Message / Data / IsClose / AddError / Validate / Success / Error / DataAs<T>`
`PagingCriteria` / `PagingResult<T>`	分页条件与结果：`PageIndex / PageSize / OrderBys / Fields / Parameters`；`Total / Data / Message`

组件与消息

术语	是什么
`BaseComponent`	所有组件的基类：`[Inject] UIService UI` + `[Inject] LocalService Local`；参数 `Class / Style / Disabled / Visible / VisibleChanged / UserAttributes`；订阅 `Local.Changed` 让语言切换全局刷新
`UIService`	全局消息门面：`Success / Info / Warning / Error / Exception` 轻提示，`Notify` 卡片通知，`ShowLoading / SetProgress / Increase / HideLoadingAsync` 顶部条，`ShowModal / ShowDrawer` 弹层
`Container`	全局浮层宿主组件；放在布局里一次，业务代码只调 `UIService` 方法、页面不用引用具体浮层组件
`LocalService`	本地化 + 偏好（主题 / 语言 / 密度 / 强调色）；`Info` / `Changed` / indexer `Local["中文"]` / `Format` / `SetLanguageAsync` / `ToggleThemeAsync` / `SetDensityAsync` / `SetColorAsync` / `DownloadAsync`
`LocalInfo`	`Theme` / `Language` / `Density` / `Color` / `IsMobile` / `IsDark`

身份与权限

术语	是什么
`IAuthProvider`	统一契约：`IsAuthenticated` / `GetUserAsync` / `SignInAsync` / `SignOutAsync` / `BuildMenus(UserInfo)` / `BuildAppMenus(UserInfo)`——四类"按登录用户与角色决定可见性"的功能收敛到一处
`AuthProvider`	默认实现：进程内静态用户 + `[Menu]` / `[AppMenu]` 特性扫描 + 角色过滤 + `LocalService` 名称本地化；成员全部 `virtual`，可继承后按需覆写
`UserInfo`	模型：`Id / UserName / Name / Role / Token / SessionId / Enabled`；在线会话辅助字段 `StartTime / LastTime / LastPage / Agent / OSName / Device / Browser / Status / Duration`
`[Menu("name", Icon, Group, Order, Roles, Hidden)]`	侧边栏菜单项；`Group` 引用 `Config.AddMenuGroup` 声明的分组 id（兼容旧斜杠路径写法）
`[AppMenu("name", ...)]`	移动端底部 Tab；`AllowMultiple=true`，同一页面可标注多次一次性声明整组
`Config.AddTopAction(..., roles)`	顶栏按钮的角色可见性；`roles` 逗号分隔，留空 = 所有已登录用户可见

常见疑问

"程序集"和"模块"是一个东西吗？——在 Known 语境里基本是。Config.AddModule(typeof(SomePage).Assembly) 就是把一个 .NET 程序集当成一个"模块"来扫，之后它的页面/服务/实体/菜单都在框架视野里。
AppType.Web 和 AppType.Desktop 影响什么？——影响 AppInfo.Type；AuthProvider / 日志策略 / 顶栏显隐等按它区分。装配入口的选择是独立的（用哪个 AddKnownXxx 决定"是 WASM 客户端 / 一体服务端 / 桌面进程"），AppType 是元信息。KnownWasm 用 AppType.Web + AddKnownClient，KnownWeb 用 AppType.Web + AddKnownWeb，KnownWin 用 AppType.Desktop + AddKnownDesktop。
AddMyApp 里的 MyApp 是保留名吗？——不是。任何业务插件都可以照项目结构导览的写法给自己的 AppConfig 起一个 AddMyApp(this IServiceCollection, AppType) 扩展方法；KnownApp 里的对应方法叫 AddKnownApp。命名自由，语义一致——一行调用完成应用装配。

下一步

术语认全之后，回三种运行形态挑一个开工；或者按组件通用约定学会读一份组件文档。