CAMPUS RESOURCE ORGANIZER · M1 / M2 / M3
把排错与数据结构连成一个可用工具
用 Python 标准库构建虚构资料元数据的命令行整理器:按 ID 增删改查、独立预览、分类和标签筛选,以及可以跨进程恢复的 JSON 文件保存。
当前交付到 M3 SQLite 与事务导入。浏览器只提供教学模型,真实数据库由本地 Python 工程运行。程序不扫描、移动或删除真实资料文件。
从独立快照或 M1 起始包开始
每项任务都有独立起点;六项沿用同一字段契约与业务模块。M1 起始包保留明确列出的待修故障,不是已完成作品。
python check_environment.py python -m unittest discover -s tests -v python cli.py --data ./my-data/resources.json
Python 3.11+,无第三方依赖。Windows 也可用 py -3,POSIX 常用 python3;实际验证的平台和版本以包内说明为准。
M1 的保存与退出规则
- 启动时按固定工程位置读取默认 JSON;--data 显式指定文件。只有文件不存在才初始化空项目,空文件、损坏内容和版本不匹配应报错退出。
- 增删改先改变内存并标记未保存;预览和查询不自动保存。显式 save 才写盘,quit 在有改动时选择 save、discard 或 cancel。
- 保存使用同目录临时文件后替换;失败时保留当前内存和未保存状态,旧磁盘文件不变。修复环境后可重试或 save 到另一明确路径。不承诺断电场景的完整持久性。
list
add {"title":"Week 1","category":"CS","tags":["notes"]}
status
save
filter {"category":"CS"}
quit新增返回稳定 ID;update、remove 和 preview 使用 ID。标题按去首尾空白再 casefold() 去重。完整命令和错误示例见中英文 README。
验收自己的作品
- 运行六项公开测试与完整回归:失败输入不留下部分记录,预览和筛选不修改原集合。
- 在临时数据目录保存后真正结束进程,再从另一个工作目录启动同一个数据文件,核对 ID、标题和标签。
- 用坏 JSON、空文件、版本不匹配和可复现的替换失败验证错误路径;始终保留源文件,不对真实资料操作。
独立改需求与交付
自行增加“按标签筛选”,写一个能发现原地筛选错误的反例。说明 Python、Git、编辑器和 AI 分别帮助了什么,保留一次修复前后差异。请同学在新目录按 README 运行,记录实际卡点;不要把下载当作已安装或已掌握。
M2 · STACK / QUEUE / INDEXES
数据结构版:撤销、顺序批检查与索引
在 M1 的同一业务契约上增强:成功新增、修改、删除保存独立历史快照,撤销最近一次成功修改;批检查队列只生成报告,不自动入库;ID 与规范化标题索引随增删改和撤销更新,加载后从主集合重建。
python -m unittest tests.test_d01 tests.test_d02 tests.test_d03 -v python -m unittest tests.test_m2_integration -v python -m unittest discover -s tests -v python cli.py --data ./my-data/resources.json
- 历史、队列尝试与检查报告只在本次会话保留,不做重做或跨重启撤销。失败操作不写历史,每次撤销只恢复最近一次成功修改。
- 每个入队尝试最多消费一次;失败后继续下一项,显式重试创建新尝试。队列不模拟多线程或消息中间件;环形队列只用于受控实验。
- 撤销改变内存并标记未保存;保存失败保留数据、历史、索引与 dirty 状态,原盘不变。队列检查不更改资料集,不清除未保存状态。
列表尾部追加是均摊成本,整个撤销还含快照和索引维护;Python dict 的平均查找成本有假设、最坏可退化,重建和键规范化成本另算。不要用一次浏览器耗时证明复杂度。
M3 · SQLITE / TRANSACTIONS / DELIVERY
M3:替换存储,保留业务契约
M3 是校园资料整理器的数据库与交付阶段,不是另一套应用。业务规则、稳定 ID、撤销和索引保持同一契约,只替换本地存储并加入一次 JSON 导入。先在临时目录用虚构资料验证,再交给同学按说明运行。
- JsonStore/SQLiteStore.load/save 通过同一套业务契约;CLI 用 --storage json|sqlite 显式选择。缺少 sqlite3 时明确失败,不静默回退后仍称数据库阶段完成。
- SQLite 保存稳定 ID、原始标题、Python strip().casefold() 规范化标题、分类和 JSON 编码的标签。ID 为主键,规范化标题有 UNIQUE 约束;position 保存列表顺序,加载显式 ORDER BY position,业务字段仍须先验证。
- JSON 输入 schemaVersion=1,SQLite PRAGMA user_version=1。加载不存在的数据库不创建文件;已有空文件、未知/不兼容版本或坏库明确拒绝。仅新建存储时初始化,不宣称自动升级已有版本。
- SQLiteStore.import_json(source_path) 先完整验证记录、ID 和规范化标题唯一性。CLI import-json PATH 仅限 SQLite 且当前无未保存修改;目标须为新路径或已识别的空库,整批一个事务,失败回滚且源 JSON 不变。
- 重复执行导入时,若数据库已有数据则明确拒绝,不做隐式覆盖或合并。合法空输入导入 0 条,但仍可能新建数据库并提交事务;原集合、历史、索引和未保存提示只在实际保存成功后按契约更新。
- 真实验收用临时数据库文件、第二个进程、另一个工作目录和可复现故障注入。网页轨迹没有执行 SQL、本地代码或数据库文件,也不能远程证明学生测试通过。
python check_environment.py python -m unittest tests.test_storage_contract tests.test_sqlite_storage tests.test_sqlite_import -v python -m unittest discover -s tests -v python cli.py --storage sqlite --data ./my-data/resources.sqlite3
- 先运行 M2 的 JSON 回归,记录 Python、操作系统和 sqlite3.sqlite_version;若 import sqlite3 失败,按环境说明修复并保留诊断,不换存储冒充完成。
- 建立 SQLite 存储实现,显式打开目标文件,检查版本,建表并声明约束。沿用资料包实际帮助中的 --storage json|sqlite 与数据路径参数;查询和预览不自动保存。
- 实现参数绑定和标签 JSON 序列化,按同一业务契约加载/保存。使用独立事务控制,成功后提交,失败时回滚并保留内存及未保存状态,最后关闭连接。
- 读取源 JSON 但不修改它;先全量验证,再检查空目标,在同一个事务内导入。成功后保留真实报告 count/source/target/schemaVersion/result;count 是完整提交并发布后的条数。失败保留错误输出,报告模板保持 not_run 或填写失败说明,不伪造 success。
- 对两个存储运行相同行为测试;给导入第二条插入或提交注入失败,核对旧数据库和源文件保持原内容。补测重复 ID、规范化重名、坏字段、版本不兼容、空输入和再次导入。
- 从新目录和第二个进程复现保存恢复。交付源码、虚构样例、双语 README、真实测试结果、修复差异、独立变式、本人/AI 分工说明,以及同学按 README 运行的反馈。
status import-json ./data/sample.json list save quit
import-json 仅 SQLite 且当前会话无未保存修改时可用。导入会直接在一个事务中写盘,成功后更新内存与索引并清空会话历史/队列。它不同于先修改内存再显式 save 的日常编辑。
SQLite 与 SQL 桥接
连接与环境:sqlite3 是 Python 的可选标准库模块;它连接本地文件,不需要 MySQL 服务。用实际环境记录 SQLite 运行时版本,并显式关闭连接。
import sqlite3
print(sqlite3.sqlite_version)
connection = sqlite3.connect(database_path, isolation_level=None)
try:
pass
finally:
connection.close()建表与约束:显式 NOT NULL、稳定 ID 主键、规范化标题 UNIQUE。标签用 Python json.dumps/json.loads 存成 TEXT,不要求 SQLite JSON 扩展。数据库唯一约束不替代 Python 类型与业务校验。
CREATE TABLE documents (
position INTEGER NOT NULL UNIQUE CHECK(position >= 0),
id TEXT NOT NULL PRIMARY KEY,
title TEXT NOT NULL,
normalized_title TEXT NOT NULL UNIQUE,
category TEXT NOT NULL,
tags_json TEXT NOT NULL
);参数绑定:用 ? 占位符传值,不把标题拼进 SQL。normalized_title 在 Python 中用 title.strip().casefold() 得到;SQLite NOCASE/LOWER 不能直接当作此 Unicode 规则的等价实现。
import json
connection.execute(
"INSERT INTO documents (position, id, title, normalized_title, category, tags_json) "
"VALUES (?, ?, ?, ?, ?, ?)",
(position, record["id"], record["title"], record["title"].strip().casefold(),
record["category"], json.dumps(record["tags"], ensure_ascii=False)),
)显式事务:此示意使用 isolation_level=None,再显式 BEGIN IMMEDIATE;所有插入后一起提交,异常时回滚。BEGIN 也可能因占用等原因失败;真实代码要检查状态、报告错误并关闭连接,不把数据库错误当空库。
connection.execute("BEGIN IMMEDIATE")
try:
for record in validated_records:
insert_one(connection, record)
connection.commit()
except Exception:
if connection.in_transaction:
connection.rollback()
raise版本:本项目首版为 1。PRAGMA user_version 是应用管理的整数,不会替你迁移表。本项目还核对 application_id=0x5A4D4333、确切表约束和默认 DELETE 日志格式;仅版本号相同不足以认定是本项目数据库。只在新建数据库且完成初始化时设为 1;已有空文件或不支持版本明确拒绝。下面只展示读取与固定版本赋值,不是升级实现。
version = connection.execute("PRAGMA user_version").fetchone()[0]
marker = connection.execute("PRAGMA application_id").fetchone()[0]
# Only during validated new-database initialization:
connection.execute("PRAGMA user_version = 1")
connection.execute("PRAGMA application_id = 0x5A4D4333")与 MySQL 衔接:INSERT、CREATE TABLE、约束和事务概念可复用,运行环境与方言需区分。SQLite 使用文件与 PRAGMA,不照搬 MySQL 的 USE、AUTO_INCREMENT 或服务连接;Python sqlite3 的 ? 参数也不能直接套到所有 MySQL 驱动。
-- SQLite application schema marker, not MySQL syntax: PRAGMA user_version; -- Shared SQL concept; driver placeholders are API-specific: SELECT id, title FROM documents WHERE id = ?;
- MySQL 第 10 课:INSERT 插入数据
复习插入概念;实际 SQLite 操作使用 Python 参数绑定。
- MySQL 第 13 课:建表与删表
复习建表与约束;区分 SQLite 方言和本项目的版本策略。
- F05:保存恢复与错误保护
保留明确路径、失败状态与第二进程验收。
- D03:索引与标题唯一性
数据库更换存储,不改变 Python 标题规范化与稳定 ID。
官方参考: Python 3.11 sqlite3 documentation · SQLite transaction documentation · SQLite PRAGMA user_version
M3 独立改需求与交付
独立改需求:实现 challenges.category_counts(documents),返回“精确分类字符串 → 数量”的字典,输入列表、记录及 tags 不变。无效资料按既有契约抛 ValueError。分类不 trim 或 casefold;例如 Course、course 与 Course 后带一个空格是三个分类。自行补测空集合、重复分类、大小写不同分类及输入不变,并说明键和值的含义,不提供实现步骤。
python -m unittest tests.test_m3_variant -v
逐条提交会让前几条在后续失败前已成为正式数据,此时回滚当前一条也撤不回早先的提交。整批事务把成功与失败的边界放在整次导入上:要么全部可见,要么保留原数据库。全量验证减少可预期坏输入,但数据库/提交失败仍必须在事务中处理。网页只比较受控状态,实际能力证据来自自己的代码、测试和复现。
- 仅单机、单进程交互会话,不包含 Web API、账号、云同步、上传或线上数据库管理。SQLite 连接与事务也可能失败,不能把有文件等同于保存成功。
- 只实现版本 1 与明确拒绝不兼容版本,不宣称已有自动升级。JSON 标签保留本期列表契约,不扩展成多表标签系统。
- 没有真实运行的系统或 Python 版本,不写为已验收。网页推演不验证 SQLite 模块可用性、文件锁、磁盘、断电恢复或学生作品。
- 模型仅使用 Python 预生成的规范化结果,不执行任意 Unicode casefold。合法空源导入 0 条,但仍可能建库并提交事务;非空目标包含再次导入,一律明确拒绝,既不隐式合并也不保证自动幂等重放。
项目交付记录(自报)
只存当前浏览器,不上传作品、不签发证书。M1、M2 和 M3 分开记录;任务修改会使相关交付勾选失效。
M3 参考实现(答案)
M3 参考包含完整项目与 SQLite 答案,会记录九项单元及 M3 自身的参考使用;参考测试通过不代表学生作品通过。
下载 M3 参考实现 · 版本与来源摘要M2 参考实现(答案)
M2 参考包含九项单元的实现,下载会记录全部九项使用参考;M1 参考仍只标记六个基本功任务。
下载 M2 参考实现 · 版本与摘要M1 参考实现(答案)
参考包含六项任务的答案,下载会将六项任务记录为已使用参考。它通过测试只验证材料,不替代你的作品或同学复现。
下载 M1 参考实现 · 版本与摘要