# 三端目录与 XFE WinUI 架构

源码按运行职责拆分，解决方案中的分组与物理路径一致：

```text
Server/
  XFEWarframe.Server/            ServerInteractive 控制台入口
  XFEWarframe.Core/              游戏 API、存档与业务逻辑
  data/                         嵌入程序集的上游静态数据
  Tests/XFEWarframe.Tests/
Client/
  XFEWarframe.Player/            玩家 WinUI 应用
  XFEWarframe.Client/            C# 安装、检测、恢复、启动逻辑
  XFEWarframe.Installer/         C# 命令行安装器
  XFEWarframe.Bridge/            C# NativeAOT 游戏兼容组件
  Tests/XFEWarframe.Client.Tests/
Admin/
  XFEWarframe.Admin/             管理员 WinUI 应用
```

根目录的 `XFEWarframe.slnx` 包含全部工程。也可分别打开三端文件夹内的 `Server.slnx`、`Client.slnx`、`Admin.slnx`。

Visual Studio 的启动项目、非打包 WinUI 调试配置和 x64 映射见 [调试说明](DEBUGGING.md)。

## 模板来源

采用用户确认的本机模板：
`XFEExtension.NetCore.VSIX/XFEExtension.NetCore.VSIX/ProjectTemplates/XFEApplication (WinUI3).zip`。

- 本机 VSIX 仓库提交：`b2dfe0d26a81310ef788eefd5ae41eff7c892f1f`。
- 模板 SHA-256：`51CDCDA995C986F1E8EB02A59E839B541222D8275C25B334B901860444730BA1`。
- 模板结构已按 Warframe 功能改写；未保留演示服务、示例页面或空的演示项目。
- 保留模板的 Apache 2.0 许可，见 [许可文件](licenses/XFE-WinUI-Template-Apache-2.0.txt)。

两个应用均采用以下实际分层：

| 位置 | 职责 |
| --- | --- |
| App / MainWindow | 注册页面及服务、应用生命周期、原生窗口与 DPI |
| Views/AppShellPage | 原生 WinUI TitleBar、NavigationView、Frame、消息与加载服务宿主 |
| Views | 独立 XAML 页面；后台代码只绑定 ViewModel、接收导航与控件事件 |
| ViewModels | CommunityToolkit ObservableObject、可观察属性、异步命令与页面状态 |
| Interface/Services | 业务及交互服务契约 |
| Implements/Services | API、客户端安装与启动、文件选择、对话框、配置迁移 |
| Models | 共享应用状态和列表数据 |
| Profiles/CrossVersionProfiles | XFEProfile 持久化主题及各端偏好 |
| Utilities / Styles | 路径、窗口辅助、验证工具、主题资源与控件样式 |

使用模板的 `PageManager` 注册页面，使用 `ServiceManager` 和 `GlobalServiceBase` 管理服务。页面导航由 `INavigationViewService`、`IAutoNavigationParameterService` 承载；消息、对话框和加载状态分别接入 `IMessageService`、`IDialogService`、`ILoadingService`。不只采用相同文件夹名称。

固定依赖为 WinUIHelper **1.2.5**（模板的 1.2.x 系列）、Windows App SDK **1.8.260804001**、CommunityToolkit.Mvvm **8.4.2**、AutoConfig **4.1.2**。使用 .NET 10 partial properties；主题属性初值使用完整类型名，以兼容配置生成器生成代码的命名空间。

## 配置与生命周期

管理员配置位于 `%LOCALAPPDATA%/XFEWarframe/Admin/Profiles`，玩家配置位于 `%LOCALAPPDATA%/XFEWarframe/Player/Profiles`。两者互不共享。玩家端首次使用时读取旧 `Player/settings.json` 并迁移游戏目录和服务器地址，保留旧文件；`--settings=<旧配置文件>` 可显式导入。

管理员令牌只保存在内存，不写入 Profiles。管理员端只在本地地址下自动读取本地服务配置，远程连接通过设置页输入。玩家工程不引用 Admin、Server 或游戏 Core，不调用管理 API。

玩家端的 `AccountPage` 与 `InventoryPage` 使用 `IPlayerAccountService` / `PlayerAccountService`、独立的 `PlayerAccountState` 和各自 ViewModel。可测试的 HTTP 协议客户端位于 `XFEWarframe.Client/PlayerPortalClient.cs`。账号与游戏存档共用，Bearer 会话独立于游戏 nonce。`RememberedAccountStore` 通过 Windows 用户数据保护加密登录信息，按服务器地址独立存储；XFEProfile 仅保存邮箱和默认开启的 `RememberAccount` 选项。关闭记住选项或明确退出会清除相应的加密记录。

关闭玩家窗口会先取消正在执行的安装并等待清理/回滚结束。管理员窗口关闭会停止轮询并释放 HTTP 客户端，独立服务器继续运行。两端关闭时刷新 XFEProfile 的待保存写入。

新启动脚本的服务数据默认在 `Server/runtime`。旧根目录 `runtime` 的存档没有自动移动或覆盖，正在运行的旧实例不受影响；继续使用旧存档可传 `-Root ./runtime`，或在停止旧服务器后自行迁入 `Server/runtime`。

## 发布与验证

`scripts/Publish.ps1` 生成三个运行目录及三个独立 ZIP：

- `Server/Start.cmd`：启动 API 控制台服务，数据在同目录的 `runtime`。
- `Client/Start.cmd`：玩家应用；命令行安装器在 `Client/Installer`，兼容组件在 `Client/Bridge`。
- `Admin/Start.cmd`：管理员应用；连接远程服务器时无需 Server 文件夹，本地启动功能查找同级 Server。

各包保留对应源码、许可证、文档与验证报告，不打包用户存档、管理令牌或个人偏好。

`scripts/Smoke-Desktop.ps1` 使用临时本地服务器和隔离的 `--profile-root`，在隐藏窗口中检查全部页面的构造、导航、ViewModel 加载、不同宽度布局、主题和配置保存。不会执行安装、卸载或游戏启动。它不替代真实显示器上的视觉验收。

`--verify-ui=<报告路径>` 仅用于这项主动触发的验证；正常启动没有测试页面或开发选项。

## 管理发布与账号交互

管理员新增 MailPage、NewsPage 和各自 ViewModel，复用 IAdminService 调用管理接口。玩家新增 ItemCatalogPage，AccountPage 只展示名片；LoginDialog 与 RegisterDialog 复用 AuthenticationViewModel，弹窗由模板 IDialogService 承载。FooterMenuItems 中显示账号与偏好设置，账号头像与昵称由 PlayerAccountState 共享。权限改变通过可观察状态同步隐藏操作区域。

战甲、普通武器与显赫武器的拖动 MOD 配装共用 `Client/SharedUI/ModLoadoutView`、`EquipmentEditorModel` 和编译的 `ModLoadoutResources.xaml`。原版资源图片由异步 `GameAssetImage` 显示；数据规则位于 `Client/Shared/ModLoadoutRules.cs`，服务端保存重复执行相同校验。技能的 AutoSuggestBox 与候选模板共用名称和原版图标。两端只替换 API 传输和账号上下文，不复制配装 UI；详见 [配装说明](MOD-LOADOUT.md)。