# Project Acceptance Data Management System

**Repository Path**: dovepan_git/project-acceptance-data-management-system

## Basic Information

- **Project Name**: Project Acceptance Data Management System
- **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-07-22
- **Last Updated**: 2026-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 验收数据管理网站

质量部成品管控用的验收数据管理网站：读取各项目文件夹中的 **Excel 验收记录** 与 **Word/PDF 合格证**，自动解析项目号、产品分类、一致性，并在网页上结构化展示、支持 CSV 导出。

> 🔒 **数据安全**：所有 Excel / Word / PDF 验收源文件**绝不进入版本库**（见 `.gitignore`），运行时通过 SMB 挂载**只读**读取，不落盘、不改源文件。

---

## 一、项目结构

```
acceptance_site/
├── app.py                 # Flask 入口：页面路由、/api/scan 扫描、CSV 导出
├── parsers/
│   ├── __init__.py
│   ├── detect.py          # 文件类型嗅探
│   ├── excel_reader.py    # 读 Excel（openpyxl / xlrd），自动跳过隐藏 sheet
│   ├── word_reader.py     # 读合格证 .doc / .docx（antiword，WPS .doc 走 LibreOffice 兜底）
│   └── scan.py            # 目录扫描、项目号解析/生成/校验、产品分类
├── static/
│   ├── app.js             # 前端 SPA 逻辑（卡片、筛选、详情抽屉）
│   └── style.css          # 明亮主题样式
├── templates/
│   └── index.html         # 单页骨架
├── Dockerfile             # 容器镜像（python:3.11-slim + UV 装依赖 + antiword + 可选 LibreOffice）
├── docker-compose.yml     # 编排（端口映射、DATA_ROOT、只读 SMB 挂载、健康检查）
├── pyproject.toml        # 📦 UV 管理的 Python 依赖（唯一真相源）
├── uv.lock                # 锁文件（精确钉版本、可复现）
├── .dockerignore
├── .gitignore             # 排除验收数据、日志、缓存、本地虚拟环境
└── DOCKER_DEPLOY.md       # 完整 Docker + SMB 部署文档（服务器侧步骤）
```

---

## 二、本地运行（UV 管理）

本项目 **Python 依赖统一用 [UV](https://github.com/astral-sh/uv) 管理**（不另用 pip / venv 散装）。

```bash
# 1. 安装 UV（一次）： https://docs.astral.sh/uv/getting-started/installation/
# 2. 进入项目目录
cd acceptance_site

# 3. 创建 .venv 并安装依赖（按 uv.lock 可复现）
uv sync

# 4. 启动（UV 会自动用 .venv 里的解释器）
uv run python app.py
```

启动后访问 **http://127.0.0.1:5000** 。

- 数据根目录默认是 `app.py` 的上级目录；在网页上可手动填路径或点"选择文件夹"列子目录（如 `ZH25`）。
- 也可双击 `start_server.bat`（Windows）一键启动，它优先用 `uv run`。
- 打印依赖清单：`uv pip list`；升级某包后重新锁定：`uv lock`。

---

## 三、Docker + SMB 部署（服务器侧）

把 `acceptance_site/` 传到 Debian 服务器（如 `/opt/acceptance_site`），源数据通过 SMB 协议从文件服务器/NAS 只读挂载，容器本身不存数据。

```bash
cd /opt/acceptance_site

# 构建（默认不含 LibreOffice；需解析 WPS .doc 时加 --build-arg WITH_LO=1）
docker compose build
docker compose up -d

# 验证
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5000/
```

SMB 挂载、fstab 持久化、nginx + HTTPS 加固、`.doc` 解析能力说明等**完整步骤见 [`DOCKER_DEPLOY.md`](./DOCKER_DEPLOY.md)**。

**核心架构**：SMB 挂载放在**宿主机**（`cifs-utils` → `/mnt/acceptance`，只读、开机自动），容器用 `bind mount` 只读挂入 `/data/acceptance`；容器不加特权、不装 cifs，凭据只在宿主机 `/etc/smbcredentials`（chmod 600）。

---

## 四、从 Gitee 拉取最新版本（服务器更新与同步）

代码托管在 Gitee：`git@gitee.com:dovepan_git/project-acceptance-data-management-system.git`。后续所有修改只落在 `acceptance_site/` 内的代码 / 文档 / 配置，验收数据（Excel / Word）永不入库，因此服务器更新**只动代码、不碰源数据**，SMB 挂载的数据完全不受影响。

### 首次部署：克隆仓库
```bash
# 进入部署父目录（如 /opt）
cd /opt
git clone git@gitee.com:dovepan_git/project-acceptance-data-management-system.git acceptance_site
cd acceptance_site
# 之后按「三、Docker + SMB 部署」完成 SMB 挂载并构建启动
```

### 日常更新：拉取最新版本
```bash
cd /opt/acceptance_site

# 1. 查看当前状态（可选，确认无未提交的本地改动）
git status

# 2. 拉取远程 master 最新提交
git pull origin master

# 3. 重新构建并平滑重启容器（build 会按新的 uv.lock 重装依赖）
docker compose build
docker compose up -d

# 4. 确认服务正常
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5000/
```
> **何时要重新 build**：只要改了 `pyproject.toml` / `uv.lock` 或 Python 依赖，必须 `docker compose build`；若仅前端（`static/`）或 `app.py` 等应用代码改动，执行 `docker compose up -d --build`（或单独重启容器）即可生效。

### 本地改动冲突怎么办
若服务器上曾手动改过文件，导致 `git pull` 报冲突，按部署机性质二选一：
```bash
# 方案 A（推荐，纯部署机）：丢弃服务器本地改动，直接用远程版本
git fetch origin
git reset --hard origin/master
docker compose build && docker compose up -d

# 方案 B：暂存本地改动，拉取后手动合并
git stash
git pull origin master
git stash pop   # 有冲突时按提示解决
```

### 回退到某个历史版本
```bash
git log --oneline          # 找到目标 commit hash
git checkout <commit-hash>
docker compose build && docker compose up -d
```

### 安全要点
- 拉取只会更新代码 / 文档 / 配置，**绝不会**拉到 Excel / Word 验收数据（已被 `.gitignore` 排除）。
- 切勿在服务器上把验收数据文件执行 `git add`，否则会破坏「数据不入库」的约束。
- 建议给容器加 `restart: unless-stopped`（可在 `docker-compose.yml` 的服务下补一行），更新重启后自动恢复服务。

---

## 五、项目号格式规范

代码按以下规则解析 / 生成 / 校验项目号（见 `parsers/scan.py`）：

```
ZH + 2位年份(24=2024) + 1位项目类型号(6=批试 / 7=客户) + 3位序列号(001 起) + 1位分类标识(D/W/N/G/B) + 可选设备后缀(-1/-2…)
```

- 分类标识：`D` 电子万能试验机、`W` 液压万能试验机、`N` 扭转试验机、`G` 摆锤冲击试验机、`B` 轴承试验机。
- 一致性校验：提取的项目号与**文件夹名称**（非 Excel 文件名）比对，不一致会在网页标记。

---

## 六、技术栈

- 后端：Python 3.11 + Flask
- Excel：openpyxl（.xlsx）、xlrd 2.x（.xls），自动跳过隐藏 sheet
- 合格证：antiword（.doc）、python-docx（.docx）、LibreOffice 兜底（WPS .doc）、msoffcrypto（加密）
- 前端：原生 JS + CSS（明亮主题，无构建步骤）
- 部署：Docker + Docker Compose，数据走 SMB/CIFS 只读
- 依赖管理：UV（pyproject.toml + uv.lock）