cmautobuy/docs/task/8-定义任务数据模型与-sqlite-repository.md

8 定义任务数据模型与 SQLite Repository

• 类型：需求
• 父级大工单：#1
• 所属 MVP / 版本：#2 / MVP
• 状态：已完成
• 日期：2026-08-06
• Gitea 工单：#8

背景与目标

SQLite v1 已能初始化，但 Python 代码还没有稳定的数据对象和数据库访问入口。本任务用简单数据类表达数据库含义，并通过 Repository 集中管理任务和非敏感设置 SQL，避免 UI、Admin 和自动化代码直接操作数据库。

最终方案

• 保持 client/src 扁平文件结构，不引入 ORM 或第三方测试框架。
• 使用字符串枚举定义任务类型、任务状态、执行状态及 Outbox 状态，枚举值与 SQLite CHECK 约束一致。
• 使用 dataclass 定义新领取任务、任务摘要、任务详情、执行记录、Outbox 事件和应用设置记录。
• TaskRepository 提供新领取任务写入、分页查询、筛选计数和详情读取。
• 新任务状态固定为 claimed；重复 remote_task_id 抛出明确错误且不覆盖已有数据。
• 列表查询不读取 admin_payload 和 pdd_data，详情查询才解析完整 JSON。
• 类型、状态和关键词筛选采用 AND；关键词同时搜索任务编号、商品编号和标题，并把 %、_ 当普通输入处理。
• SettingsRepository 使用 JSON 保存非敏感设置，支持默认值、新增、读取、更新和删除。
• 每个 Repository 方法自行打开和关闭连接，不共享跨线程连接。

改了哪些

• client/src/task_models.py：新增任务、执行、Outbox 和设置数据对象及枚举。
• client/src/task_repository.py：新增任务写入、分页筛选、计数和详情读取。
• client/src/settings_repository.py：新增非敏感设置 JSON CRUD。
• client/test/test_task_repository.py：新增任务模型和 Repository 测试。
• client/test/test_settings_repository.py：新增设置 Repository 测试。

验收结果

验收标准	结果
状态枚举值与 SQLite v1 约束一致	通过
数据模型不依赖 Qt、Admin 或 uiautomator2	通过
新领取任务以 claimed 状态写入	通过
重复任务编号不会覆盖已有记录	通过
分页按 updated_at DESC, id DESC 稳定排序	通过
类型、状态和关键词筛选采用 AND	通过
列表摘要不读取完整 JSON，详情能还原 JSON	通过
能统计筛选后的任务数量	通过
设置支持 JSON 新增、读取、更新、删除和默认值	通过
测试只使用临时数据库	通过
语法、unittest 和差异检查通过	通过

测试

• 执行的命令：

  C:/Python310/python.exe -m py_compile src/task_models.py src/task_repository.py src/settings_repository.py test/test_task_repository.py test/test_settings_repository.py
  C:/Python310/python.exe -m unittest discover -s test -p "test_*.py" -v
  

• 结果：新增测试与已有 SQLite 初始化测试合计 17 项全部通过，输出 Ran 17 tests ... OK；git diff --check 通过。

• 没验证到的部分：没有连接真实 UI、Admin 或 Android 设备；没有实现任务状态转换、任务执行记录写入、结果与 Outbox 同事务保存；没有进行多线程并发和真实 client/data/client.db 测试。

遗留问题

• 下一单元任务把 PDD 表格的查询、筛选、刷新和分页接到 TaskRepository。
• 任务执行与 Outbox 工单再补充状态转换和可靠事务方法。

相关提交

• e60b0c9 定义任务模型与 SQLite Repository