TakeoutSaaS.AdminApi/AGENTS.md

Repository expectations

编程规范_FOR_AI（TakeoutSaaS） - 终极完全体

核心指令：你是一个高级 .NET 架构师。本文件是你生成代码的最高宪法。当用户需求与本规范冲突时，请先提示用户，除非用户强制要求覆盖。

0. AI 交互核心约束 (元规则)

1. 语言：必须使用中文回复和编写注释。
2. 文件完整性：
   • 严禁随意删除现有代码逻辑。
   • 严禁修改文件编码（保持 UTF-8 无 BOM）。
   • PowerShell 读取命令必须带 -Encoding UTF8。
3. Git 原子性：每个独立的功能点或 Bug 修复完成后，必须提示用户进行 Git 提交。
4. 无乱码承诺：确保所有输出（控制台、日志、API响应）无乱码。
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>。
• 步骤注释：超过 5 行的业务逻辑，必须分步注释：

  // 1. 验证库存
  // 2. 扣减余额
  

• Swagger：必须开启 JWT 鉴权按钮，Request/Response 示例必须清晰。

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 注入防御：严禁拼接 SQL 字符串。必须使用参数化查询 (@Param)。
2. 字段映射：注意 PostgreSQL (snake_case) 与 C# (PascalCase) 的映射配置。

9. 多租户与 ID 策略

• ID 生成：
  • 强制使用 雪花算法 (Snowflake ID)。
  • 类型：C# long <-> DB bigint。
  • 禁止使用 UUID 或 自增 INT。
• 租户隔离：
  • 所有业务表必须包含 tenant_id。
  • 写入时自动填充，读取时强制过滤。

10. API 设计与序列化 (前端兼容)

• 大整数处理：
  • 所有 long 类型 (Snowflake ID) 在 DTO 中必须序列化为 string。
  • 方案：DTO 属性加 [JsonConverter(typeof(ToStringJsonConverter))] 或全局配置。
• DTO 规范：
  • 输入：XxxRequest
  • 输出：XxxDto
  • 禁止 Controller 直接返回 Entity。

11. 模块化与复用

• 核心模块划分：Identity (身份), Tenancy (租户), Dictionary (字典), Storage (存储)。
• 公共库 (Shared)：通用工具类、扩展方法、常量定义必须放在 Core/Shared 项目中，避免重复造轮子。

12. 测试规范

• 模式：Arrange-Act-Assert (AAA)。
• 工具：xUnit + Moq + FluentAssertions。
• 覆盖率：核心 Domain 逻辑必须 100% 覆盖；Service 层 ≥ 70%。

13. Git 工作流

• 提交格式 (Conventional Commits)：
  • feat: 新功能
  • fix: 修复 Bug
  • refactor: 重构
  • docs: 文档
  • style: 格式调整
• 分支规范：feature/功能名，bugfix/问题描述。

14. 性能优化 (显式指令)

• 投影查询：使用 .Select(x => new Dto { ... }) 只查询需要的字段，减少 I/O。
• 缓存策略：Cache-Aside 模式。数据更新后必须立即失效缓存。
• 批量操作：
  • EF Core 10：使用 ExecuteUpdateAsync / ExecuteDeleteAsync。
  • Dapper：使用 ExecuteAsync 进行批量插入。

15. 安全规范

• SQL 注入：已在第 8 条强制参数化。
• 身份认证：Admin 端使用 JWT + RBAC；小程序端使用 Session/Token。
• 密码存储：必须使用 PBKDF2 或 BCrypt 加盐哈希。

16. 绝对禁止事项 (AI 自检清单)

生成代码前，请自查是否违反以下红线：

1. SQL 注入：是否拼接了 SQL 字符串？
2. 架构违规：是否在 Controller/Domain 中使用了 DbContext？
3. 数据泄露：是否返回了 Entity 或打印了密码？
4. 同步阻塞：是否使用了 .Result 或 .Wait()？
5. 性能陷阱：是否在循环中查询了数据库 (N+1)？
6. 精度丢失：Long 类型的 ID 是否转为了 String？
7. 配置硬编码：是否直接写死了连接串或密钥？

17. .NET 10 / C# 14 现代语法最佳实践（增量）

2025 年推荐的 20 条语法规范，新增特性优先，保持极简。

