Store.Management/.agents/rules/architecture.md

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 或项目依赖变更后，构建受影响项目并运行相关冒烟测试。以下命令均在仓库根目录执行：

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 是框架示例，不证明商品业务已接入。新增商品字段、上架状态或权限须依据具体需求与服务端契约。