From be6ee3d8806a6eedf94738d941e8912e794d988e Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Thu, 6 Aug 2026 16:22:30 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?=
 =?UTF-8?q?#8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../8-定义任务数据模型与-sqlite-repository.md | 69 +++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 docs/task/8-定义任务数据模型与-sqlite-repository.md

diff --git a/docs/task/8-定义任务数据模型与-sqlite-repository.md b/docs/task/8-定义任务数据模型与-sqlite-repository.md
new file mode 100644
index 0000000..5c9447c
--- /dev/null
+++ b/docs/task/8-定义任务数据模型与-sqlite-repository.md
@@ -0,0 +1,69 @@
+# 8 定义任务数据模型与 SQLite Repository
+
+- 类型：需求
+- 父级大工单：#1
+- 所属 MVP / 版本：#2 / MVP
+- 状态：已完成
+- 日期：2026-08-06
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/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 和差异检查通过 | 通过 |
+
+## 测试
+
+- 执行的命令：
+
+  ```powershell
+  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