diff --git a/.claude/launch.json b/.claude/launch.json index adb5dfd..917e601 100644 --- a/.claude/launch.json +++ b/.claude/launch.json @@ -4,15 +4,15 @@ { "name": "frontend", "runtimeExecutable": "npm", - "runtimeArgs": ["run", "dev", "--", "--force", "--port", "3002"], - "port": 3002, + "runtimeArgs": ["run", "dev", "--", "--force"], + "port": 3000, "cwd": "frontend" }, { "name": "backend", "runtimeExecutable": "uvicorn", - "runtimeArgs": ["app.main:app", "--port", "8088", "--reload"], - "port": 8088, + "runtimeArgs": ["app.main:app", "--port", "8000", "--reload"], + "port": 8000, "cwd": "backend" } ] diff --git a/docs/开发者环境搭建指南.md b/docs/开发者环境搭建指南.md new file mode 100644 index 0000000..816556d --- /dev/null +++ b/docs/开发者环境搭建指南.md @@ -0,0 +1,470 @@ +# 天普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 (本地启动后访问) diff --git a/docs/晨会发言稿_开发任务分配.md b/docs/晨会发言稿_开发任务分配.md new file mode 100644 index 0000000..6000a4f --- /dev/null +++ b/docs/晨会发言稿_开发任务分配.md @@ -0,0 +1,260 @@ +# 晨会发言稿:天普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. 开始阅读自己负责的代码 + +好,今天的晨会就到这里,谢谢大家。 diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts index 8f3ccca..2b5b732 100644 --- a/frontend/vite.config.ts +++ b/frontend/vite.config.ts @@ -7,7 +7,7 @@ export default defineConfig({ port: 3000, proxy: { '/api': { - target: 'http://localhost:8088', + target: 'http://localhost:8000', changeOrigin: true, }, },