tianpu-ems/docs/晨会发言稿_开发任务分配.md

# 晨会发言稿：天普EMS企业级功能增强 — 开发任务分配

> **会议时长**: 约15-20分钟
> **参会人员**: 前端开发组（Team A）、后端开发组（Team B）
> **主讲人**: 项目经理

---

## 一、开场（约1分钟）

各位早上好，今天的晨会主要跟大家介绍一下我们天普EMS平台的企业级功能增强成果，同时把开发任务分配下去。

先说一下背景，大家都知道我们一直在做天普零碳园区的智慧能源管理平台，技术栈是React前端加FastAPI后端，数据库用的PostgreSQL加TimescaleDB。之前我们完成了基础版本，但跟企业级的商用EMS系统比，功能上还有不少差距。

---

## 二、项目背景（约2分钟）

这次增强的起因是这样的：我们参考了cp-ems，这是一套比较成熟的企业级Java EMS系统，分析了它的功能模块之后，我们把它具备而我们缺少的功能，全部用我们自己的Python和React技术栈重新实现了一遍。

为什么要这么做呢？两个原因：

第一，客户在做产品选型的时候，会横向对比各家平台的功能清单。如果我们缺少定额管理、分时电价、运维工单这些企业级功能，竞标的时候就会吃亏。

第二，天普大兴园区已经在用我们的系统了，实际运营中也确实需要这些功能来支撑日常管理。

所以这次增强不是为了加功能而加功能，而是补齐我们跟企业级产品之间的功能差距。

---

## 三、整体成果概述（约2分钟）

好，说一下这次增强的整体成果。

我们一共完成了12个增强阶段，全部已经验证通过。具体数字给大家报一下：

- **后端API接口**：新增120多个端点
- **前端页面**：新增和增强了12个页面，总共27个Tab页签
- **数据库表**：新增了21张表，加上原有的，现在一共37张表
- **前端技术栈**：React 19 + TypeScript + Ant Design + ECharts + Vite
- **后端技术栈**：FastAPI + SQLAlchemy + Alembic + APScheduler + Redis

整体架构没有变，还是前后端分离，前端跑在3000端口，后端跑在8000端口。但是后端新增了几个比较重要的基础设施：Redis缓存层、限流中间件、数据采集队列、还有定时聚合引擎。这些后面后端组的同事需要重点看一下。

---

## 四、前端团队任务说明（约5分钟）

好，接下来我按团队来分配任务。先说前端组。

前端组的同事，你们负责的代码都在 `frontend/src/` 这个目录下。我把需要你们重点阅读和理解的文件按模块列一下：

**第一个，定额管理页面。**

文件路径是 `pages/Quota/index.tsx`。这个页面有3个Tab：配置、监控、分析。配置Tab是一个定额的增删改查表格，可以给不同设备或区域设置能耗上限。监控Tab用进度条展示当前用量跟定额的对比情况。分析Tab用ECharts做了定额执行情况的图表分析。这个页面逻辑不算复杂，但涉及到表格、进度条、图表三种不同的展示形式，大家注意看一下数据是怎么流转的。

**第二个，充电桩管理模块。**

这是一个比较大的模块，在 `pages/Charging/` 目录下，一共6个文件：

- `index.tsx` 是主页面，包含5个Tab的整体布局
- `Dashboard.tsx` 是充电总览，有KPI卡片和图表，展示充电站整体运营状态
- `Stations.tsx` 是充电站的增删改查管理
- `Piles.tsx` 是充电桩管理，有各种状态标签，比如空闲、充电中、故障这些
- `Orders.tsx` 分三块：实时订单、历史订单、异常订单
- `Pricing.tsx` 是计费策略配置，里面有一个时段编辑器，可以拖拽设置不同时段的费率

充电桩这个模块是这次新增里最大的，大家要花多一点时间看。

**第三个，运维管理页面。**

文件是 `pages/Maintenance/index.tsx`。5个Tab：概览Dashboard、巡检计划、巡检记录、维修工单、值班安排。运维管理在实际项目中非常重要，客户方的运维团队会天天用这个模块。大家看的时候注意一下巡检计划和记录之间的关联关系。

**第四个，数据查询页面。**

文件是 `pages/DataQuery/index.tsx`。这个页面的布局比较特殊，左侧是一个设备树，右侧是多参数查询加图表展示，还有数据导出功能。设备树组件和查询条件的联动是这个页面的重点。

**第五个，管理体系页面。**

