32ff8b6619
- 开发者环境搭建指南.md: comprehensive Chinese setup guide for both teams - 晨会发言稿_开发任务分配.md: 15-min morning meeting script - 天普EMS开发任务分配_晨会.pptx: 8-slide presentation - Fix vite proxy back to port 8000 (standard dev port) - Fix launch.json to standard ports Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
471 lines
16 KiB
Markdown
471 lines
16 KiB
Markdown
# 天普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 （本地启动后访问）
|