tianpu-ems/docs/开发者环境搭建指南.md

# 天普EMS 开发者环境搭建指南

> 本文档帮助新加入的开发者快速搭建本地开发环境并开始工作。
> 请按顺序执行每一步，遇到问题请先查看文末的常见问题解答。

---

## 一、环境要求

在开始之前，请确保你的电脑已安装以下软件：

| 软件 | 最低版本 | 推荐版本 | 下载地址 |
|------|---------|---------|---------|
| Python | 3.10+ | 3.11.x | https://www.python.org/downloads/ |
| Node.js | 18+ | 20.x 或 24.x | https://nodejs.org/ |
| npm | 9+ | 随Node.js安装 | 随Node.js安装 |
| Git | 2.30+ | 最新版 | https://git-scm.com/downloads |
| VS Code | 最新版 | 最新版 | https://code.visualstudio.com/ |

**检查方法**（在终端/命令提示符中运行）：

```bash
python --version    # 应显示 Python 3.10 或更高
node --version      # 应显示 v18 或更高
npm --version       # 应显示 9 或更高
git --version       # 应显示 git version 2.30 或更高
```

---

## 二、注册 Gitea 账号

我们的代码托管在内部 Gitea 服务器上。

### 2.1 访问 Gitea

浏览器打开：**https://ailabmac-studio.tail954f11.ts.net/git/**

> 如果你在公司局域网内，也可以使用内网地址：`http://100.108.180.60:3300/`

### 2.2 注册账号

请将你想要的用户名告知项目经理，由管理员统一创建账号。

创建完成后你会收到：
- **用户名**：你指定的用户名
- **初始密码**：由管理员告知

首次登录后请立即修改密码：
1. 登录 Gitea
2. 点击右上角头像 → 设置
3. 修改密码

### 2.3 配置 Git 凭据（避免每次输密码）

```bash
# 配置全局用户信息（改成你自己的名字和邮箱）
git config --global user.name "你的名字"
git config --global user.email "你的邮箱@tianpu.com"

# 开启凭据缓存（输一次密码后会记住）
git config --global credential.helper store
```

---

## 三、克隆代码仓库

### 3.1 克隆

选择一个你想放代码的目录，执行：

```bash
git clone https://ailabmac-studio.tail954f11.ts.net/git/tianpu/tianpu-ems.git
```

第一次会提示输入 Gitea 的用户名和密码。输入后代码就会下载到 `tianpu-ems` 目录。

### 3.2 进入项目目录

```bash
cd tianpu-ems
```

### 3.3 查看项目结构

```
tianpu-ems/
├── backend/                  # 后端（Python/FastAPI）
│   ├── app/
│   │   ├── api/v1/           # API 接口路由（每个模块一个文件）
│   │   ├── collectors/       # IoT 数据采集器（Modbus/MQTT/HTTP）
│   │   ├── core/             # 核心模块（数据库/安全/缓存/中间件）
│   │   ├── models/           # 数据模型（SQLAlchemy ORM）
│   │   └── services/         # 业务服务（聚合/告警/报表/费用计算）
│   ├── alembic/versions/     # 数据库迁移文件（001-008）
│   ├── requirements.txt      # Python 依赖列表
│   └── main.py               # 应用入口
│
├── frontend/                 # 前端（React/TypeScript）
│   ├── src/
│   │   ├── pages/            # 页面组件（每个功能模块一个目录）
│   │   │   ├── Dashboard/    # 能源总览
│   │   │   ├── Monitoring/   # 实时监控
│   │   │   ├── Devices/      # 设备管理 + 拓扑
│   │   │   ├── Analysis/     # 能耗分析（7个Tab组件）
│   │   │   ├── Alarms/       # 告警管理（事件/规则/分析）
│   │   │   ├── Carbon/       # 碳排放管理
│   │   │   ├── Reports/      # 报表管理
│   │   │   ├── Quota/        # 定额管理 ★新增
│   │   │   ├── Charging/     # 充电桩管理 ★新增（6个子页面）
│   │   │   ├── Maintenance/  # 运维管理 ★新增（5个Tab）
│   │   │   ├── DataQuery/    # 数据查询 ★新增
│   │   │   ├── Management/   # 管理体系 ★新增（4个Tab）
│   │   │   ├── BigScreen/    # 2D 大屏可视化
│   │   │   ├── BigScreen3D/  # 3D 园区可视化
│   │   │   ├── System/       # 系统管理（用户/角色/设置/审计）
│   │   │   └── Login/        # 登录页
│   │   ├── layouts/          # 布局组件（MainLayout含菜单导航）
│   │   ├── services/         # API 调用函数（api.ts）
│   │   ├── contexts/         # React Context（主题）
│   │   ├── hooks/            # 自定义 Hooks
│   │   ├── i18n/             # 国际化（中文/英文）
│   │   ├── utils/            # 工具函数
│   │   ├── App.tsx           # 路由配置
│   │   └── main.tsx          # 应用入口
│   ├── package.json          # Node.js 依赖列表
│   └── vite.config.ts        # Vite 构建配置
│
├── scripts/                  # 脚本工具
│   ├── seed_data.py          # 种子数据（初始化演示数据）
│   └── init_db.py            # 数据库初始化
│
├── docker-compose.yml        # Docker 部署配置
└── docs/                     # 文档
    ├── 晨会发言稿_开发任务分配.md
    └── 天普EMS开发任务分配_晨会.pptx
```

