# 背景
日常使用cursor时，发现有些措施可以使得代码提效的效率倍增（经实测，通常存在半个小时完成几天开发工作量情况），特此记录，方便后续持续优化



# cursor喜好
1. 对md格式相当友好
2. 对协议层、标准的代码、二进制理解友好
3. 对已经实现的部分参考实现友好（即新需求，建议先开始调研清楚后再看具体代码引入，大致要自己心里有个理解）
4. 可以让其写具体的开发文档，便于后续开发评审

# tips
1. rules
GPT增加cursor的rules配置
在项目根目录下增加.cursor/rules.md
如果是Django的，参考：
```js
# Cursor Rules - Python / Django 项目团队规范

## ✅ 基础代码规范
- 所有 Python 代码必须遵循 PEP8
- 变量、函数、方法使用 snake_case
- 类名使用 PascalCase
- 常量使用 UPPER_CASE
- 禁止无意义命名，如 a、b、tmp、test1
- 禁止提交 print 调试代码，使用 logging

## ✅ Django 项目结构规范
- apps/ 下每个模块是独立 Django APP，遵循 “单一职责”
- models 放在 models.py 或 models/ 目录
- serializers 放在 serializers.py
- views 放在 views.py 或 views/ 目录，不写业务逻辑
- 业务逻辑写在 services.py
- 工具类放在 common/utils
- 配置放在 config/，不可硬编码在业务中

## ✅ 数据库规范
- 所有模型字段必须写 verbose_name、help_text
- 必须开启 auto_now 或 auto_now_add 的时间字段
- 删除、更新尽量使用软删除
- QuerySet 操作必须捕捉异常，不能直接裸 try
- 不允许 N+1 查询，建议使用 select_related / prefetch_related

## ✅ API 接口规范（RESTful）
- 使用 DRF 编写 API
- 所有接口返回统一结构：

成功：
{
  "code": 0,
  "msg": "success",
  "data": {...}
}

失败：
{
  "code": 非0,
  "msg": "错误信息"
}

- 分页接口必须返回 total / page / page_size
- 不允许返回内部异常堆栈
- 所有接口必须有权限控制 （IsAuthenticated 或自定义权限）

## ✅ 注释规范
- 所有类、方法必须包含 docstring
- 函数必须写入参数说明、返回值说明
- 写关键业务逻辑时必须加注释
- 注释要说明 “做什么 + 为什么” 而不是“代码翻译”

## ✅ 依赖与环境规范
- 依赖固定在 requirements.txt
- 开发/生产分离：settings/dev.py、settings/prod.py
- 禁止将敏感信息（密码、密钥、URL）写死，必须使用环境变量
- migrations 必须提交

## ✅ Git 规范（遵循 Conventional Commit）
- feat: 新功能
- fix: 修 bug
- docs: 文档
- style: 格式（不影响逻辑）
- refactor: 重构（不影响功能）
- test: 测试
- chore: 构建、脚本、依赖管理

示例：
feat: add user login API
fix: fix token expire bug
refactor: move business logic to service layer

## ✅ 单元测试
- 所有 API 必须写测试
- 覆盖率不低于 70%
- 测试命名为 test_xxxx.py
- 必须断言 status_code 和返回结构

## ✅ 日志规范
- 用 logging，不用 print
- 错误级别必须包含上下文信息
- 不输出敏感数据（密码、token、手机号明文）

## ✅ 安全规范
- 表单和接口必须进行参数校验
- 禁止 SQL 拼接
- 密码必须加盐存储
- Token 必须带过期时间
- 不返回敏感数据（密码、ID卡号、密钥）

## ✅ 其他
- 遇到不确定实现方式，优先选择 Django 官方推荐实践
- 代码尽量可读、可维护、可测试，而不是“能跑就行”

```

2. 跨项目代码使用，可以直接把需要的项目放到当前项目下，然后chat中，使用@引入所需要的部分，加上描述使用，最后是有参考某某实现

```js
参考a2l文件的解析逻辑，这个页面http://localhost:8086/#/file/data/list?current=2&pageSize=20
调用解析逻辑时，参考后端Django的接口：class DataFileViewSet(ModelViewSet):
@action(detail=True, methods=['post'], url_path='parse-hex-data')
    def parse_hex_data(self, request, pk=None)
@src 
```

3. 如果是word或PDF等其他形式的文档，需要转换为md格式再使用@引入，加上描述，目的

```js
@hex_client.py 根据地址具体是怎么分析出来最终的物理值的？给出详细的分析过程
```

