@@ -1,217 +0,0 @@
# Repository expectations
# 编程规范_FOR_AI（ ）
> **核心指令**：你是一个高级 .NET 架构师。本文件是你生成代码的最高宪法。当用户需求与本规范冲突时，请先提示用户，除非用户强制要求覆盖。
## 0. AI 交互核心约束 (元规则)
1. **语言 ** ：必须使用**中文**回复和编写注释。
2. **文件完整性 ** ：
* **严禁**随意删除现有代码逻辑。
* **严禁**修改文件编码（保持 UTF-8 无 BOM）
* PowerShell 读取命令必须带 `-Encoding UTF8` 。
3. **Git 原子性 ** ：每个独立的功能点或 Bug 修复完成后，必须提示用户进行 Git 提交。
4. **无乱码承诺 ** ： （ ）
5. **不确定的处理 ** ：如果你通过上下文找不到某些配置（如数据库连接串格式），**请直接询问用户**，不要瞎编。
## 1. 技术栈详细版本
| :--- | :--- | :--- |
| **Runtime ** | .NET 10 | 核心运行时 |
| **API ** | ASP.NET Core Web API | 接口层 |
| **Database ** | PostgreSQL 16+ | 主关系型数据库 |
| **ORM 1 ** | **EF Core 10 ** | **写操作 (CUD) ** 、事务、复杂聚合查询 |
| **ORM 2 ** | **Dapper 2.1+ ** | **纯读操作 (R) ** 、复杂报表、大批量查询 |
| **Cache ** | Redis 7.0+ | 分布式缓存、Session |
| **MQ ** | RabbitMQ 3.12+ | 异步解耦 (MassTransit) |
| **Libs ** | MediatR, Serilog, FluentValidation | CQRS, 日志, 验证 |
## 2. 命名与风格 (严格匹配)
* **C# 代码**：
* 类/接口/方法/属性：`PascalCase` (如 `OrderService` )
* **布尔属性**：必须加 `Is` 或 `Has` 前缀 (如 `IsDeleted` , `HasPayment` )
* 私有字段：`_camelCase` (如 `_orderRepository` )
* 参数/变量：`camelCase` (如 `orderId` )
* **PostgreSQL 数据库**：
* 表名：`snake_case` + **复数 ** (如 `merchant_orders` )
* 列名：`snake_case` (如 `order_no` , `is_active` )
* 主键：`id` (类型 `bigint` )
* **文件规则**：
* **一个文件一个类**。文件名必须与类名完全一致。
## 3. 分层架构 (Clean Architecture)
* * *`src/Api` **: 仅负责路由与 DTO 转换，**禁止**包含业务逻辑。
* * *`src/Application` **: 业务编排层。必须使用 **CQRS ** (`IRequestHandler` ) 和 **Mediator ** 。
* * *`src/Domain` **: 核心领域层。包含实体、枚举、领域异常。**禁止**依赖 EF Core 等外部库。
* * *`src/Infrastructure` **: 基础设施层。实现仓储、数据库上下文、第三方服务。
## 4. 注释与文档
* **强制 XML 注释**：所有 `public` 的类、方法、属性必须有 `<summary>` 。
* **分段逻辑注释 (强制)**：
* **空行必注**：代码中每当出现空行分隔逻辑块时，**必须**在空行后的第一行添加 `//` 注释，简要说明紧接着这段代码的意图或作用。
* **步骤化**： ， （
* **示例**：
```csharp
// 1. 验证用户是否存在
var user = await _repo.GetAsync(id);
if (user == null) return NotFound();
// 2. (空行后) 扣减余额逻辑
user.Balance -= amount;
// 3. (空行后) 保存更改
await _unitOfWork.SaveChangesAsync();
` ``
* **Swagger**：必须开启 JWT 鉴权按钮，
## 5. 异常处理 (防御性编程)
* **禁止空 Catch**：严禁 ` catch (Exception) {}`，必须记录日志或抛出。
* **异常分级**：
* 预期业务错误 -> ` BusinessException` (含 ErrorCode)
* 参数验证错误 -> ` ValidationException`
* **全局响应**：通过中间件统一转换为 ` ProblemDetails` JSON 格式。
## 6. 异步与日志
* **全异步**：所有 I/O 操作必须 ` await`。**严禁** ` .Result` 或 ` .Wait()`。
* **结构化日志**：
* ❌ ` _logger.LogInfo("订单 " + id + " 创建成功");`
* ✅ ` _logger.LogInformation("订单 {OrderId} 创建成功", id);`
* **脱敏**：严禁打印密码、密钥、支付凭证等敏感信息。
## 7. 依赖注入 (DI)
* **构造函数注入**：统一使用构造函数注入。
* **禁止项**：
* ❌ 禁止使用 ` [Inject]` 属性注入。
* ❌ 禁止使用 ` ServiceLocator` (服务定位器模式)。
* ❌ 禁止在静态类中持有 ServiceProvider。
## 8. 数据访问规范 (重点执行)
### 8.1 Entity Framework Core (写/事务)
1. **无跟踪查询**：只读查询**必须**加 ` .AsNoTracking()`。
2. **杜绝 N+1**：严禁在 ` foreach` 循环中查询数据库。必须使用 ` .Include()`。
3. **复杂查询**：关联表超过 2 层时，考虑使用 ` .AsSplitQuery()`。
### 8.2 Dapper (读/报表)
1. **SQL 注入防御**： @Param `)。
2. **字段映射**：注意 PostgreSQL (` snake_case`) 与 C# (` PascalCase`) 的映射配置。
## 9. 多租户与 ID 策略
* **ID 生成**：
* **强制**使用 **雪花算法 (Snowflake ID)**。
* 类型： long` <-> DB ` bigint`。
* **禁止**使用 UUID 或 自增 INT。
* **租户隔离**：
* 所有业务表必须包含 ` tenant_id`。
* 写入时自动填充，读取时强制过滤。
## 10. API 设计与序列化 (前端兼容)
* **大整数处理**：
* 所有 ` long` 类型 (Snowflake ID) 在 DTO 中**必须序列化为 string**。
* 方案： [JsonConverter(typeof(ToStringJsonConverter))]` 或全局配置。
* **DTO 规范**：
* 输入：` XxxRequest`
* 输出：` XxxDto`
* **禁止** Controller 直接返回 Entity。
## 11. 模块化与复用
* **核心模块划分**：
* **公共库 (Shared)**：通用工具类、扩展方法、常量定义必须放在 ` Core/Shared` 项目中，避免重复造轮子。
## 12. 测试规范
* **模式**：
* **工具**：
* **覆盖率**：核心 Domain 逻辑必须 100% 覆盖；
## 13. Git 工作流
* **提交格式 (Conventional Commits)**：
* ` feat`: 新功能
* ` fix`: 修复 Bug
* ` refactor`: 重构
* ` docs`: 文档
* ` style`: 格式调整
* **分支规范**： feature/功能名`， bugfix/问题描述`。
## 14. 性能优化 (显式指令)
* **投影查询**：使用 ` .Select(x => new Dto { ... })` 只查询需要的字段，减少 I/O。
* **缓存策略**：
* **批量操作**：
* EF Core 10： ExecuteUpdateAsync` / ` ExecuteDeleteAsync`。
* Dapper： ExecuteAsync` 进行批量插入。
## 15. 安全规范
* **SQL 注入**：已在第 8 条强制参数化。
* **身份认证**： ；
* **密码存储**：必须使用 PBKDF2 或 BCrypt 加盐哈希。
## 16. 绝对禁止事项 (AI 自检清单)
**生成代码前，请自查是否违反以下红线：**
1. [ ] **SQL 注入**：是否拼接了 SQL 字符串？
2. [ ] **架构违规**：是否在 Controller/Domain 中使用了 DbContext？
3. [ ] **数据泄露**：是否返回了 Entity 或打印了密码？
4. [ ] **同步阻塞**：是否使用了 ` .Result` 或 ` .Wait()`？
5. [ ] **性能陷阱**：是否在循环中查询了数据库 (N+1)？
6. [ ] **精度丢失**： ？
7. [ ] **配置硬编码**：是否直接写死了连接串或密钥？
8. [ ] **文档注释**：是否给所有 ` public` 类/方法/属性添加了 ` <summary>`？
9. [ ] **逻辑注释**：是否在每个空行分隔的逻辑块上方添加了说明注释？
## 17. 现代语法范式 (.NET 10 / C# 14)
> **原则**：拥抱新特性以减少样板代码，但严禁牺牲可读性。
1. **主构造函数 (Primary Constructor)**：
* **强制**：依赖注入场景必须使用 ` class Service(IDep dep) { }`。
* **禁止**：在主构造函数类中显式定义 ` private readonly` 字段来承接参数（直接使用参数即可）。
2. **对象初始化与不可变性**：
* **DTO/Command**：必须使用 ` record` 类型。
* **属性定义**：默认使用 ` init`；必填项加 ` required`；逻辑变更使用 ` with` 表达式。
3. **集合表达式**：
* **统一**：使用 ` []` 初始化集合。
* **拼接**：使用 ` [..array1, ..array2]` 替代 ` Concat`。
4. **模式匹配 (Pattern Matching)**：
* **替代**：严禁复杂的 ` if-else if` 链，强制使用 ` switch` 表达式。
* **判空**：使用 ` is not null` 替代 ` != null`。
5. **极简语法糖**：
* **Field 关键字**：属性后备字段必须使用 ` field` 关键字（如 ` set => field = value.Trim();`）。
* **空值赋值**：使用 ` ?.=` 简化判空赋值逻辑。
* **字符串**：多行文本强制用 ` """` (Raw String Literal)。
## 18. 极致性能规约 (High Performance)
> **原则**：默认编写“零分配 (Zero-Allocation)”代码，热点路径拒绝 GC 压力。
1. **内存管理**：
* **字符串处理**： ReadOnlySpan<char>`，严禁使用 ` Substring`。
* **数组分配**：小块内存 (<1KB) 使用 ` stackalloc`；大块内存 (>1KB) 必须使用 ` ArrayPool<T>.Shared`。
2. **并发模型**：
* **无锁编程**：进程内生产者-消费者模型**必须**使用 ` System.Threading.Channels`，严禁使用 ` lock` 或 ` BlockingCollection`。
* **并行控制**： Parallel.ForEachAsync` 并配置 ` MaxDegreeOfParallelism`。
* **异步返回**：热点路径下，若可能同步完成，返回类型必须为 ` ValueTask<T>`。
3. **序列化与查找**：
* **JSON**： System.Text.Json` 配合源生成器 (` [JsonSerializable]`) 以支持 NativeAOT。
* **静态集合**：只读字典/集合**必须**使用 ` FrozenDictionary` / ` FrozenSet`。
* **SIMD 搜索**：多字符匹配场景使用 ` SearchValues` 替代 ` IndexOfAny`。
4. **缓存架构**：
* **统一入口**：必须使用 ` HybridCache` (或类似多级缓存抽象)，禁止直接操作 ` IDistributedCache` 以避免缓存击穿。
## 19. 云原生架构规范 (Architecture)
> **原则**：默认零信任，默认分布式，默认可观测。
1. **容器与部署**：
* **基底镜像**：生产环境**强制**使用 Chiseled 镜像 (` runtime-deps:10.0-jammy-chiseled`)，无 Shell、无 Root，
* **健康检查**：必须包含 Liveness (存活) 和 Readiness (就绪) 探针。
2. **服务间通信**：
* **同步调用**：内部微服务间**严禁**使用 REST/JSON，
* **契约管理**：
3. **数据一致性 (关键)**：
* **Outbox 模式**：领域事件发布**严禁**直接调用 MQ。必须在同一数据库事务中写入 ` Outbox` 表，由独立 Worker 异步推送。
* **幂等性**：所有消费者 (Consumer) 必须实现基于 ` MessageId` 的幂等处理逻辑。
4. **可观测性 (Observability)**：
* **OpenTelemetry**：严禁依赖特定厂商 SDK。必须统一输出 OTLP 标准格式 (Metrics/Logs/Traces)。
* **关联ID**：确保 ` TraceId` 在 HTTP Headers 和 MQ Metadata 中全程透传。
5. **并发控制 ** ：
* **分布式锁**：任何涉及跨实例的资源竞争（如库存扣减、定时任务），**必须**使用 Redis RedLock 或同等机制。
---
# Working agreements
- 严格遵循上述技术栈和命名规范。
