TakeoutSaaS.AdminApi/0_Document/09_AI精简开发规范.md

编程规范_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；分页返回使用 PagedResult
• 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编程助手生成的代码必须符合本规范，并默认使用这些约束。