# 编程规范_FOR_AI（TakeoutSaaS）

说明：本规范为AI编程助手与开发者共同遵循的统一编码规范，结合 0_Document 下文档约定（特别是 06_开发规范.md、02_技术架构.md、12.* 规范）执行。超出本文件内容的详细条目请以文档中心为准。

## 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编程助手生成的代码必须符合本规范，并默认使用这些约束。