# test

**Repository Path**: bladevil/test

## Basic Information

- **Project Name**: test
- **Description**: ai考试
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-27
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 简易学生成绩管理系统（Student Grade Management System）

> AI 开发实战营考核作品 · OpenSpec 规范驱动开发（Spec-Driven）+ 全程 TDD
> 学员：**陈思航**　工号：**201588**　日期：**2026-06-27**

一个基于 **JSON 轻量文件数据库**的命令行学生成绩管理工具，面向教务人员，提供成绩录入、查询、统计与异常容错能力；数据持久化、程序重启不丢。

## ✨ 功能特性

- **录入**：学号 / 姓名 / 语文 / 数学 / 英语，完整合法性校验 + 重复学号拦截
- **查询**：按学号精准查询单个学生；全部学生批量列表展示
- **统计**：单学生总分 / 平均分；班级单科平均分
- **持久化**：JSON 文件数据库，程序重启数据不丢失
- **容错**：全局中文友好提示，非法输入 / 空数据 / 不存在学号均不崩溃

## 🧩 技术栈

- Python 3（运行期仅标准库，**零第三方依赖**）
- pytest（测试驱动开发 TDD）
- JSON 文件数据库

## 📁 项目结构

```
.
├── main.py                  # 命令行入口
├── src/grade_manager/       # 源码（分层架构）
│   ├── config.py            # 配置与默认值常量
│   ├── errors.py            # 自定义异常体系
│   ├── models.py            # Student 数据模型
│   ├── database.py          # JSON 文件数据库读写
│   ├── validators.py        # 输入合法性校验
│   ├── services.py          # 业务逻辑（录入/查询/统计）
│   └── cli.py               # 命令行交互 + 全局容错
├── tests/                   # pytest 测试（TDD 资产）
├── data/students.json       # JSON 文件数据库
├── spec/                    # 四类规范文件 task/design/spec/config
├── openspec/                # OpenSpec 提案与规范
├── requirements.txt         # 测试依赖（pytest）
└── pytest.ini               # pytest 配置
```

## 🚀 快速开始

```bash
# 1. 准备环境
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 2. 初始化数据库
python main.py init

# 3. 录入与查询
python main.py add --id 201588 --name 陈思航 --chinese 95 --math 88 --english 92
python main.py get --id 201588
python main.py list

# 4. 统计
python main.py stats --id 201588      # 单学生总分/平均分
python main.py stats --class          # 班级单科平均分
```

> 📦 仓库已内置 3 条演示数据（学号 1001 / 1002 / 1003），克隆后可直接运行 `python main.py list` 或 `python main.py stats --class` 查看效果。

## ✅ 运行测试

```bash
pytest                 # 或 python -m pytest
```

测试覆盖正常 / 异常 / 边界场景，目标通过率 **100%**。

## 📐 OpenSpec 工作流

本项目严格按 OpenSpec 四阶段（**Explore → Purpose → Apply → Archive**）推进，拆分为 4 个迭代 Change：

1. `project-foundation` — 项目架构与持久化
2. `grade-entry-validation` — 成绩录入与数据校验
3. `grade-query` — 成绩查询能力
4. `statistics-and-error-handling` — 成绩统计与全局容错

规范文档见 `spec/`（task / design / spec / config 四类文件）与 `openspec/`（changes / specs）。

## 📑 评分相关文档导航

- 规范四件套：[`spec/task.md`](spec/task.md) · [`spec/design.md`](spec/design.md) · [`spec/spec.md`](spec/spec.md) · [`spec/config.md`](spec/config.md)
- OpenSpec 四阶段落地说明：[`OPENSPEC_PROCESS.md`](OPENSPEC_PROCESS.md)
- 测试报告：[`TEST_REPORT.md`](TEST_REPORT.md)
- 归档总结（迭代问题与优化点）：[`ARCHIVE_SUMMARY.md`](ARCHIVE_SUMMARY.md)
- 满分自检清单：[`FULL_SCORE_CHECKLIST.md`](FULL_SCORE_CHECKLIST.md)
- OpenSpec 资产：`openspec/specs/`（主规范 5 能力）· `openspec/changes/archive/`（4 个已归档迭代）

## 👤 学员信息

- 姓名：陈思航　工号：201588　日期：2026-06-27
- 仓库：https://gitee.com/bladevil/test.git