文件是 `pages/Management/index.tsx`。4个Tab：规章制度、标准规范、管理流程、应急预案。这个模块相对简单，基本都是文档的增删改查和分类管理。

**第六个，能耗分析增强。**

这块在 `pages/Analysis/` 目录下，新增了5个组件：

- `CostAnalysis.tsx` — 费用分析，包含TOU分时电价的饼图、趋势图和成本分摊
- `SubitemAnalysis.tsx` — 分项分析，按暖通、照明、动力等分类做饼图、排名和趋势
- `LossAnalysis.tsx` — 损耗分析，供电量和用电量的对比，看线损情况
- `YoyAnalysis.tsx` — 同比分析，当年跟去年的12个月逐月对比
- `MomAnalysis.tsx` — 环比分析，本期跟上期的对比

能耗分析是EMS平台的核心功能，这5个组件大家都要仔细看，特别是图表的配置和数据处理逻辑。

**第七个，告警页面增强。**

文件是 `pages/Alarms/index.tsx`。原来的告警页面新增了一个"分析"Tab，里面有告警趋势图、Top10设备排行、还有MTTR（平均修复时间）统计。另外规则Tab新增了开关Toggle和触发历史功能。

**第八个，设备拓扑。**

文件是 `pages/Devices/Topology.tsx`。这是一个树状拓扑组件，展示设备之间的层级关系。

**最后还有三个全局文件需要了解：**

- `layouts/MainLayout.tsx` — 主菜单导航，我们新增了5个菜单项
- `App.tsx` — 路由配置，新增了5条路由
- `services/api.ts` — API调用函数，新增了60多个函数，这个文件比较大，建议对照后端接口文档来看

以上就是前端组需要重点阅读的文件清单。

---

## 五、后端团队任务说明（约5分钟）

好，接下来说后端组。

后端组的代码都在 `backend/app/` 目录下。我按三层来介绍：数据模型、API接口、服务层。

### 数据模型层

先说数据模型，在 `models/` 目录下：

**`models/quota.py`** — 两个模型：EnergyQuota是能耗定额，QuotaUsage是定额使用记录。定额可以按月、按季度、按年设置，使用记录用来跟踪实际消耗。

**`models/pricing.py`** — ElectricityPricing是电价策略，PricingPeriod是时段定义。支持峰谷平分时电价，这在国内的电价体系里是标配。

**`models/charging.py`** — 这个文件最大，8个模型：ChargingStation充电站、ChargingPile充电桩、ChargingPriceStrategy计费策略、ChargingPriceParam计费参数、ChargingOrder充电订单、OccupancyOrder占位费订单、ChargingBrand品牌、ChargingMerchant商户。充电桩业务比较复杂，模型之间的外键关系大家要理清楚。

**`models/maintenance.py`** — 4个模型：InspectionPlan巡检计划、InspectionRecord巡检记录、RepairOrder维修工单、DutySchedule值班安排。

**`models/management.py`** — 4个模型：Regulation规章制度、Standard标准规范、ProcessDoc管理流程、EmergencyPlan应急预案。

**`models/energy.py`** — 新增了EnergyCategory能耗分项类别，分5种：暖通、照明、动力、特殊、其他。这个跟前端的分项分析是对应的。

### API接口层

接下来是API接口，在 `api/v1/` 目录下：

**`api/v1/quota.py`** — 定额的增删改查，加上合规检查和使用统计接口。

**`api/v1/cost.py`** — 电价策略管理，费用汇总，同比环比分析，峰谷平分析。这个模块的业务逻辑比较重，费用计算涉及到分时电价的匹配。

**`api/v1/charging.py`** — 充电桩全套接口，充电站、充电桩、订单、计费、商户、品牌的增删改查，加上充电总览Dashboard。这一个文件就有20多个端点，是接口最多的。

**`api/v1/maintenance.py`** — 巡检计划、记录、工单、值班的增删改查，加上运维Dashboard接口。

**`api/v1/management.py`** — 规章、标准、流程、预案的增删改查，加上合规概览统计接口。

**`api/v1/energy.py`** — 这是在原有能耗接口基础上扩展的，新增了分类管理、损耗分析、同比分析、环比分析、还有电参量查询。

**`api/v1/alarms.py`** — 告警接口扩展，新增了告警趋势分析、Top设备排行、MTTR统计、规则开关Toggle、触发历史。

### 服务层和基础设施

最后说服务层，这块是后端的重点：