4. 如果直接指定模型使用，发现有时会特别轴，比如指定sonnet 4.5时（跟他说了几遍，注意事项和需求等还是会犯同样的问题），现在都是setting设置models圈定范围，默认AUTO即可

5. 如果跨不同IDE使用，即apk开发、iOS开发等，建议使用cursor描述开发，调试用对应的IDE，比如Android Studio调试

6. 多看极客时间相关课程，看看业界对这块使用的方式，对比自己的方式

7. 直接选中命令行或输出窗口中的情况（Add to chat），告知chat处理

```js
@Python (162-307) @a2l_client.py 存在很多乱码的情况，麻烦修复
```
8. 针对已经成熟模块的改动，建议分拆成一定模块来问，附带测试进行，避免引入新bug


# 为啥要优先AI编程
1. 可以基于已经存在的代码，快速实现，尤其是类似的；
2. 由于设定了rules，会默认按照最官方的方式实现，最标准，和不容易踩坑；
3. 不用完全熟悉具体底层实现，只需要知道大概需要用到什么即可，不需要自己想代码实现；
4. 联动上下游的，使用AI不容易忘记且少硬编码实现；

# 效率分析
业界某公司调研分析为：cursor 40%；copilot 35% 其他忽略不计

经内部日常使用分析，cursor起码能到80%以上的代码编写，尤其是新项目，或参考类似的、官方的实现；

1. hex解析、a2l解析，cursor实现了90%以上的代码，1个小时，顶起码一周的工作量；（分析了类似协议的实现，需要至少2周以上，但是cursor+清晰文档md化后，1个小时就可以实现绝大部分类型协议的实现，经测试无误）
2. 日常接口新增字段，抽象类型定义及工具类的实现，cursor半个小时内可以解决起码要写一个早上的代码效果工作量；

cursor提效tips

# 理解
临时把当前修改藏起来，恢复工作区干净，以便切分支或拉代码

# 深度理解
stash 会保存什么？

默认会保存：
✅ 工作区已修改但未提交的文件
✅ 暂存区里的文件（git add 过的）

不会保存：
❌ 未被 git 追踪的新文件（除非用特殊参数）

# 高频命令操作

1. 查看所有 stash 内容

```js
git stash list
```

你会看到类似：

```js
stash@{0}: WIP on develop: 1234567 修复接口
stash@{1}: WIP on master: UI调整
```


✅ 2. 恢复（取出并删除 stash）

把最新的 stash 应用到当前分支：

```js
git stash pop
```


应用并删除 stash@{0}

如果有冲突，解决后再 git add + git commit

✅ 3. 恢复但不删除 stash（保险一点）

```js
git stash apply
```
应用 stash

stash 记录仍保留（更安全）

✅ 4. 恢复指定 stash

例如恢复第 1 个：

```js
git stash apply stash@{1}
```

若要恢复并删除：

```js
git stash pop stash@{1}
```



git stash

# 背景
我从remote_calibration分支合并到develop分支时，提示： 

```js
Merge request cherry-pick failed: Can't perform this action automatically. It may have already been done, or a more recent commit may have updated some of this content. Please perform this action locally.
```
# 理解
意思是：GitLab 在尝试把 remote_calibration 分支的变更自动合并（或 cherry-pick）到 develop 分支时失败了，需要你在本地手动处理冲突。这种情况通常发生在：

✅ 同一段代码被两个分支改动了

✅ 分支之间有冲突文件

✅ 已经有人做过部分 cherry-pick/merge

✅ GitLab 无法自动确认冲突如何解决

# 解决
直接cursor处理

更新分支：

```js
git checkout develop && git pull
git checkout remote_calibration && git pull
```

本地尝试合并：

```js
git checkout develop
git merge remote_calibration
```

用 git status 查看具体冲突

打开冲突文件并手动解决

会提示是否直接界面解决，同意后，界面合并即可，然后提交

合并完成后：
基于develop创建新分支然后合并到develop即可

git add .
git commit
git push origin develop




代码冲突解决

# 背景
由于celery最小只能到分钟级别，但是日常有需要每隔10秒同步一遍获取远程系统能力

# 实现

