# 中学成绩档案（初中 / 高中）

Secondary School Grade Archive — 多用户 Web 系统：成绩录入、占比趋势分析、错题 OCR + 本地 AI 解法。

**版权所有 © 马建军** · 微信 **dekun03** · 手机 **18364911125**

> [COPYRIGHT.md](./COPYRIGHT.md) · [LICENSE](./LICENSE)

**仓库：** [https://git.bz121.com/dekun/secondary-school-grade-archive.git](https://git.bz121.com/dekun/secondary-school-grade-archive.git)

---

## 文档

| 文档 | 说明 |
|------|------|
| [docs/DEPLOY.md](./docs/DEPLOY.md) | **Ubuntu 零 Node 部署**（systemd + FastAPI 单进程） |
| [docs/USAGE.md](./docs/USAGE.md) | 用户使用说明 |

---

## 修改代码后如何发布（必读）

**生产服务器不安装 Node.js，也不在服务器上执行 `npm build`。**  
凡涉及前端或全栈改动的发布，均按以下流程在**开发机**完成构建后再推送：

```
开发机改代码 → 本地构建 frontend/dist → git push 远端仓库 → 服务器 git pull + update.sh
```

### 仅改后端（`backend/`）

```bash
git add backend/
git commit -m "你的说明"
git push
```

服务器：

```bash
bash /opt/secondary-school-grade-archive/deploy/update.sh
```

### 改前端或同时改前后端（`frontend/`）

**必须先本地构建，再把 `frontend/dist` 一并提交推送：**

```powershell
# Windows
.\deploy\build-frontend.ps1
```

```bash
# Linux / macOS
bash deploy/build-frontend.sh
```

```bash
git add frontend/ frontend/dist
git commit -m "你的说明"
git push
```

服务器：

```bash
bash /opt/secondary-school-grade-archive/deploy/update.sh
```

> 若只推送源码而未推送 `frontend/dist`，服务器更新后页面不会变化。详见 [docs/DEPLOY.md §2](./docs/DEPLOY.md#2-代码修改与发布流程重要)。

---

## Ubuntu 一键部署（零 Node）

```bash
git clone https://git.bz121.com/dekun/secondary-school-grade-archive.git /opt/secondary-school-grade-archive
cd /opt/secondary-school-grade-archive
chmod +x deploy/*.sh
bash deploy/install.sh
```

- 安装目录：`/opt/secondary-school-grade-archive`
- 访问地址：`http://<服务器IP>:23566`
- 进程管理：`systemctl status grade-archive` / `journalctl -u grade-archive -f`
- 默认超级管理员：**admin / admin123**（登录后请在「系统设置」中修改）

**前提：** 仓库中已包含 `frontend/dist/`（由开发机构建后推送）。详见 [docs/DEPLOY.md](./docs/DEPLOY.md)。**反向代理不包含在本项目中。**

---

## 本地开发

### 方式一：前后端分离（推荐日常开发）

```bash
# PostgreSQL 本地安装后
cp .env.example .env

cd backend
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 23566

cd frontend
npm install && npm run dev
```

- 前端开发：http://localhost:5173（Vite 代理 `/api` → 23566）
- 后端 API：http://localhost:23566/api/health

### 方式二：模拟生产（单进程 + 静态 dist）

```bash
cd frontend && npm run build
cd ../backend
source venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 23566
```

访问 http://localhost:23566

---

## 运维

```bash
bash deploy/update.sh    # 拉代码 + 更新依赖 + 重启服务
bash deploy/backup.sh    # 备份
bash deploy/uninstall.sh # 停止并卸载
```

---

## 技术支持

微信 **dekun03** · 手机 **18364911125**