**`core/cache.py`** — Redis缓存层。实现了一个 `cache_response` 装饰器，可以给任意API接口加缓存，支持设置TTL过期时间。大家看一下装饰器的用法，后续开发新接口的时候可以直接用。

**`core/middleware.py`** — 两个中间件：限流中间件，默认100次每分钟每用户；请求ID中间件，给每个请求生成唯一ID方便排查问题。

**`collectors/queue.py`** — Redis Streams数据采集缓冲队列。设备数据不是直接写数据库的，而是先进Redis队列，再批量写入。这样可以应对高并发的数据上报。

**`services/aggregation.py`** — 能耗数据聚合引擎，用APScheduler做定时任务，按小时、日、月三个维度聚合能耗数据。这个是后端比较核心的服务，大家要仔细看。

**`services/quota_checker.py`** — 定额合规自动检查服务。定时检查各设备的能耗是否超过定额，超了就自动创建告警记录。

**`services/cost_calculator.py`** — 分时电价费用计算服务。根据时段定义计算峰谷平各时段的用电费用。

### 数据库迁移

还有一个，数据库迁移文件在 `alembic/versions/` 目录下，编号003到008，一共6个迁移文件，创建了21张新表。后端的同事跑完 `alembic upgrade head` 之后可以看一下这些迁移文件，了解表结构。

以上就是后端组的全部任务清单。

---

## 六、Git账号设置和本地环境搭建（约3分钟）

好，下面说一下代码怎么拿到。

我们的代码托管在内部的Gitea服务器上，大家用这个地址访问：

- **Gitea网页地址**：`https://ailabmac-studio.tail954f11.ts.net/git/`
- **仓库地址**：`https://ailabmac-studio.tail954f11.ts.net/git/tianpu/tianpu-ems`

如果你在公司局域网内，也可以用内网地址 `http://100.108.180.60:3300/` 访问，但推荐大家统一用上面的Tailscale地址，在哪都能用。

每个人都需要自己的Gitea账号。账号我来统一创建，用管理员账号登录后台给大家注册。**会后请每个人把你想用的用户名发给我**，我来创建。创建好之后会给你们初始密码，第一次登录要改密码。

账号拿到之后，按这个步骤把环境跑起来：

**第一步，克隆仓库：**

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

克隆的时候会让你输入Gitea的用户名密码，就用我给你创建的账号。

**第二步，启动后端：**

```bash
cd backend
pip install -r requirements.txt
python -m alembic upgrade head
python ../scripts/seed_data.py
python -m uvicorn app.main:app --port 8000 --reload
```

先装依赖，然后跑数据库迁移，再导入种子数据，最后启动后端服务。`--reload` 参数是热更新，改了代码会自动重启。

**第三步，启动前端，另开一个终端：**

```bash
cd frontend
npm install
npm run dev
```

**第四步，访问系统：**

- 浏览器打开 `http://localhost:3000`
- 登录账号：`admin` / `admin123`
- 后端API文档：`http://localhost:8000/docs`，这个Swagger文档里能看到所有接口的详细说明和参数定义

如果遇到环境问题跑不起来，先在群里问一下，常见问题我们会整理一份FAQ。

---

## 七、下一步安排（约2分钟）

好，最后说一下接下来的安排。

**本周的任务很明确：阅读代码。**

每个人对照我刚才列的文件清单，把自己团队负责的代码通读一遍。不需要你逐行看，但要做到以下几点：

1. **理解每个文件的职责**：这个文件是干什么的，对应系统的哪个功能
2. **理清数据流**：前端的同事要知道数据从API怎么拿到、怎么渲染到页面上；后端的同事要知道一个请求从路由进来，经过哪些处理，最终怎么操作数据库
3. **记录问题**：看不懂的地方、觉得有问题的地方、或者有更好实现思路的地方，都记下来

**下周的晨会**，每个人汇报一下自己看的代码理解情况，有什么疑问我们集中讨论。

另外再强调一点，后端组的同事建议结合Swagger文档来看代码，`http://localhost:8000/docs` 里面每个接口都有请求参数和返回格式的说明，比直接看代码要直观很多。前端组的同事建议把系统跑起来，边看代码边操作页面，这样理解会更快。

---

## 八、Q&A（约2分钟）

好，以上就是今天晨会的全部内容。大家有什么问题吗？

……（等待提问）

没有问题的话，会后请大家：

1. 把你想要的Gitea用户名发给我
2. 尽快把本地环境搭起来
3. 开始阅读自己负责的代码

好，今天的晨会就到这里，谢谢大家。