```python3
""" Auto reload celery runner script
Usage: python manage.py sync_perms
See: https://stackoverflow.com/a/49166246/2544762
"""
import signal
import traceback
from datetime import datetime
from logging import getLogger
from time import sleep
from typing import Dict

from django.apps import apps
from django.conf import settings
from django.core.management.base import BaseCommand

from mobile.tasks import job_watch_sonic_devices

logger = getLogger(__name__)


class Command(BaseCommand):
    def handle(self, *args, **options):
        # 退出标记
        flag_terminate = False

        # 退出信号处理（Ctrl + C），使得可以正常结束不用 kill
        def signal_handler(signal, frame):
            nonlocal flag_terminate
            flag_terminate = True

        signal.signal(signal.SIGINT, signal_handler)
        signal.signal(signal.SIGTERM, signal_handler)

        # 死循环轮询定时任务
        while not flag_terminate:
            logger.info(f'定时任务开始执行：{datetime.now().strftime("%Y-%m-%d %H:%M:%S")}')
            try:
                job_watch_sonic_devices()
            except Exception as e:
                print(f'watch sonic e: {e}')
                traceback.print_exception(e)
            # 整体执行时间需要2秒，这里设置8秒，基本10秒内一个轮回
            sleep(8)

```
## 1、信号处理

```python3
signal.signal(signal.SIGINT, signal_handler)
signal.signal(signal.SIGTERM, signal_handler)
```
捕获 Ctrl + C (SIGINT) 和 终止信号 (SIGTERM)。

使用 nonlocal flag_terminate 让信号处理函数能修改外部变量，确保可以优雅退出循环，而不是被强制 kill。

优点：

运行中按 Ctrl+C 可以安全结束（会在下个循环退出）。

避免直接 kill -9 导致状态不一致。


```python3
flag_terminate = False

def signal_handler(signal, frame):
    nonlocal flag_terminate
    flag_terminate = True

```
### 底层流程（信号机制是怎么帮忙的）：
当用户 Ctrl+C（SIGINT）或 kill（SIGTERM）时，不是立刻杀掉进程，而是执行 signal_handler：

把 flag_terminate 设成 True。

主循环每轮都会检查 flag_terminate：

如果 True，退出循环，任务结束前可以优雅清理（比如保存状态、断开连接）。

这样：

正在执行的那一轮任务会先跑完。

然后在下一轮循环检查到退出标志，再干净地退出。

### 简单理解：

信号处理就是给死循环任务加了一个“安全刹车”，让你按下 Ctrl+C 时，不是直接翻车，而是慢慢停下来。

### 是否同步？
如果只看 Python 解释器层面，当收到信号时，信号处理函数（signal_handler）的执行是同步的。

解释器会在执行字节码的“安全点”检测是否有挂起的信号：

如果有，就暂停当前的 Python 代码执行；

同步调用你注册的 signal.signal(...) 处理函数；

处理函数执行完后，回到原来的位置继续执行

## 2、技术要点总结

- 自定义 Django 管理命令：可直接用 python manage.py <command> 启动，不依赖外部调度器。
- 信号安全退出：通过 signal.signal + 外部变量标志实现优雅退出。
- 异常隔离：任务出错不会中断整个进程。
- 简单定时调度：用 sleep() 模拟固定周期调度（适合简单场景，不适合精确到秒的生产任务）。
- 日志追踪：方便监控执行情况。
- 可替代 Celery beat：适合轻量任务或测试环境，但在高并发/分布式场景下不如 Celery 稳定

django中增加manage.py拉起命令及信号机制

# 背景
日常多表查询时，容易引入脏数据，需要删除多表中脏数据，减少直接操作DB的工作量

# model层代码分析
假设有表如下：

TestTaskPackagePluginApplianceRel 中间表，挂钩插件包和插件设备

TestTaskPackage 插件包

TestTaskPluginAppliance 插件设备

```python3
from django.db import transaction
class TestTaskPackage(UUIDModel, DatedModel):
    ...
    
    def delete_with_related(self):
            """删除当前 TestTaskPackage 及其关联的 TestTaskPluginAppliance 和中间表记录"""
            with transaction.atomic():

                # 先查出来关联TestTaskPluginAppliance的记录并强制评估为列表
                appliance_ids = TestTaskPackagePluginApplianceRel.objects.filter(test_task_package=self).values_list(
                    'test_task_plugin_appliance_id', flat=True
                )
                appliances = list(TestTaskPluginAppliance.objects.filter(id__in=appliance_ids))

                logger.info(f'appliances: {appliances}')

                # 删除中间表中的记录
                rels = TestTaskPackagePluginApplianceRel.objects.filter(test_task_package=self)
                for rel in rels:
                    logger.info(f"Deleting relation: {rel}")
                    rel.delete()

                # 删除关联的 TestTaskPluginAppliance
                # logger.info(f'appliances after: {appliances}')
                for appliance in appliances:
                    logger.info(f"Deleting appliance: {appliance}")
                    appliance.delete()

                # 删除当前 TestTaskPackage
                logger.info(f"Deleting TestTaskPackage: {self}")
                self.delete()

```
## 1、事务管理 (transaction.atomic)

