根据参考文档修改一部分规范

03 - Coding & Frameworks/01 - Language Coding Specification/Python 编码与开发规范.md

@@ -21,6 +21,8 @@ Python 是一门极其灵活的动态语言，但“灵活”在大型团队协
       ...
 
 * **常量（Constants）：** 强制使用 SCREAMING\_SNAKE\_CASE（全大写加下划线），定义在模块顶部。  
+* **布尔语义命名：** 布尔变量与布尔返回值应使用 `is_`、`has_`、`can_`、`allow_` 前缀，避免语义歧义。  
+* **集合语义命名：** 列表、集合、查询结果变量应使用复数命名（如 `users`, `orders`, `permission_codes`）。  
 * **私有与受保护属性：** \* 单下划线 \_private\_var：表示内部使用（软性约束，仅作提示）。  
   * 双下划线 \_\_strict\_private：触发名称改写（Name Mangling），除非极特殊情况（如防止子类重写），**日常业务开发中不推荐使用**，以免增加调试难度。
 
@@ -90,6 +92,7 @@ class UserCreateRequest(BaseModel):
 
 * **禁止吞噬异常：** 绝不允许出现 except Exception: pass 这种掩耳盗铃的代码。  
 * **自定义异常层次：** 模块应当抛出特定业务领域的异常（如继承自 ValueError 的 OrderNotFoundError），而不是直接抛出裸露的 Exception。
+* **边界层错误策略：** 在 API、CLI、任务入口等边界层，应优先“抛异常并交由统一处理”，避免在底层函数中拼接错误响应字符串。
 
 ### **4\. 资源释放与安全**
 

03 - Coding & Frameworks/02 - Framework Development Specification/Django_DRF开发规范.md

@@ -18,6 +18,7 @@
 * **严禁重复造轮子**：Django 和 DRF 拥有极其成熟的第三方开源生态。对于标准化的通用需求，**必须**优先集成成熟的第三方库。例如使用 djangorestframework-simplejwt 处理 Token，使用 django-filter 处理复杂查询过滤。  
 * **代理层无状态**：若系统作为中间层代理外部 API（如大模型网关），代理视图禁止落库复杂的业务状态。  
 * **认证逻辑收口**：对接外部系统的身份认证逻辑（如 LDAP、API Key）必须严格收拢在 DRF 的 Authentication 类或 Django 的中间件中，**绝对禁止**在业务 View 中直接读取 Request Headers 做条件分流。
+* **认证冲突拒绝**：当请求同时携带多种互斥认证凭证时，必须直接拒绝并返回统一错误，禁止按优先级做隐式降级兼容。
 
 ## **数据层规范 (Models & Serializers)**
 
@@ -28,11 +29,15 @@
 * **显式定义主键与审计**：不推荐使用庞大的公共抽象基类隐式继承。业务 Model 应当显式定义主键和必备的审计字段（如 created\_at, updated\_at），避免基类变更带来全局副作用。  
 * **字段防空红线**：字符型字段（CharField, TextField）禁止设置 null=True，必须设为 default=''。  
 * **外键明确声明**：使用 ForeignKey 关联时必须显式指定清晰的 related\_name。  
+* **枚举字段规范**：枚举值优先使用 TextChoices 或 IntegerChoices，禁止散落硬编码字符串。  
+* **字段文档化**：核心业务字段应补充 help_text，以保障文档可读性与维护一致性。  
+* **索引基线**：高频过滤、排序与关联字段必须显式建索引，避免接口上线后暴露慢查询。  
 * **物理删除优先**：默认优先使用物理删除。仅当业务明确要求审计追溯时引入逻辑删除（is\_deleted）。若启用逻辑删除，必须配合使用带条件的唯一约束以防止重复插入冲突。
 
 ### **序列化层红线 (Serializers)**
 
 * **禁用全量暴露**：**严禁**在 Serializer 中使用 fields \= '\_\_all\_\_'。必须逐个显式列出对外暴露的字段，防止数据库新增敏感字段后发生意外泄露。  
+* **参数集中声明**：字段级约束（如 read_only、required、write_only）优先通过 Meta.extra_kwargs 集中配置。  
 * **严防 N+1 查询**：  
   * 列表接口**严禁**使用包含深层嵌套关系的复杂 Serializer，必须为其单独定义轻量级的结构。  
   * 若 Serializer 输出了外键字段，View 层的 QuerySet **必须**配合使用 select\_related 或 prefetch\_related。  
@@ -60,8 +65,24 @@ View 层仅作为路由调度、参数校验和权限决策的枢纽，绝不可
 ### **路由与异常处理**
 
 * **命名空间绝对隔离**：全局强制采用 NamespaceVersioning 机制。根路由必须携带命名空间，且内部的 urls.py 必须存在 app\_name。反向解析必须带版本号前缀。  
+* **URL 风格统一**：内部 REST 接口默认使用 kebab-case 与复数资源命名；第三方透传代理接口可按上游路径 1:1 保持。  
 * **异常抛出代替返回**：遇到业务校验错误，**严禁**在代码中手动 return Response({"error": "xxx"})。**必须**直接抛出异常（如 raise ValidationError），交由全局的 exception\_handler 统一格式化。  
 * **统一响应壳**：严禁在 View 中手动构建类似 {"code": 0, "data": ...} 的字典，必须交由自定义的全局 Renderer 统一包装。
+* **状态码语义化**：HTTP 状态码必须通过 `rest_framework.status` 常量引用，禁止直接写数字魔法值。
+
+## **分页与文档规范**
+
+* **默认分页策略**：常规列表接口默认使用 LimitOffsetPagination；仅在瀑布流、时间游标等场景使用 CursorPagination。  
+* **文档注解强制化**：所有自定义 Action 与非标准接口必须显式补充 `@extend_schema`（至少包含 summary、description、request、responses）。  
+* **透传接口说明**：代理第三方接口时，文档必须标注哪些字段为“上游原样透传”，避免接口语义歧义。
+
+## **查询性能与异步基线**
+
+* **N+1 防线**：开发阶段必须启用 N+1 监测手段（插件或测试守卫），出现问题即阻断合并。  
+* **批量操作优先**：批量写入与批量更新优先使用 `bulk_create` / `bulk_update`，禁止循环逐条写库。  
+* **大结果集迭代**：处理大表时优先使用 `iterator()` 或分批读取，避免一次性加载导致内存峰值过高。  
+* **异步边界清晰**：异步视图仅用于高并发 I/O 场景，CPU 密集计算必须下沉到任务队列或独立计算服务。  
+* **耗时任务剥离**：邮件、报表、第三方调用等明显耗时逻辑应通过异步任务框架执行，避免阻塞同步请求。
 
 ## **权限管控与数据隔离 (Permissions)**