# 电商OA系统开发

**Repository Path**: jack_python/oasystem

## Basic Information

- **Project Name**: 电商OA系统开发
- **Description**: 初级电商OA系统开发的开源项目，提供解决方案，助力企业数字化运营。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-21
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 电商团队 OA 审批系统

基于 FastAPI + LangChain + Vue 3 的企业级内部 OA 系统。

## 技术栈

| 层面 | 技术 |
|------|------|
| 后端 | Python FastAPI + SQLAlchemy 2.0 (async) |
| AI | LangChain + LangGraph + ChromaDB |
| LLM | 阿里云百炼 Qwen-Plus |
| 前端 | Vue 3 + Element Plus + Pinia |
| 数据库 | PostgreSQL 16 |
| 缓存 | Redis (Windows) |

## 项目结构

```
oa-system/
├── backend/                 # FastAPI 后端
│   ├── app/
│   │   ├── api/             # API 路由（auth/users/approvals/attendance/knowledge/chat/dashboard）
│   │   ├── core/            # 核心配置（config/security/database/redis）
│   │   ├── models/          # SQLAlchemy 数据模型
│   │   ├── schemas/         # Pydantic 验证模型
│   │   ├── services/        # 业务逻辑（审批引擎/RAG服务）
│   │   └── middleware/      # 中间件
│   ├── seed_data.py         # Demo 数据初始化脚本
│   ├── requirements.txt     # Python 依赖
│   ├── .env                 # 环境变量配置
│   └── main.py              # 入口文件
├── frontend/                # Vue 3 前端
│   ├── src/
│   │   ├── api/             # API 请求封装
│   │   ├── layout/          # 布局组件
│   │   ├── router/          # 路由配置
│   │   ├── stores/          # Pinia 状态管理
│   │   ├── views/           # 页面组件
│   │   └── styles/          # 全局样式
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
└── README.md
```

## 快速开始

### 方式一：Docker Compose（推荐 ⭐）

一条命令启动全部服务（PostgreSQL + 后端 + 前端），无需手动安装 Python/Node.js/数据库。

```bash
# 1. 配置环境变量
cp .env.production .env
# 编辑 .env 填入 SECRET_KEY、DASHSCOPE_API_KEY 等

# 2. 一键启动
docker-compose up -d

# 3. 初始化 Demo 数据
docker-compose exec app python seed_data.py
```

访问：http://localhost:8000
API 文档：http://localhost:8000/docs

### 方式二：手动安装（开发调试）

确保已安装：
- Python 3.12+
- Node.js 18+
- PostgreSQL 16
- Redis (Windows)

### 2. 后端启动

```bash
# 进入后端目录
cd backend

# 创建虚拟环境（推荐）
python -m venv venv
venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

# 配置环境变量（编辑 .env 文件）
# 必填：DASHSCOPE_API_KEY（百炼 API Key）
# 可选：DB_PASSWORD、REDIS_PASSWORD

# 创建数据库
psql -U postgres -c "CREATE DATABASE oa_system;"

# 初始化 Demo 数据
python seed_data.py

# 启动服务
python main.py
```

访问：http://localhost:8000
API 文档：http://localhost:8000/docs

### 3. 前端启动（开发模式）

```bash
# 进入前端目录
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

访问：http://localhost:5173

### 4. 生产部署

```bash
# 构建前端
cd frontend
npm run build