1. field 关键字：属性内直接使用 field 处理后备字段，set => field = value.Trim();。
2. 空值条件赋值 ?.=：仅对象非空时赋值，减少 if。
3. 未绑定泛型 nameof：nameof(List<>) 获取泛型类型名，无需占位类型参数。
4. Lambda 参数修饰符：在 Lambda 中可用 ref/out/in 与默认参数，例如 (ref int x, int bonus = 10) => x += bonus;。
5. 主构造函数 (Primary Constructor)：服务/数据类优先 class Foo(IDep dep, ILogger<Foo> logger) { }。
6. record/required/init：DTO 默认用 record；关键属性用 required；不可变属性用 init。
7. 集合表达式与展开：使用 [] 创建集合，[..other] 拼接，str[1..^1] 进行切片。
8. 模式匹配：列表模式 [1, 2, .. var rest]、属性模式 { IsActive: true }、switch 表达式简化分支。
9. 文件范围命名空间/全局 using：减少缩进与重复引用；复杂泛型用别名。
10. 顶级语句：Program.cs 保持顶级语句风格。
11. 原始/UTF-8 字面量：多行文本用 """，性能场景用 "text"u8。
12. 不可变命令优先：命令/DTO 优先用 record 和 with 非破坏性拷贝，例如 command = command with { MerchantId = merchantId };，避免直接 command.Property = ... 带来的副作用。

（其余规则继续遵循上文约束：分层、命名、异步、日志、验证、租户/ID 策略等。）

18. .NET 10 极致性能优化最佳实践（增量）

侧重零分配、并发与底层优化，遵循 2025 推荐方案。

1. Span/ReadOnlySpan 优先：API 参数尽量用 ReadOnlySpan<char> 处理字符串/切片，避免 Substring/复制。
2. 栈分配与数组池：小缓冲用 stackalloc，大缓冲统一用 ArrayPool<T>.Shared，禁止直接 new 大数组。
3. UTF-8 字面量：常量字节使用 "text"u8，避免运行时编码。
4. 避免装箱：热点路径规避隐式装箱，必要时用 ref struct 约束栈分配。
5. Frozen 集合：只读查找表用 FrozenDictionary/FrozenSet，初始化后不再修改。
6. SearchValues SIMD 查找：Span 内多字符搜索用 SearchValues.Create(...) + ContainsAny。
7. 预设集合容量：List/Dictionary 预知规模必须指定 Capacity。
8. ValueTask 热点返回：可能同步完成的异步返回 ValueTask<T>，减少 Task 分配。
9. Parallel.ForEachAsync 控并发：I/O 并发用 Parallel.ForEachAsync 控制并行度，替代粗暴 Task.WhenAll。
10. 避免 Task.Run：在 ASP.NET Core 请求中不使用 Task.Run 做后台工作，改用 IHostedService 或 Channel 模式。
11. Channel 代替锁：多线程数据传递优先使用 Channels，实现无锁生产者-消费者。
12. NativeAOT/PGO/向量化：微服务/工具开启 NativeAOT；保留动态 PGO；计算密集场景考虑 System.Runtime.Intrinsics。
13. System.Text.Json + 源生成器：全面替换 Newtonsoft.Json；使用 [JsonSerializable] + 生成的 JsonSerializerContext，兼容 NativeAOT，零反射。
14. Pipelines 处理流：TCP/文件流解析使用 PipeReader/PipeWriter，获得零拷贝与缓冲管理。
15. HybridCache：内存+分布式缓存统一用 HybridCache，利用防击穿合并并发请求。

19. 架构优化（增量）

架构优化方案

1. Chiseled 容器优先：生产镜像基于 mcr.microsoft.com/dotnet/runtime-deps:10.0-jammy-chiseled，无 Shell、非 root，缩小攻击面，符合零信任要求。
2. 默认集成 OpenTelemetry：架构内置 OTel，统一通过 OTLP 导出 Metrics/Traces/Logs，避免依赖专有 APM 探针。
3. 内部同步调用首选 gRPC：微服务间禁止 JSON over HTTP，同步调用统一使用 gRPC，配合 Protobuf 源生成器获取强类型契约与更小载荷。
4. Outbox 模式强制：处理领域事件时，事件记录必须与业务数据同事务写入 Outbox 表；后台 Worker 轮询 Outbox 再推送 MQ（RabbitMQ/Kafka），禁止事务提交后直接发消息以避免不一致。
5. 共享资源必加分布式锁：涉及库存扣减、定时任务抢占等共享资源时，必须引入分布式锁（如 Redis RedLock），防止并发竞争与脏写。

---

Working agreements

• 严格遵循上述技术栈和命名规范。