---

## 四、启动后端

### 4.1 创建 Python 虚拟环境（推荐）

```bash
cd backend

# Windows
python -m venv venv
venv\Scripts\activate

# macOS / Linux
python3 -m venv venv
source venv/bin/activate
```

激活后终端前面会出现 `(venv)` 标识。

### 4.2 安装 Python 依赖

```bash
pip install -r requirements.txt
```

> 安装过程大约需要2-3分钟，如果速度慢可以使用国内镜像：
> ```bash
> pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
> ```

### 4.3 初始化数据库

项目默认使用 SQLite（零配置），开发时不需要安装 PostgreSQL。

```bash
# 运行数据库迁移（创建所有37张表）
python -m alembic upgrade head

# 导入演示数据（用户/设备/告警/充电桩/定额等）
python ../scripts/seed_data.py
```

成功后你会看到类似输出：
```
种子数据导入完成！
  角色: 6  用户: 4  设备类型: 8  设备组: 7  设备: 19
  告警规则: 6  碳排放因子: 5  报表模板: 3  报表任务: 1  告警事件: 15
  分项类别: 5  充电商户: 1  充电品牌: 2  充电站: 2  充电桩: 6
  ...
```

### 4.4 启动后端服务

```bash
python -m uvicorn app.main:app --port 8000 --reload
```

看到以下输出说明启动成功：
```
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000
```

### 4.5 验证后端

浏览器打开：**http://localhost:8000/docs**

你会看到 Swagger API 文档，列出所有120多个接口。可以直接在页面上测试接口。

---

## 五、启动前端

**另开一个终端窗口**（后端保持运行）：

### 5.1 安装 Node.js 依赖

```bash
cd frontend
npm install
```

> 如果速度慢，先配置国内镜像：
> ```bash
> npm config set registry https://registry.npmmirror.com
> npm install
> ```

### 5.2 启动前端开发服务器

```bash
npm run dev
```

看到以下输出说明启动成功：
```
VITE v8.0.3  ready in 263 ms
➜  Local:   http://localhost:3000/
```

### 5.3 访问系统

浏览器打开：**http://localhost:3000**

使用以下账号登录：

| 角色 | 用户名 | 密码 | 权限说明 |
|------|--------|------|---------|
| 管理员 | admin | admin123 | 全部权限 |
| 能源主管 | energy_mgr | tianpu123 | 能源管理+报表 |
| 操作员 | operator1 | tianpu123 | 日常操作 |
| 访客 | visitor | visitor123 | 只读浏览 |

> **建议用 admin 登录**，可以看到所有功能。

---

## 六、日常开发工作流

### 6.1 每天开始工作前

```bash
# 拉取最新代码
cd tianpu-ems
git pull origin main
```

### 6.2 开发新功能

```bash
# 创建自己的分支（用功能名命名）
git checkout -b feature/你的功能名

# 开发完成后提交
git add .
git commit -m "feat: 功能描述"

# 推送到远程
git push origin feature/你的功能名
```

然后在 Gitea 网页上创建 Pull Request 请求合并。

### 6.3 代码修改后自动刷新

- **后端**：加了 `--reload` 参数，改了 Python 代码会自动重启
- **前端**：Vite 有 HMR 热更新，改了代码浏览器会自动刷新

---

## 七、前端团队代码导读

**你负责的代码在 `frontend/src/` 目录下。**

### 核心文件（必看）