# 启动后端（自动托管前端静态文件）
cd ../backend
python main.py
```

访问：http://localhost:8000

## Demo 账号

| 角色 | 用户名 | 密码 |
|------|--------|------|
| Leader/管理员 | admin | 123456 |
| 一组组长 | liming | 123456 |
| 二组组长 | zhaohong | 123456 |
| 客服 | zhangsan | 123456 |
| 售后 | wangwu | 123456 |

> 所有人初始密码均为 `123456`

## 功能模块

### 审批管理
- 5种审批类型：费用报销、采购申请、请假/外出、用印/合同、折扣/退款
- LangGraph 驱动的智能审批引擎
- 自动规则：报销 <500 自动通过、退款 <100 自动通过
- 会签/或签支持

### 考勤排班
- 弹性打卡（上班/下班/外勤）
- 可视化排班管理
- 请假/外出申请
- 加班调休自动计算

### 知识库 RAG
- 5个知识库（客服话术、上架流程、售后标准、大促清单、平台规则）
- Markdown 编辑器 + 版本历史
- LangChain + ChromaDB 向量检索
- 阿里云百炼 Qwen-Plus 生成回答
- 文件上传（PDF/Word/Markdown）自动解析

### AI 助手
- 多用户多会话管理
- SSE 流式输出
- 会话历史持久化
- 知识库检索增强

### 用户管理
- JWT 双 Token 认证
- RBAC 三级权限（admin/组长/员工）
- 注册/登录/密码修改
- 小组管理

---

## 🌐 互联网部署

> 想让别人通过公网访问你的 OA 系统？以下是三种方案，从最简单到最正式。

### 方案A：ngrok 内网穿透（5分钟 · 免费 · 适合演示）

ngrok 在你的电脑和公网之间建立加密隧道，无需服务器、无需域名。

```bash
# 1. 访问 https://ngrok.com 注册免费账号
# 2. 下载 ngrok，获取 authtoken
# 3. 本地启动项目
cd backend
python main.py

# 4. 另开终端，启动隧道
ngrok http 8000

# 5. 获得公网地址，例如 https://xxxx.ngrok-free.app
#    发给任何人即可访问！
```

> ⚠️ 免费版 URL 每次重启会变，电脑关机即失效。适合临时演示。

---

### 方案B：Cloudflare Tunnel（免费 · 稳定 · 适合长期）

Cloudflare Tunnel 比 ngrok 更稳定，完全免费，支持自定义域名，自动 HTTPS。

**前提**：拥有一个域名（阿里云/腾讯云 ¥30-60/年）

```bash
# 1. 在 Cloudflare 添加域名（免费计划）
# 2. 下载 cloudflared
#    https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/

# 3. 登录并创建隧道
cloudflared tunnel login
cloudflared tunnel create oa-system

# 4. 配置 DNS 指向
cloudflared tunnel route dns oa-system oa.你的域名.com

# 5. 创建配置文件 ~/.cloudflared/config.yml
#    url: http://localhost:8000
#    tunnel: <tunnel-uuid>
#    credentials-file: /path/to/<tunnel-uuid>.json

# 6. 启动隧道
cloudflared tunnel run oa-system

# 7. 访问 https://oa.你的域名.com  🎉
```

**注册为 Windows 服务（开机自启）**：
```bash
cloudflared service install
```

> 💡 Cloudflare 免费计划不限流量，全球 CDN 加速，自带 DDoS 防护。

---

### 方案C：Docker + 云服务器（生产级 · 适合正式运营）

📖 **完整操作手册请参阅 [DEPLOY.md](DEPLOY.md)**（含服务器选购、安全配置、备份恢复、故障排查）

最专业的部署方式：购买云服务器，Docker 一键部署，7×24 运行。

**1. 购买服务器**

- 推荐：阿里云 ECS / 腾讯云 CVM
- 配置：2核4G，Ubuntu 22.04
- 新用户约 ¥50-100/月（常有活动 ¥100/年）

**2. 登录服务器并安装 Docker**

```bash
ssh root@你的服务器IP
curl -fsSL https://get.docker.com | bash
```

**3. 部署项目**

```bash
# 克隆代码
git clone <你的仓库地址> /opt/oa-system
cd /opt/oa-system

# 配置环境变量
cp .env.production .env
nano .env  # 填入 SECRET_KEY、DB_PASSWORD、DASHSCOPE_API_KEY
           # 修改 CORS_ORIGINS 加入你的域名

# 一键启动
docker-compose up -d

# 初始化数据
docker-compose exec app python seed_data.py
```

访问：`https://你的域名.com` 🎉

---

### 部署方案对比

| 方案 | 难度 | 月费 | 需电脑开机 | 需域名 | 适合 |
|------|------|------|-----------|--------|------|
| ngrok | ⭐ | 免费 | ✅ | ❌ | 临时演示 |
| Cloudflare Tunnel | ⭐ | ¥0+域名 | ✅ | ✅ | 长期展示 |
| Docker+云服务器 | ⭐⭐⭐ | ¥50-200 | ❌ | 建议有 | 正式运营 |