Store.Management/.agents/rules/csharp-syntax.md

C# 编码规则

版本与组织

• Directory.Build.props 指定 C# 14；属性优先使用 field 关键字管理编译器生成的后备字段。目标框架以各 .csproj 的覆盖值为准。
• 可使用 C# 14 及此前版本的语言特性，调用 API 仍须兼容目标框架。保留各项目 Nullable 设置；开发环境需要支持 C# 14 的 SDK。
• 类型、方法、公开属性使用 PascalCase，参数和局部变量使用 camelCase；私有字段沿用文件现有风格。
• 命名空间匹配项目与目录，例如 Store.Management.Api.Users；Core 项目保留 MAX.* 命名空间。
• 新文件优先文件范围命名空间；不批量重排无关代码。
• 新代码优先显式类型；修改已有代码时不批量替换 var。控制流使用大括号，每条语句独立一行，避免无意义空行。
• 公共接口及复杂行为补充 XML 注释，解释约束和原因，不要求固定注释比例。
• 对职责一致的重复逻辑适度提取，避免重复实现传输、配置和容器功能，不为单次用途增加多层抽象。

MVVM、DI 与异步

• ViewModel 使用 Prism BindableBase，属性优先以 field 配合 SetProperty(ref field, value)；需要跨成员访问或特殊存储语义时保留显式字段，不引入 DevExpress MVVM。
• 命令使用现有 DelegateCommand / AsyncDelegateCommand；服务优先构造注入，由现有 Prism/Autofac 容器管理生命周期。
• 调用内部库 API 前核实当前项目的依赖和类型；不要为了简单工具让 API/Core 依赖 UI 包。
• 异步返回 Task 并按需传递 CancellationToken；async void 限于 UI 事件。
• 不在 UI 线程用 Result/Wait 阻塞网络或文件操作；库层可 ConfigureAwait(false)，更新控件和绑定时回到 UI 线程。
• 公共入口校验参数，API DTO 沿用 DataAnnotations；区分取消、业务失败和致命错误。
• 复用现有 NLog 封装记录错误，保留异常类型和上下文，不强制每个 catch 调用 Debug.WriteLine，不记录密码或 Token。
• 释放自有 IDisposable、取消源与事件订阅；注入的外部 HttpClient 由调用者管理。

序列化

API 层保持 System.Text.Json / RestSharp 协议；JSON 配置服务保持 Newtonsoft.Json 格式。不因统一库名而改变服务端字段、配置兼容性或增加依赖。

field 属性示例

public string Keyword
{
    get => field ?? string.Empty;
    set => SetProperty(ref field, value);
}

public DelegateCommand RefreshCommand => field ??= new DelegateCommand(Refresh);

属性的初始值、可空性与通知行为应按实际需求明确；不要仅为使用 field 改写无关代码。