| 文件 | 说明 | 重要程度 |
|------|------|---------|
| `App.tsx` | 所有页面的路由配置，新增了5条路由 | ⭐⭐⭐ |
| `layouts/MainLayout.tsx` | 主布局+菜单导航，新增了5个菜单项 | ⭐⭐⭐ |
| `services/api.ts` | 所有后端API调用函数，新增了60多个 | ⭐⭐⭐ |

### 新增页面文件

| 目录/文件 | 功能 | 子页面/Tab |
|-----------|------|-----------|
| `pages/Quota/index.tsx` | 定额管理 | 配置(CRUD表格) / 监控(进度条) / 分析(图表) |
| `pages/Charging/index.tsx` | 充电桩管理入口 | 5个子Tab |
| `pages/Charging/Dashboard.tsx` | 充电总览 | KPI卡片 + 收入趋势 + 桩状态饼图 |
| `pages/Charging/Stations.tsx` | 充电站管理 | CRUD表格 + 新建/编辑弹窗 |
| `pages/Charging/Piles.tsx` | 充电桩管理 | 状态标签(空闲/充电/故障/离线) |
| `pages/Charging/Orders.tsx` | 充电订单 | 实时订单 / 历史订单 / 异常订单 |
| `pages/Charging/Pricing.tsx` | 计费策略 | 时段编辑器 + 峰谷平费率配置 |
| `pages/Maintenance/index.tsx` | 运维管理 | 概览 / 巡检计划 / 巡检记录 / 维修工单 / 值班 |
| `pages/DataQuery/index.tsx` | 数据查询 | 左侧设备树 + 右侧多参数查询图表 |
| `pages/Management/index.tsx` | 管理体系 | 规章制度 / 标准规范 / 管理流程 / 应急预案 |

### 增强的现有页面

| 文件 | 新增内容 |
|------|---------|
| `pages/Analysis/index.tsx` | 新增5个Tab：费用/分项/损耗/同比/环比 |
| `pages/Analysis/CostAnalysis.tsx` | 分时电价费用分析（TOU饼图+趋势） |
| `pages/Analysis/SubitemAnalysis.tsx` | 分项分析（按暖通/照明/动力分类） |
| `pages/Analysis/LossAnalysis.tsx` | 损耗分析（供电 vs 用电对比） |
| `pages/Analysis/YoyAnalysis.tsx` | 同比分析（当年 vs 去年12个月） |
| `pages/Analysis/MomAnalysis.tsx` | 环比分析（本期 vs 上期） |
| `pages/Alarms/index.tsx` | 新增"分析"Tab + 规则Toggle开关 |
| `pages/Devices/Topology.tsx` | 设备拓扑树组件 |

### 技术栈速查

| 库 | 用途 | 文档 |
|----|------|------|
| Ant Design 5 | UI组件（表格/表单/弹窗/Tab） | https://ant.design/components/overview-cn |
| ECharts | 图表（折线/柱状/饼图） | https://echarts.apache.org/zh/index.html |
| React Router v6 | 路由 | https://reactrouter.com/ |
| Axios | HTTP请求 | https://axios-http.com/ |
| dayjs | 日期处理 | https://day.js.org/ |

---

## 八、后端团队代码导读

**你负责的代码在 `backend/app/` 目录下。**

### 核心文件（必看）

| 文件 | 说明 | 重要程度 |
|------|------|---------|
| `main.py` | 应用入口，启动Redis/聚合/采集 | ⭐⭐⭐ |
| `api/router.py` | 所有API路由注册 | ⭐⭐⭐ |
| `models/__init__.py` | 所有模型导出 | ⭐⭐⭐ |
| `core/config.py` | 配置项（数据库/Redis/开关） | ⭐⭐⭐ |
| `core/deps.py` | 认证依赖（get_current_user/require_roles） | ⭐⭐ |
| `core/database.py` | 数据库连接和会话 | ⭐⭐ |

### 数据模型（`models/` 目录）

| 文件 | 模型 | 对应功能 |
|------|------|---------|
| `models/quota.py` | EnergyQuota, QuotaUsage | 能耗定额和使用记录 |
| `models/pricing.py` | ElectricityPricing, PricingPeriod | 分时电价策略和时段 |
| `models/charging.py` | 8个模型（Station/Pile/Order/Strategy/Param/Brand/Merchant/Occupancy） | 充电桩全模块 |
| `models/maintenance.py` | InspectionPlan, InspectionRecord, RepairOrder, DutySchedule | 巡检/工单/值班 |
| `models/management.py` | Regulation, Standard, ProcessDoc, EmergencyPlan | 管理体系四大文档 |
| `models/energy.py` | EnergyCategory（新增） | 能耗分项类别（暖通/照明/动力等） |

