# Store.Management 项目架构

## 定位与实现边界

Store.Management 是需要登录并访问远端 API 的 WPF 门店管理客户端。当前实现包含登录、用户 API、框架能力示例以及管理、商品上架模块的启动骨架；不要把骨架或示例描述为已完成的业务功能。

## 项目划分

| 路径 | 职责 |
|---|---|
| `Source/Store.Management/` | 应用宿主、登录窗口、主窗口、示例页面与容器注册 |
| `Source/Store.Management.Framework/` | WPF 基础控件、应用生命周期、配置目录、配置服务、日志与工具 |
| `Source/Store.Management.Api/` | RestSharp API 客户端、认证会话、用户接口、DTO 与传输错误 |
| `Source/Core/MAX.Core/` | 通用工具、Autofac 注册、类型发现与通知集成 |
| `Source/Core/MAX.Framework/` | Prism/Autofac 适配、命令、弹窗基类与日志封装 |
| `Source/Core/MAX.Notification/` | 通知契约、发布器与处理器分发 |
| `Source/Modules/Store.Admin/` | 管理模块骨架，目前通过项目引用依赖 Framework |
| `Source/Modules/Store.ListingProduct/` | 商品上架模块骨架，目前通过项目引用依赖 Framework |
| `Tests/` | 可执行的冒烟测试项目 |

- 通用 Core 不反向依赖 Store 项目；API 层保持与 WPF 视图解耦。
- 共用客户端基础设施放 Framework，接口通信放 Api，具体业务放对应模块。
- 当前宿主没有引用上述两个业务模块；模块只有 `IStartup` 骨架。新增模块功能时核实程序集加载、注册和导航链路，不假设已自动接入。
- 不为遵守规则而新增数据库、ORM、图表、视频或文档生成依赖；当前仓库没有这些业务实现。

## 技术与配置依据

- `Directory.Build.props` 默认 `net8.0-windows`、C# `14.0`、隐式 using、Nullable annotations；各项目可以覆盖。
- Core 与 Notification 中有 `net8.0` 项目；业务模块和部分测试覆盖为 `net10.0` / `net10.0-windows`。依据各 `.csproj`，不将整个解决方案误写为同一目标框架，也不擅自统一。
- UI 使用 Prism.Wpf 和仓库内的 Autofac 适配，控件使用官方 `HandyControl` 与 `MAX.Common.WPF`；具体版本以项目文件为准。
- API 使用 RestSharp 与 System.Text.Json；JSON 配置服务使用 Newtonsoft.Json；日志使用 NLog。
- 应用入口为 `App : FrameworkApplication`，后者继承 `Prism.Autofac.PrismApplication`。维护现有启动、登录成功切换主窗口及退出释放客户端的流程。

## 数据、目录与生命周期

- 所有 HTTP 请求复用 `StoreApiClient` / `ApiTransport`，不在 ViewModel 中另起传输实现。
- 路径复用 `FolderConfig`，配置复用 `JsonSettingsServiceBase<T>`；读取路径不应触发不必要的文件创建。
- 当前 `FolderConfig.AppName` 是 `StoreManagement`，应用数据目录实际为 `%LOCALAPPDATA%/StoreManagement`；不要根据类注释或程序集名猜目录，也不要无迁移方案改名。
- 保持配置保存的串行化、同目录临时文件替换、失败保留原模型行为。
- 普通业务失败交给调用方展示；致命错误复用 `ApplicationLogService` / `FrameworkApplication.Fatal`。不要吞掉错误或把取消当作致命故障。

## 验证方式

C#、XAML 或项目依赖变更后，构建受影响项目并运行相关冒烟测试。以下命令均在仓库根目录执行：

```powershell
dotnet build Store.Management.slnx
dotnet run --project Tests/MAX.Core.SmokeTests/MAX.Core.SmokeTests.csproj
dotnet run --project Tests/MAX.Notification.SmokeTests/MAX.Notification.SmokeTests.csproj
dotnet run --project Tests/Store.Management.Api.SmokeTests/Store.Management.Api.SmokeTests.csproj
dotnet run --project Tests/Store.Management.Framework.SmokeTests/Store.Management.Framework.SmokeTests.csproj
dotnet run --project Tests/Store.Management.App.SmokeTests/Store.Management.App.SmokeTests.csproj
```

- 这些测试是控制台可执行程序，不能仅以 `dotnet test` 无失败判断测试已运行。
- Framework 和 App 冒烟测试未列入当前解决方案，按项目路径单独执行；WPF 测试需要 Windows，部分项目需要 .NET 10 SDK。
- 纯规则文档修改检查引用和内容即可，无需启动应用或全量构建。
- 遇到 SDK、还原或文件锁定问题，报告具体阻碍；不要擅自终止用户进程或把失败报告为通过。

## API 与业务契约

- 复用 `IAuthApi` 的登录、退出、当前用户接口及 `IUserApi` 的查询、新增、更新接口；保持现有路由大小写、HTTP 方法与参数位置。
- 登录窗口当前按服务端契约对 UTF-8 密码计算 32 位大写 MD5 后提交，保留密码首尾空格。不把该转换推广为其他用途的密码存储策略。
- TokenSession 只存内存，不将密码或 Token 写入配置、日志或用户资料 DTO；保持登录/退出串行及旧请求 401 不清除新会话的行为。
- ApiResult 的业务成功码为 200；HTTP 成功不等于业务成功。分页使用 Page、PageSize 与 Total、Items；保留 DTO DataAnnotations 的长度及范围限制。
- 用户名与昵称分别对应 UserName、NickName；积分与可空余额使用 DTO 的 decimal 类型，区分 null 与 0。不自行推断 GroupId、ParentUserName 的权限语义。
- ApiTransport 是统一传输出口，负责相对路由、版本、认证头、校验、取消与错误分类；保留 ApiException 的类型、状态和追踪信息。
- ProductSavedNotification 是框架示例，不证明商品业务已接入。新增商品字段、上架状态或权限须依据具体需求与服务端契约。