```python3
with transaction.atomic():
```
作用：把代码块中的数据库操作放在同一个事务里执行。

好处：

如果中间任何一步抛异常，所有已执行的 SQL 都会回滚，保证数据一致性。

避免出现删除了一部分关联记录但没有完全清理干净的情况

## 2、多对多/外键关联查询 (filter + values_list)

```python3
appliance_ids = TestTaskPackagePluginApplianceRel.objects.filter(
    test_task_package=self
).values_list('test_task_plugin_appliance_id', flat=True)

```
filter：筛选出中间表 TestTaskPackagePluginApplianceRel 中，关联到当前 TestTaskPackage 的记录。

values_list(..., flat=True)：直接取出字段值列表（只要一个字段时 flat=True 才能得到一维列表）。

这里的用途：先获取所有相关的 TestTaskPluginAppliance ID，方便后面批量删除

## 3、强制转换到内存 QuerySet (list(...))

```python3
appliances = list(TestTaskPluginAppliance.objects.filter(id__in=appliance_ids))
```
jango 的 QuerySet 是惰性执行的（lazy evaluation）。

用 list(...) 会立刻执行 SQL 查询，把结果加载到内存中。

这样做的原因：

后续删除中间表记录时，这些对象仍然能在内存中访问，避免因级联删除或 QuerySet 变化导致数据不一致。

# views层

```python3
class TestTaskPackageViewSet(viewsets.ModelViewSet):
    queryset = m.TestTaskPackage.objects.all()
    serializer_class = s.TestTaskPackageSerializer
    filter_fields = '__all__'
    ordering = ['-pk']
    permission_classes = [ActionBasedPermission]
    action_permissions = {
        'list,retrieve': IsMember,
        'create': IsMember,
        'update,partial_update,destroy,delete_with_related':
            IsMember |
            UserWithCondition.build(lambda u, o: u == o.author),
    }
    
    @action(methods=['POST'], detail=False)
    def delete_with_related(self, request):
        """删除指定的 TestTaskPackage 及其关联的记录"""
        from rest_framework import status
        try:
            test_task_id = request.data.get('test_task_id')
            logger.info(f'test_task_id: {test_task_id}')
            test_task_package = (m.TestTaskPackage.objects.filter(test_task_id=test_task_id,
                                                                  package_type=m.TestTaskPackage.TYPE_PLUGIN_PACKAGE).
                                 order_by('date_created').first())
            logger.info(f'test_task_package: {test_task_package}')
            # 检查 test_task_package 是否为空
            if not test_task_package:
                return Response(
                    {'status': 'info', 'message': '当前没有关联任何插件包，跳过删除操作。'},
                    status=status.HTTP_200_OK
                )
            test_task_package.delete_with_related()
            return Response(
                {'status': 'success', 'message': 'TestTaskPackage and related records deleted successfully.'},
                status=status.HTTP_204_NO_CONTENT)
        except Exception as e:
            return Response({'status': 'error', 'message': str(e)}, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
```

# 测试层分析

```python3
from XXX.models import GrpcMemberProxy

from django.test import TestCase
from plugin_test import models as m
import uuid
from datetime import datetime


class TestTaskPackageModelTest(TestCase):

    def setUp(self):
        # 创建一个 TestTaskPackage 实例
        author = GrpcMemberProxy(username='abc')
        self.test_task_package = m.TestTaskPackage.objects.create(
            id=uuid.uuid4(),
            test_task_id=uuid.uuid4(),
            mobile_device_id=123456789,
            file_md5='dummy_md5',
            author=author
        )

        # 创建一个 TestTaskPluginAppliance 实例
        self.test_task_plugin_appliance = m.TestTaskPluginAppliance.objects.create(
            name='Test Appliance',
            appliance_code='dummy_code',
            sn='dummy_sn',
            bt_mac='dummy_bt_mac',
            enterprise_name='Dummy Enterprise',
            appliance_type='Dummy Type',
            enterprise_code='dummy_ent_code',
            cat_code='dummy_cat_code',
            sn8='dummy_sn8',
            develop_group_name='Dummy Group',
            product_code='dummy_product_code',
            wifi_version='dummy_wifi_version',
            register_time=datetime.now(),  # 提供当前时间作为注册时间
            a0='dummy_a0',
            prd_name='Dummy Product',
            prd_id='dummy_prd_id',
            model_type='dummy_model_type',
            access_method='dummy_access_method',
            source='dummy_source',
            product_code_in_app_svc='dummy_product_code_in_app_svc',
            smart_product_id=1,
            prd_info={},  # 提供一个空字典作为默认值
            prd_id_on_spid='dummy_prd_id_on_spid'
        )

        # 创建一个中间表记录
        m.TestTaskPackagePluginApplianceRel.objects.create(
            test_task_package=self.test_task_package,
            test_task_plugin_appliance=self.test_task_plugin_appliance
        )

    def test_delete_with_related(self):
        # 确保中间表记录存在
        self.assertEqual(m.TestTaskPackagePluginApplianceRel.objects.count(), 1)
        # 确保 TestTaskPluginAppliance 记录存在
        self.assertEqual(m.TestTaskPluginAppliance.objects.count(), 1)

        # 调用 delete_with_related 方法
        self.test_task_package.delete_with_related()

        # 检查所有相关记录是否被删除
        self.assertEqual(m.TestTaskPackage.objects.filter(id=self.test_task_package.id).count(), 0)
        self.assertEqual(m.TestTaskPluginAppliance.objects.filter(id=self.test_task_plugin_appliance.id).count(), 0)
        self.assertEqual(m.TestTaskPackagePluginApplianceRel.objects.count(), 0)

```