### API接口（`api/v1/` 目录）

| 文件 | 端点数 | 功能 |
|------|--------|------|
| `api/v1/quota.py` | 6 | 定额CRUD + 合规检查 + 使用统计 |
| `api/v1/cost.py` | 9 | 电价策略 + 费用汇总 + 同环比 + 峰谷平 |
| `api/v1/charging.py` | 20+ | 充电站/桩/订单/计费/商户/品牌/Dashboard |
| `api/v1/maintenance.py` | 15+ | 巡检/工单/值班 CRUD + Dashboard |
| `api/v1/management.py` | 16+ | 规章/标准/流程/预案 CRUD + 合规概览 |
| `api/v1/energy.py`（扩展） | +8 | 分类管理/损耗/同比/环比/电参量查询 |
| `api/v1/alarms.py`（扩展） | +5 | 告警趋势/Top设备/MTTR/Toggle/历史 |

### 服务层（`services/` 和 `core/` 目录）

| 文件 | 功能 | 说明 |
|------|------|------|
| `core/cache.py` | Redis 缓存 | `cache_response` 装饰器，给API加缓存 |
| `core/middleware.py` | 限流 + 请求ID | 100次/分钟/用户，每个请求分配UUID |
| `collectors/queue.py` | Redis Streams 队列 | 设备数据先入队列再批量写库 |
| `services/aggregation.py` | 数据聚合引擎 | 按时/日/月聚合能耗数据（APScheduler） |
| `services/quota_checker.py` | 定额检查 | 定时检查是否超定额，超了创建告警 |
| `services/cost_calculator.py` | 费用计算 | 按分时电价计算峰谷平各时段费用 |

### 数据库迁移（`alembic/versions/` 目录）

| 文件 | 创建的表 |
|------|---------|
| `001_initial_schema.py` | 14张基础表（用户/设备/能耗/告警/碳排放/报表） |
| `002_add_system_settings.py` | 系统设置表 |
| `003_energy_categories.py` | 能耗分项类别 + 设备关联字段 |
| `004_charging_tables.py` | 8张充电桩相关表 |
| `005_quota_tables.py` | 定额 + 使用记录 |
| `006_pricing_tables.py` | 电价策略 + 时段 |
| `007_maintenance_tables.py` | 巡检计划/记录 + 工单 + 值班 |
| `008_management_tables.py` | 规章/标准/流程/预案 |

### 接口测试方法

后端启动后，打开 **http://localhost:8000/docs** 可以：
1. 先调 `POST /api/v1/auth/login`（用户名 admin，密码 admin123）获取 token
2. 点击页面右上角 "Authorize" 按钮，输入 `Bearer <你的token>`
3. 然后就可以测试任意接口了

---

## 九、常见问题

### Q: `pip install` 报错 "Microsoft Visual C++ required"
**A:** 安装 [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)，勾选 "Desktop development with C++"。

### Q: `npm install` 很慢或超时
**A:** 配置国内镜像后重试：
```bash
npm config set registry https://registry.npmmirror.com
npm install
```

### Q: 后端启动报 "Address already in use"
**A:** 端口被占用，换一个端口：
```bash
python -m uvicorn app.main:app --port 8001 --reload
```
同时修改 `frontend/vite.config.ts` 中 proxy 的 target 端口。

### Q: 前端页面显示空白或报错
**A:** 确保后端正在运行。前端通过 Vite proxy 转发 API 请求到后端（localhost:8000）。

### Q: `alembic upgrade head` 报错
**A:** 删掉旧数据库重来：
```bash
cd backend
rm -f tianpu_ems.db
python -m alembic upgrade head
python ../scripts/seed_data.py
```

### Q: Git push 报 "Connection refused"
**A:** 确认你能访问 Gitea 地址。如果用了代理，设置绕过：
```bash
# Windows（PowerShell）
$env:NO_PROXY="ailabmac-studio.tail954f11.ts.net"
git push origin main

# macOS / Linux
NO_PROXY=ailabmac-studio.tail954f11.ts.net git push origin main
```

### Q: 数据库里没有数据，页面都是空的
**A:** 运行种子数据脚本：
```bash
cd backend
python ../scripts/seed_data.py
```

---

## 十、联系方式

遇到解决不了的问题，请联系项目经理或在开发群里提问。

**项目仓库**: https://ailabmac-studio.tail954f11.ts.net/git/tianpu/tianpu-ems
**API文档**: http://localhost:8000/docs （本地启动后访问）