Store.Management/Source/Store.Management.Api

Store Management API 客户端

独立的 API 类库（当前继承仓库的 net8.0-windows 目标框架），使用 RestSharp 112.1.0 连接 StoreWeb。WPF 项目已引用该类库。每个服务地址及用户会话创建一个 StoreApiClient，建议在应用容器注册为单例，退出应用时释放。

调用

using Store.Management.Api;
using Store.Management.Api.Authentication;
using Store.Management.Api.Users;
using Store.Management.Api.Transport;

using var api = new StoreApiClient(new ApiClientOptions
{
    BaseUrl = new Uri("https://your-server/"), // 替换为实际服务地址
    Version = "v1",
    Timeout = TimeSpan.FromSeconds(30)
});
try
{
    await api.Auth.LoginAsync(new LoginRequest
    {
        UserName = userName,
        Password = passwordMd5, // UTF-8 密码的 32 位大写 MD5，保留原密码首尾空格
        DeviceId = deviceId, // 可选；稳定设备标识由宿主应用管理
        DeviceName = Environment.MachineName
    });
    var me = await api.Auth.MeAsync();
    var page = await api.Users.SearchAsync(new UserSearchRequest
    {
        Page = 1, PageSize = 50, Keyword = ""
    });
    var created = await api.Users.CreateAsync(new UserCreateRequest
    {
        UserName = "new-user", Password = initialPassword, NickName = "新用户"
    });
    await api.Users.UpdateAsync(new UserUpdateRequest { Id = created.Id, NickName = "修改后的昵称" });
    await api.Auth.LogoutAsync();
}
catch (ApiException ex)
{
    // 显示 ex.Message；根据 Kind 区分失败类型，TraceId 可用于联系服务端排查。
    // Unauthorized 时导航登录页；HTTP 403 不清除会话。
}

示例中的账号、密码摘要、设备标识由调用方提供；登录窗口已负责计算密码摘要，API 层不重复计算。异步方法均支持 CancellationToken；主动取消抛出 OperationCanceledException，本地输入校验抛出 ValidationException。

文件与职责

• StoreApiClient.cs：组合会话、传输层与业务模块，集中管理生命周期。
• ApiClientOptions.cs：服务地址、版本和超时配置。
• Transport/ApiTransport.cs：唯一 HTTP 出口，统一 Bearer、JSON、查询参数、校验及错误映射。
• Transport/ApiException.cs：区分网络、超时、HTTP、业务、响应格式与认证错误，保留状态码、业务码与 TraceId。
• Authentication/：登录、退出、当前用户；Token 仅存内存。
• Models/：服务端响应信封与分页模型。
• Users/：用户分页、查询、添加与修改，DTO 只包含当前基础功能所需字段。

协议与扩展

对齐 StoreWeb 的 AuthController、TokenResult、UnifyResultFilter 和用户管理控制器。成功码为 200；HTTP 200 内的业务失败同样抛出 ApiException。先读取响应状态与业务码，再解析成功 data，避免错误响应的数据结构掩盖业务错误。登录读取 data.token，认证采用 Bearer opaque Token，不解析 JWT，不根据首次登录的有效期自行判定续期。HTTP 或业务 401 清除当前请求所用的会话；旧请求的 401 不清除新 Token。

后续商品模块按 Users 的方式新增独立 DTO、接口和实现，由 StoreApiClient 暴露模块入口。模块通过 Transport.GetRequiredAsync 发送有数据请求，通过 SendAsync