## 1、jango.test.TestCase
```python3
class TestTaskPackageModelTest(TestCase):
```
继承自 django.test.TestCase，意味着：

每个 test_ 方法运行前都会新建一个测试数据库（事务隔离）。

每个测试方法运行后会回滚数据库，不影响其他测试。

运行速度快且测试之间数据互不干扰。

## 2、setUp 阶段

```python3
def setUp(self):
```
setUp 会在每个测试方法执行前自动运行，用来准备测试数据。

## 3、中间关联表
```python3
m.TestTaskPackagePluginApplianceRel.objects.create(
    test_task_package=self.test_task_package,
    test_task_plugin_appliance=self.test_task_plugin_appliance
)
```
建立 TestTaskPackage 和 TestTaskPluginAppliance 的关联关系。

这相当于多对多关系的“中间表”。

数据库里现在三张表各有一条相关记录。

## 4、流程总结
1）准备数据（setUp）

插入一条包记录、一条设备记录、一条中间表记录。

2）验证初始状态

确认数据已按预期插入。

3）执行删除方法

调用 delete_with_related()。

4）验证最终状态

所有关联数据都被删光。

5）测试结束回滚

Django 自动清空测试数据库，准备下一个测试

# vue2前端要点
template
```js
<i-button class="btn" v-if="me.is_superuser" @click="clearTaskRelated()" :type="'error'" :disabled="!me.is_superuser">脏数据清除</i-button>
```
    
script
```js
// 脏数据清除（物模型插件任务/关联表/插件设备表）
    async clearTaskRelated() {
      const vm = this;

      // 显示确认弹窗
      await vm.$confirm('您确定要删除该任务及其关联的数据吗？此操作不可撤销!!!')

      try {

        // 调用后端删除接口
        const deleteResp = await vm.api('test_task_package').showLoading(false).post({
          action: 'delete_with_related'
        }, {
          test_task_id: vm.$route.query.task
        });

        // 检查删除操作的响应
        if (deleteResp.status === 204) {
          vm.$Message.success({
            content: '任务及其关联数据已成功删除。',
            duration: 3
          });
        } else {
          vm.$Message.error({
            content: deleteResp.data.message,
            duration: 5
          });
        }
      } catch (error) {
        console.error('Error:', deleteResp.data.message);
        vm.$Message.error({
          content: '操作失败，请检查网络连接或稍后重试。',
          duration: 5
        });
      }
    }
```
## 1、调用后端 delete_with_related Action：

第一个参数 { action: 'delete_with_related' } → 这是后端的 DRF Action 调用方式。

第二个参数 { test_task_id: vm.$route.query.task } → 把任务 ID 传给后端。

showLoading(false)：

禁用全局 loading 动画。

设计要点：

test_task_id 从 URL query 参数中获取（this.$route.query.task），无需额外输入。

API 请求是 POST，符合 DRF @action(methods=['POST']) 要求。

## 2、技术要点总结
1）操作前确认：用弹窗防止误删，明确提示危险操作。

2）API 调用模式：

链式调用 (vm.api(...).showLoading(false).post(...))。

动作参数 { action: 'delete_with_related' } 对应 DRF 自定义 Action。

3）参数传递：test_task_id 来自 URL query，确保接口参数和后端匹配。

4）状态码处理：

204 表示删除成功。

其他状态用后端返回的 message 提示用户。

5、异常处理：

捕获请求错误，防止 UI 卡死。

提示用户并记录日志。
