# ai-coding-project

**Repository Path**: xiaoxinzhss/ai-coding-project

## Basic Information

- **Project Name**: ai-coding-project
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-30
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 校园报修工单系统

基于 Flask + MySQL 的轻量级 Web 工单平台，用于校园设施故障报修的全流程管理。

## 功能概览

| 模块 | 功能 | 状态 |
|------|------|------|
| 用户认证 | 登录/登出、角色权限控制 | 已完成 |
| 报修提交 | 表单提交 + JSON API，自动生成工单号 | 已完成 |
| 工单查询 | 列表/详情/状态筛选，按角色过滤可见范围 | 已完成 |
| 状态管理 | 管理员指派/推进/退回工单状态 | 已完成 |
| 完工记录 | 维修人员提交维修说明、耗材、工时 | 已完成 |
| 统计看板 | 各状态工单数量、维修人员工作负载 | 已完成 |

## 技术栈

- **后端**：Flask 3.x + Jinja2 模板
- **数据库**：MySQL 8.0 + PyMySQL
- **测试**：pytest（73 项自动化用例，100% 通过）
- **认证**：werkzeug.security（scrypt 哈希）

## 快速开始

### 1. 启动 MySQL

```bash
docker run -d --name repair-mysql \
  -e MYSQL_ROOT_PASSWORD=root123 \
  -e MYSQL_DATABASE=repair_system \
  -p 3307:3306 mysql:8.0
```

### 2. 初始化数据库

```bash
mysql -h 127.0.0.1 -P 3307 -u root -proot123 repair_system < db/schema.sql
mysql -h 127.0.0.1 -P 3307 -u root -proot123 repair_system < db/seed.sql
```

### 3. 安装依赖并启动

```bash
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py
```

访问 http://127.0.0.1:5001

## 测试账号

| 用户名 | 密码 | 角色 | 权限 |
|--------|------|------|------|
| admin001 | admin123 | 管理员 | 全部工单、状态管理、统计看板 |
| worker001 | worker123 | 维修人员 | 仅指派给自己的工单、提交完工 |
| student001 | student123 | 学生 | 仅自己提交的工单 |

## 运行测试

```bash
python -m pytest tests/ -v
```

## 工单状态流转

```
待处理(pending) ──→ 已指派(assigned) ──→ 维修中(doing) ──→ 已完成(done)
      ↑                   ↓                   ↓
      └──── 退回 ─────────┘       └── 退回 ──┘
```

| 流转 | 操作角色 |
|------|----------|
| pending → assigned | 管理员（指派维修人员） |
| assigned → doing | 管理员（确认开始维修） |
| assigned → pending | 管理员（退回待处理） |
| doing → assigned | 管理员（退回已指派） |
| doing → done | 维修人员（提交完工记录） |

## 项目结构

```
├── app/
│   ├── __init__.py        # Flask 工厂 + 蓝图注册
│   ├── config.py          # 配置（DB/密钥/常量）
│   ├── db.py              # DB 上下文管理器 + 查询函数
│   ├── ticket_state.py    # 状态流转规则
│   ├── auth.py            # 登录/登出
│   ├── tickets.py         # 工单 CRUD
│   ├── admin.py           # 状态管理/看板
│   ├── templates/         # Jinja2 模板
│   └── static/            # CSS
├── db/
│   ├── schema.sql         # 建表脚本
│   └── seed.sql           # 种子数据
├── tests/                 # pytest 测试套件（5 个文件，73 项用例）
├── docs/                  # 项目文档
│   ├── SPEC-v0.1.md       # 需求规格说明书
│   ├── ARCH-v0.1.md       # 架构说明
│   ├── TEST-PLAN.md       # 测试计划
│   ├── test-cases.md      # 测试用例（38 条手工用例）
│   ├── TEST-REPORT-v0.1.md # 测试报告
│   ├── DEPLOY.md          # 部署手册
│   ├── DATA-v0.1.md       # 数据层评估报告
│   └── DATA-changelog.md  # 数据层变更日志
├── main.py                # 应用入口
└── requirements.txt       # Python 依赖
```

## 文档索引

| 文档 | 说明 |
|------|------|
| [SPEC-v0.1.md](docs/SPEC-v0.1.md) | 需求规格说明书：用户故事、功能矩阵、非功能需求、验收标准 |
| [ARCH-v0.1.md](docs/ARCH-v0.1.md) | 架构说明：技术选型、模块划分、接口概要、重构方案、业务流程 |
| [TEST-PLAN.md](docs/TEST-PLAN.md) | 测试计划：测试策略、阶段划分、权限矩阵、通过标准 |
| [test-cases.md](docs/test-cases.md) | 测试用例：P0 功能 UT/IT/AT 共 38 条手工用例 |
| [TEST-REPORT-v0.1.md](docs/TEST-REPORT-v0.1.md) | 测试报告：73/73 自动化测试通过，0 缺陷 |
| [DEPLOY.md](docs/DEPLOY.md) | 部署手册：环境搭建、运维指南、安全配置、故障排查 |

## 许可证

内部教学项目，仅供演示使用。