docs: merge AI guidelines and renumber documents

Document/08_AI精简开发规范.md

@@ -0,0 +1,145 @@
+# 编程规范_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 行的业务逻辑，必须分步注释：
+    ```csharp
+    // 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.  [ ] **配置硬编码**：是否直接写死了连接串或密钥？
+
+---

Document/09_AI精简开发规范.md

@@ -1,87 +0,0 @@
-# 编程规范_FOR_AI（TakeoutSaaS）
-
-说明：本规范为AI编程助手与开发者共同遵循的统一编码规范，结合 0_Document 下文档约定（特别是 06_开发规范.md、02_技术架构.md、12.* 规范）执行。超出本文件内容的详细条目请以文档中心为准。
-
-## 0. AI交互补充约束
-1. 每次回复必须回复中文。
-2. 不要更改我的文件编码。
-3. 每次修复bug或者新增完小功能必须提交git。
-4. 新创建的文件或者修改过的文件注释部分必须保持中文。
-5. 项目中不要有乱码。
-6. 在 PowerShell 查看文件时必须指定 UTF8（例如 Get-Content -Encoding UTF8 或设置 $OutputEncoding 为 UTF8），避免输出乱码。
-## 1. 技术栈
-- .NET 10 + ASP.NET Core Web API
-- EF Core 10（复杂关系/事务）+ Dapper（统计/批量）+ PostgreSQL 16+
-- Redis、RabbitMQ、Swagger、MediatR、Serilog、FluentValidation、AutoMapper、Hangfire、Polly
-
-## 2. 命名与风格
-- 类/方法/属性：PascalCase；接口：I前缀；私有字段：_camelCase；变量：camelCase；常量：PascalCase
-- 每文件仅1个公共类型，文件名与类型名一致
-- 命名空间与目录结构一致
-
-## 3. 分层与结构
-- 物理结构：Api（AdminApi/MiniApi/UserApi）+ Application + Domain + Infrastructure + Core(Shared.*) + Modules + Gateway
-- 不允许在Controller/Service中直接操作DbContext，必须通过仓储/应用服务
-- 返回DTO，禁止直接返回实体
-
-## 4. 注释与文档
-- 所有公共API、接口、复杂逻辑必须有XML注释
-- 控制器、服务方法提供简要说明与异常声明
-
-## 5. 异常与错误码
-- 使用 BusinessException（含ErrorCode）/ ValidationException；禁止吞异常
-- 全局异常中间件输出 ProblemDetails（扩展code与errors）
-- 错误码：400/401/403/404/409/422/500 + 业务10001+
-
-## 6. 异步与日志
-- 全面使用 async/await，禁止 .Result/.Wait()
-- 使用 Serilog 记录结构化日志，避免记录敏感数据
-
-## 7. 依赖注入
-- 统一使用构造函数注入，禁止服务定位器
-- 业务逻辑在应用层，仓储在基础设施层
-
-## 8. 数据访问
-- EF Core 10 负责关系/事务/迁移；Dapper 负责统计和大批量
-- 使用工作单元与仓储模式；避免N+1；只读查询使用AsNoTracking
-- 参数化查询，禁止字符串拼接SQL
-
-## 9. 多租户
-- 通过 Header:X-Tenant-Id 或 Token Claim: tenant_id 解析租户
-- EF Core 全局过滤（tenant_id）；写入数据时自动填充租户
-
-## 10. 安全
-- HTTPS、Security Headers、CORS按端配置
-- 授权：AdminApi 使用JWT+RBAC；MiniApi 小程序登录态+JWT
-- 严禁日志打印密码/支付信息等敏感数据
-
-## 11. API 设计
-- RESTful，统一 /api/{area}/v{version}
-- 统一返回：ApiResponse<T>；分页返回使用 PagedResult<T>
-- Swagger 按版本与端分组，开启鉴权按钮
-
-## 12. 模块化
-- 独立模块抽象：Identity、Authorization、Tenancy、Dictionary、Storage、Sms、Messaging、Scheduler、Delivery
-- 公共横切能力抽到 Shared.* 复用
-
-## 13. 测试
-- xUnit + Moq + FluentAssertions；命名：Method_Scenario_Expected
-- 核心业务覆盖率≥80%
-
-## 14. Git 提交
-- 使用 Conventional Commits：feat/fix/docs/style/refactor/perf/test/chore
-
-## 15. 性能
-- 投影查询、编译查询、批量操作（ExecuteUpdate/ExecuteDelete）
-- 缓存优先：Cache-Aside；更新后清缓存
-
-## 16. 禁止事项
-- 直接使用DbContext（绕过仓储/工作单元）
-- 硬编码配置（使用IOptions）
-- 返回实体类
-- SQL拼接注入风险
-- 吞异常或静默失败
-- 同步阻塞异步
-
-以上规范将随着文档中心的演进不断完善；AI编程助手生成的代码必须符合本规范，并默认使用这些约束。
-