# 新功能开发规范

## 一、命名规范
- APP 名称：`hertz_studio_django_xxx`，全小写，用下划线分隔
- Python 包与模块：全小写，短名称，避免缩写不清晰
- URL 命名空间：`app_name = 'hertz_studio_django_xxx'`
- 数据库表名：`Meta.db_table = 'hertz_xxx_model'`，避免与其他库冲突
- 迁移文件命名：描述性动词+对象，如 `0003_add_field_to_model`

## 二、项目结构与约定
- 标准结构：`apps.py`、`models.py`、`serializers.py`、`views.py`、`urls.py`、`admin.py`
- 静态资源：`media/<app_name>/...` 放置同路径资源以覆盖库静态文件
- 配置集中：在 `settings.py` 维护，使用前缀化大写变量（如 `YOLO_MODEL`）

## 三、接口返回规范
- 统一使用 `HertzResponse`（路径：`hertz_studio_django_utils/responses/HertzResponse.py`）
- 成功：
  ```python
  from hertz_studio_django_utils.responses.HertzResponse import HertzResponse
  return HertzResponse.success(data={'id': 1}, message='操作成功')
  ```
- 失败：
  ```python
  return HertzResponse.fail(message='业务失败')
  ```
- 错误：
  ```python
  return HertzResponse.error(message='系统错误', error=str(e))
  ```
- 验证失败：
  ```python
  return HertzResponse.validation_error(message='参数验证失败', errors=serializer.errors)
  ```
- 统一键：`success | code | message | data`，禁止返回非标准顶层结构

## 四、API 设计规范
- 路径语义化：`/models/`、`/detections/`、`/alerts/`
- 方法约定：`GET` 查询、`POST` 创建/动作、`PUT/PATCH` 更新、`DELETE` 删除
- 分页：请求参数 `page, page_size`；响应 `total, items`
- 过滤与排序：查询参数 `q, order_by, filters`；谨慎开放可排序字段

## 五、认证与授权
- 强制认证：业务敏感接口使用登录态（装饰器或 DRF 权限类）
- 权限控制：按用户/组/角色配置；避免在视图中硬编码权限
- 速率限制：对登录、验证码、检测等接口进行限流

## 六、日志与审计
- 请求审计：记录请求方法、路径、用户、响应码、耗时
- 业务事件：模型启用/删除、检测结果、告警变更记录
- 脱敏：对密码、令牌、隐私字段进行统一脱敏

## 七、配置约定
- 所有库配置集中在 `settings.py`，使用前缀化变量：
  - AI：`AI_MODEL_PROVIDER`、`AI_DEFAULT_MODEL`、`AI_TIMEOUT`
  - Auth：`AUTH_LOGIN_REDIRECT_URL`、`AUTH_ENABLE_OAUTH`
  - Captcha：`CAPTCHA_TYPE`、`CAPTCHA_EXPIRE_SECONDS`
  - Log：`LOG_LEVEL`、`LOG_SINKS`、`LOG_REDACT_FIELDS`
  - Notice：`NOTICE_CHANNELS`、`NOTICE_RETRY`
  - Monitor：`MONITOR_PROBES`、`MONITOR_ALERTS`
  - Wiki：`WIKI_MARKDOWN`、`WIKI_SEARCH_BACKEND`
  - YOLO：`YOLO_MODEL`、`YOLO_DEVICE`、`YOLO_CONF_THRESHOLD`
  - Codegen：`CODEGEN_TEMPLATES_DIR`、`CODEGEN_OUTPUT_DIR`

## 八、可扩展性（不改库源码）
- 视图子类化 + 路由覆盖：在项目中继承库视图并替换路由匹配
  ```python
  # urls.py
  from django.urls import path, include
  from your_app.views import MyDetectView
  urlpatterns = [
      path('yolo/detect/', MyDetectView.as_view(), name='detect'),
      path('yolo/', include('hertz_studio_django_yolo.urls', namespace='hertz_studio_django_yolo')),
  ]
  ```
- 猴子补丁：在 `AppConfig.ready()` 将库函数替换为自定义函数
  ```python
  # apps.py
  from django.apps import AppConfig
  class YourAppConfig(AppConfig):
      name = 'your_app'
      def ready(self):
          from hertz_studio_django_yolo import views as yviews
          from your_app.views import my_yolo_detection
          yviews.yolo_detection = my_yolo_detection
  ```
- Admin 重注册：`unregister` 后 `register` 自定义 `ModelAdmin`
- 信号连接：在 `ready()` 中连接库暴露的信号以扩展行为

## 九、示例：覆写 YOLO 检测返回值
- 目标位置：`hertz_studio_django_yolo/views.py:586-603`
- 最小替换示例（路由覆盖）：
  ```python
  from rest_framework.decorators import api_view, parser_classes
  from rest_framework.parsers import MultiPartParser, FormParser
  from django.contrib.auth.decorators import login_required
  from hertz_studio_django_utils.responses.HertzResponse import HertzResponse
  from hertz_studio_django_yolo.views import _perform_detection
  from hertz_studio_django_yolo.models import YoloModel, DetectionRecord
  import uuid, os, time, shutil
  
  @api_view(['POST'])
  @parser_classes([MultiPartParser, FormParser])
  @login_required
  def my_yolo_detection(request):
      # 复用库的流程，省略若干步骤，仅演示返回体差异化
      serializer = hertz_studio_django_yolo.serializers.DetectionRequestSerializer(data=request.data)
      if not serializer.is_valid():
          return HertzResponse.validation_error(message='参数验证失败', errors=serializer.errors)
      uploaded_file = serializer.validated_data['file']
      yolo_model = YoloModel.get_enabled_model()
      original_path = '...'  # 省略：存储原始文件
      result_path, object_count, detected_categories, confidence_scores, avg_confidence = _perform_detection('...', yolo_model.model_path, 0.5, 'image', yolo_model)
      processing_time = time.time() - time.time()
      detection_record = DetectionRecord.objects.create(
          original_file=original_path,
          result_file='...',
          detection_type='image',
          model_name=f"{yolo_model.name} {yolo_model.version}",
          model=yolo_model,
          user=request.user,
          user_name=request.user.username,
          object_count=object_count,
          detected_categories=detected_categories,
          confidence_threshold=0.5,
          confidence_scores=confidence_scores,
          avg_confidence=avg_confidence,
          processing_time=processing_time
      )
      return HertzResponse.success(
          data={
              'id': detection_record.id,
              'file': {
                  'result_url': detection_record.result_file.url,
                  'original_url': detection_record.original_file.url
              },
              'stats': {
                  'count': object_count,
                  'categories': detected_categories,
                  'scores': confidence_scores,
                  'avg_score': round(avg_confidence, 4) if avg_confidence is not None else None,
                  'time': round(processing_time, 2)
              },
              'model': {
                  'name': yolo_model.name,
                  'version': yolo_model.version,
                  'threshold': 0.5
              },
              'user': {
                  'id': getattr(request.user, 'user_id', None),
                  'name': request.user.username
              }
          },
          message='检测完成'
      )
  ```