# SRM 供应商关系管理系统

**Repository Path**: MerlinRong/SRM

## Basic Information

- **Project Name**: SRM 供应商关系管理系统
- **Description**: 构建一套覆盖 供应商全生命周期 的数字化管理平台，实现从供应商准入、询价比价、合同签订到对账结算、履约考核全流程线上化闭环，帮助企业构建稳定、高效、透明的供应链体系
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-07
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 🏭 SRM 供应商关系管理系统

**覆盖供应商全生命周期的数字化采购管理平台**

准入审核 · 档案管理 · 询价比价 · 合同签订 · 对账结算 · 履约考核 · 报表分析

[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
[![Vue](https://img.shields.io/badge/Vue-3.5-4FC08D?logo=vuedotjs&logoColor=white)](https://vuejs.org/)
[![Element Plus](https://img.shields.io/badge/Element_Plus-2.9-409EFF)](https://element-plus.org/)
[![Tests](https://img.shields.io/badge/tests-101%20passing-brightgreen)](./backend/tests)
[![License](https://img.shields.io/badge/license-MIT-blue)]()

</div>

---

## ✨ 功能特性

| 模块 | 功能 | 亮点 |
|------|------|------|
| 🏢 **供应商管理** | 自主注册、多级准入审核、档案 360°、证照版本管理与到期提醒 | 信用代码唯一校验、字段级变更留痕、银行账号 AES-256 加密 |
| ⭐ **供应商评级** | QCDS 四维自动评分（质量 30 / 价格 25 / 交期 25 / 服务 20）、A~D 分级 | 权重可配置、评级结果联动询价与订单分配 |
| 📋 **询价比价** | 询价发布、供应商在线报价、自动比价矩阵、定标决策 | 历史成交均价对比、并发报价行锁保护、报价版本化可追溯 |
| 📑 **采购合同** | 定标自动生成草稿、金额分级审批、合同变更版本链、到期预警 | >10 万加签总监、>50 万加签财务，阈值可配置 |
| 💰 **对账结算** | 对账单协同确认、差异处理、发票管理、付款审批、账龄分析 | LOCKED 幂等护栏防重复付款、差异原因强制留痕 |
| 📊 **履约考核** | 月度自动取数（准时率/合格率）、人工评分、7 天申诉闭环 | 考核结果自动联动供应商评级 |
| 📈 **报表中心** | 采购趋势、供应商排名、等级分布、管理驾驶舱 | 预计算表 + Redis 缓存，接口稳定 ≤200ms |
| 🔐 **系统管理** | 用户/角色/权限 RBAC、数据字典、审批流配置、审计日志 | 供应商数据行级隔离，前端按钮级权限控制 |

## 🏗️ 技术架构

| 层级 | 技术 |
|------|------|
| 前端 | Vue 3 + TypeScript + Element Plus + Pinia + ECharts |
| 后端 | Python 3.10+ · FastAPI · SQLAlchemy 2.0 (async) · Pydantic v2 |
| 数据库 | PostgreSQL 15（开发/测试支持 SQLite） |
| 缓存 | Redis 7（会话 / 缓存 / 分布式锁） |
| 对象存储 | MinIO（证照 / 发票扫描件） |
| 任务调度 | APScheduler + Redis 分布式锁 |

<details>
<summary><b>📐 核心设计模式</b></summary>

- **状态机驱动**：所有单据状态流转经声明式状态机校验 + `SELECT FOR UPDATE` 行锁，杜绝并发脏数据
- **审批流引擎**：节点 JSONB 配置化、金额分级条件裁剪、防自审、业务回调注册（四大业务复用）
- **数据隔离**：供应商账号查询在 Repository 层自动叠加 `supplier_id` 过滤，业务代码零感知
- **统一异常体系**：Service 层只抛业务异常，全局处理器转换为标准响应码
- **多渠道通知**：站内信 + 邮件（SMTP 未配置自动降级日志渠道），fire-and-forget 不阻塞业务

</details>

## 🚀 快速开始

### 环境要求

- Python 3.10+ / Node.js 18+ / Docker（可选，用于基础设施）

### 1️⃣ 启动基础设施

```bash
docker compose up -d        # PostgreSQL + Redis + MinIO
```

### 2️⃣ 启动后端

```bash
cd backend
python -m venv .venv
.venv\Scripts\activate                # Windows（Linux/Mac: source .venv/bin/activate）
pip install -r requirements.txt -r requirements-dev.txt

copy .env.example .env                # 生产环境必须修改 JWT_SECRET 与 FIELD_ENCRYPT_KEY
python -m scripts.init_db             # 建表 + 种子数据
uvicorn app.main:app --reload         # → http://localhost:8000/api/docs
```

### 3️⃣ 启动前端

```bash
cd frontend
npm install
npm run dev                           # → http://localhost:5173（已配置 /api 代理）
```

> 🔑 默认管理员：`admin / admin123`（首次登录后请立即修改）

### 4️⃣ 运行测试

```bash
cd backend
python -m pytest tests/ -q            # 101+ 测试：状态机穷举/审批引擎/评级算法/端到端
```

## 📁 项目结构

```text
backend/app/
├── core/          # 配置 · 数据库 · Redis · 统一响应 · 异常体系 · JWT+RBAC · 状态机
├── models/        # SQLAlchemy 模型（RBAC/审批/供应商/评级/询价/合同/结算/考核）
├── schemas/       # Pydantic 请求/响应模型
├── repositories/  # 数据访问层（供应商行级数据隔离统一实现点）
├── services/      # 业务逻辑：审批引擎 · QCDS 评级 · 通知渠道 · 各模块 Service
├── api/v1/        # RESTful 路由（OpenAPI 自动文档）
└── tasks/         # APScheduler 定时任务
frontend/src/
├── api/           # axios 封装 + 模块化接口
├── stores/        # Pinia（认证/权限/动态菜单）
├── layouts/       # 主布局
└── views/         # 页面（注册/供应商/询价/合同/对账/考核/报表/系统）
```

## ⏰ 定时任务

| 任务 | 频率 | 说明 |
|------|------|------|
| 询价自动截止 | 每 5 分钟 | 到期询价 `PUBLISHED → CLOSED` |
| 证照到期提醒 | 每日 08:00 | 有效期前 60 天通知供应商与采购员 |
| 合同到期预警 | 每日 08:10 | 到期前 30/60/90 天分级提醒 |
| 考核任务生成 | 每月 1 日 | 为有交易的供应商自动建单并取数 |
| 报表预计算 | 每日 02:00 | 日汇总表增量更新（幂等可重跑） |

## 🧪 测试

```bash
python -m pytest tests/ -q                 # 全量
python -m pytest tests/unit -q             # 单元（状态机/审批/评分）
python -m pytest tests/api -q              # 接口（权限矩阵/数据隔离/端到端）
```

覆盖重点：状态机穷举转移、审批防自审、供应商越权访问、报价并发、付款幂等、QCDS 评分边界值。

## 📦 部署

```bash
# 数据库迁移（CI/生产统一入口）
cd backend && alembic upgrade head

# 后端多 Worker
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

# 前端构建产物交由 Nginx 托管，/api 反代至后端
cd frontend && npm run build
```

## 🗺️ Roadmap

- [x] 供应商准入 / 档案 / 评级 / 询价比价 / 合同 / 对账结算 / 考核 / 报表
- [x] 比价历史成交均价对比（F-INQ-005）
- [x] 报表 CSV 导出
- [x] 多渠道通知（邮件 SMTP / 站内信）
- [x] 供应商门户独立注册页
- [ ] 电子签章集成
- [ ] 短信通知渠道
- [ ] 移动端适配

## 📄 文档

完整设计文档见 `.codebuddy/docs/`：

- 📋 [需求规格说明书（SRS）](./.codebuddy/docs/SRM%20供应商关系管理系统%20—%20需求规格说明书（SRS）.md)
- 🏗️ [系统设计文档（SDD）](./.codebuddy/docs/SRM%20供应商关系管理系统%20—%20系统设计文档（SDD）.md)
- 💻 [编码实现方案](./.codebuddy/docs/SRM%20供应商关系管理系统%20—%20编码实现方案.md)

---

<div align="center">

**SRM** · 让供应链管理更简单透明

</div>