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/

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

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 凭据（避免每次输密码）

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

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

---

三、克隆代码仓库

3.1 克隆

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

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

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

3.2 进入项目目录

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 虚拟环境（推荐）

cd backend

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

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

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

4.2 安装 Python 依赖

pip install -r requirements.txt

安装过程大约需要2-3分钟，如果速度慢可以使用国内镜像：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

4.3 初始化数据库

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

# 运行数据库迁移（创建所有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 启动后端服务

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 依赖

cd frontend
npm install

如果速度慢，先配置国内镜像：

npm config set registry https://registry.npmmirror.com
npm install

5.2 启动前端开发服务器

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 每天开始工作前

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

6.2 开发新功能

# 创建自己的分支（用功能名命名）
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，勾选 "Desktop development with C++"。

Q: npm install 很慢或超时

A: 配置国内镜像后重试：

npm config set registry https://registry.npmmirror.com
npm install

Q: 后端启动报 "Address already in use"

A: 端口被占用，换一个端口：

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: 删掉旧数据库重来：

cd backend
rm -f tianpu_ems.db
python -m alembic upgrade head
python ../scripts/seed_data.py

Q: Git push 报 "Connection refused"

A: 确认你能访问 Gitea 地址。如果用了代理，设置绕过：

# 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: 运行种子数据脚本：

cd backend
python ../scripts/seed_data.py

---

十、联系方式

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

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