StandardSence/StandardScene.Core/Docs/Charge/完整文件清单.md

🔌 充电桩管理系统 - 完整文件清单

📁 已创建的文件

核心文件（必需）

文件名	类型	说明	行数
ChargeStation.cs	数据模型	充电桩实体类，包含所有属性和验证逻辑	~150
ChargeStationDataService.cs	数据服务	单例模式数据管理类，负责增删改查和持久化	~300
ChargeStationManagementForm.cs	UI主类	管理窗口的业务逻辑和事件处理	~350
ChargeStationManagementForm.Designer.cs	UI设计	窗口控件的初始化和布局代码	~550

辅助文件（可选但推荐）

文件名	类型	说明	行数
ChargeStationHelper.cs	工具类	提供静态辅助方法，简化调用	~350
ChargeStationManagementExample.cs	示例代码	10个使用示例，包含完整的调用代码	~400

文档文件

文件名	类型	说明
README_ChargeStationManagement.md	完整文档	详细的功能说明、API文档和使用指南
QUICKSTART.md	快速开始	5分钟快速上手指南，包含集成步骤
INTERFACE_LAYOUT.txt	界面说明	ASCII艺术格式的界面布局和操作说明
完整文件清单.md	本文件	所有文件的清单和使用说明

---

🎯 文件功能详解

1. ChargeStation.cs - 充电桩数据模型

功能：

• 定义充电桩的所有属性（编号、名称、IP、端口、电压、电流等）
• 提供数据验证方法 IsValid()
• 自动计算功率 Power
• 自动生成唯一编号 GenerateStationId()

关键属性：

public string StationId { get; set; }        // 唯一编号
public string Name { get; set; }              // 名称
public string IpAddress { get; set; }         // IP地址
public int Port { get; set; }                 // 端口
public double Voltage { get; set; }           // 电压(V)
public double Current { get; set; }           // 电流(A)
public ChargeStationStatus Status { get; set; } // 状态
public bool Enabled { get; set; }             // 是否启用
public int? SiteId { get; set; }              // 站点ID
public double Power => Voltage * Current;     // 功率(W)

状态枚举：

public enum ChargeStationStatus {
    Idle = 0,        // 空闲
    Charging = 1,    // 充电中
    Fault = 2,       // 故障
    Offline = 3,     // 离线
    Maintenance = 4, // 维护中
    Reserved = 5     // 预约中
}

---

2. ChargeStationDataService.cs - 数据服务

功能：

• 单例模式，全局唯一实例
• 数据持久化（JSON格式）
• 线程安全（使用锁机制）
• CRUD操作（增删改查）

核心方法：

// 单例获取
ChargeStationDataService.Instance

// 查询
List<ChargeStation> GetAllStations()
ChargeStation GetStationById(string stationId)
List<ChargeStation> GetIdleStations()
int GetChargingCount()

// 添加
bool AddStation(ChargeStation station, out string errorMessage)

// 更新
bool UpdateStation(ChargeStation station, out string errorMessage)
bool UpdateStationStatus(string stationId, ChargeStationStatus status)

// 删除
bool DeleteStation(string stationId, out string errorMessage)

// 刷新
void Reload()

数据存储位置：

项目根目录/Data/ChargeStations.json

---

3. ChargeStationManagementForm.cs - 管理窗口

功能：

• 充电桩列表显示（DataGridView）
• 实时搜索
• 添加/编辑/删除充电桩
• 数据导出（JSON/CSV）
• 统计信息显示
• 状态颜色标识

主要方法：

private void LoadStations()              // 加载数据到列表
private void UpdateStatistics()          // 更新统计信息
private void btnAdd_Click()              // 新增按钮
private void btnSave_Click()             // 保存按钮
private void btnDelete_Click()           // 删除按钮
private void btnRefresh_Click()          // 刷新按钮
private void btnExport_Click()           // 导出按钮
private void dgvStations_CellDoubleClick() // 双击编辑
private void txtSearch_TextChanged()     // 搜索

界面布局：

• 左侧：充电桩列表 + 搜索 + 统计
• 右侧：编辑区 + 操作按钮
• 尺寸：1200×700（可调整，最小1000×600）

---

4. ChargeStationManagementForm.Designer.cs - UI设计文件

功能：

• 自动生成的设计器代码
• 包含所有控件的初始化
• 不建议手动修改

主要控件：

SplitContainer splitContainer           // 分割容器
DataGridView dgvStations                // 数据表格
TextBox txtSearch                       // 搜索框
TextBox txtName, txtIpAddress           // 文本框
NumericUpDown numPort, numVoltage       // 数字输入框
ComboBox cmbStatus                      // 下拉框
CheckBox chkEnabled                     // 复选框
Button btnAdd, btnSave, btnDelete       // 按钮
Label lblStatistics, lblPower           // 标签

---

5. ChargeStationHelper.cs - 辅助工具类

功能：

• 提供静态辅助方法
• 简化常用操作
• 封装复杂逻辑

常用方法：

// 打开管理窗口
ChargeStationHelper.OpenManagementWindow()

// 获取充电桩
ChargeStation station = ChargeStationHelper.GetStationBySiteId(1001)
ChargeStation station = ChargeStationHelper.GetStationByIp("192.168.1.100")

// 检查可用性
bool available = ChargeStationHelper.IsSiteHasAvailableChargeStation(1001)

// 充电控制
bool success = ChargeStationHelper.StartCharging("CS123456", carId)
bool success = ChargeStationHelper.StopCharging("CS123456", carId)

// 故障标记
bool success = ChargeStationHelper.MarkAsFault("CS123456", "通信超时")

// 获取状态摘要
string summary = ChargeStationHelper.GetStatusSummary()
// 输出: "总数:10 | 空闲:6 | 充电中:3 | 故障:1 | 离线:0"

// 查找最近的空闲充电桩
ChargeStation station = ChargeStationHelper.FindNearestIdleStation(currentSiteId)

// 快速创建充电桩
bool success = ChargeStationHelper.QuickAddStation("1号充电桩", "192.168.1.100", 1001)

// 显示选择对话框
ChargeStation selected = ChargeStationHelper.ShowStationSelectionDialog(ChargeStationStatus.Idle)

// 批量更新在线状态
int updatedCount = ChargeStationHelper.UpdateOnlineStatus(timeout: 3000)

---

6. ChargeStationManagementExample.cs - 示例代码

功能：

• 提供10个完整的使用示例
• 每个方法都带有 [MethodMember] 属性，可在系统中直接调用

示例列表：

方法名	说明
OpenManagementForm()	打开充电桩管理窗口
InitializeTestData()	初始化4个测试充电桩
ShowIdleStations()	显示所有空闲充电桩
ShowChargeStationStatistics()	显示统计信息
AssignChargeStationToCar()	为车辆分配充电桩
StartCharging()	开始充电
StopCharging()	结束充电
CheckChargeStationOnlineStatus()	检查在线状态
ExportChargeStationData()	导出数据
ClearAllChargeStationData()	清空所有数据

---

📖 使用指南

方式1：快速开始（推荐新手）

1. 阅读快速开始文档

   打开: QUICKSTART.md
   

2. 在主窗口添加菜单项

   var menuItem = new ToolStripMenuItem("充电桩管理");
   menuItem.Click += (s, e) => {
       ChargeStationHelper.OpenManagementWindow();
   };
   

3. 初始化测试数据

   ChargeStationManagementExample.InitializeTestData();
   

4. 打开管理窗口测试

   • 点击菜单项
   • 查看测试数据
   • 尝试添加/编辑/删除

方式2：集成到现有代码（推荐高级用户）

1. 阅读完整文档

   打开: README_ChargeStationManagement.md
   

2. 在充电任务中集成

   // 在 AbstractChargeMission.cs 中
   using StandardScene.Charge;
   
   // 选择充电站点时
   var dataService = ChargeStationDataService.Instance;
   var idleStations = dataService.GetIdleStations();
   
   // 到达充电站时
   ChargeStationHelper.StartCharging(stationId, carId);
   
   // 离开充电站时
   ChargeStationHelper.StopCharging(stationId, carId);
   

3. 添加实时监控

   // 在主窗口添加定时器
   private Timer statusTimer = new Timer { Interval = 3000 };
   statusTimer.Tick += (s, e) => {
       lblStatus.Text = ChargeStationHelper.GetStatusSummary();
   };
   statusTimer.Start();
   

方式3：参考示例代码（推荐学习）

1. 查看示例代码

   打开: ChargeStationManagementExample.cs
   

2. 运行示例方法

   // 直接调用示例方法
   ChargeStationManagementExample.ShowIdleStations();
   ChargeStationManagementExample.ShowChargeStationStatistics();
   

3. 根据需求修改

   • 复制示例代码
   • 根据实际需求调整
   • 集成到项目中

---

🔧 配置说明

数据文件配置

位置：

项目根目录/Data/ChargeStations.json

格式：

[
  {
    "StationId": "CS20240115123456",
    "Name": "1号充电桩",
    "IpAddress": "192.168.1.100",
    "Port": 502,
    "Voltage": 220.0,
    "Current": 32.0,
    "Status": 0,
    "Enabled": true,
    "SiteId": 1001,
    "Remarks": "南区1号充电桩",
    "CreatedTime": "2024-01-15T12:34:56",
    "ModifiedTime": "2024-01-15T14:20:30"
  }
]

权限要求

• Data 文件夹需要读写权限
• 如果保存失败，检查文件夹权限

性能配置

• 数据量 < 100个充电桩：无需优化
• 数据量 > 100个充电桩：考虑分页显示
• 搜索性能：实时搜索，无需优化

---

🎨 界面定制

修改窗口大小

在 ChargeStationManagementForm.Designer.cs 中：

this.Size = new Size(1400, 800);  // 修改为你需要的尺寸

修改按钮颜色

btnAdd.BackColor = Color.LightGreen;
btnSave.BackColor = Color.LightBlue;
btnDelete.BackColor = Color.LightCoral;

修改字体

this.Font = new Font("微软雅黑", 10F);

---

🐛 故障排除

问题1：窗口打不开

原因：命名空间引用错误

解决：

using StandardScene.Charge;

问题2：数据保存失败

原因：文件夹权限不足

解决：

1. 右键 Data 文件夹
2. 属性 → 安全
3. 确保当前用户有"写入"权限

问题3：找不到数据

原因：首次运行未初始化

解决：

ChargeStationManagementExample.InitializeTestData();

问题4：编译错误

原因：缺少依赖项

解决：

• 确保安装 Newtonsoft.Json NuGet 包
• 检查项目引用

---

📊 系统要求

软件要求

• .NET 8（net8.0-windows），宿主 SimpleLite.exe
• Windows Forms（充电模块界面尚未迁移到 CycleGUI，过渡期仍依赖）
• Newtonsoft.Json（NuGet）

硬件要求

• 内存：数据量小，几乎无影响
• 磁盘：每个充电桩约 1KB 数据
• CPU：UI操作，几乎无影响

兼容性

• Windows 7/8/10/11
• 与现有 AGV 系统完全兼容
• 不影响现有功能

---

🚀 下一步计划

已完成功能 ✅

• 充电桩数据模型
• 数据持久化（JSON）
• 可视化管理界面
• 增删改查功能
• 搜索和过滤
• 数据导出
• 辅助工具类
• 完整文档和示例

可扩展功能 💡

• 充电桩实时监控（通信状态）
• 充电历史记录
• 充电曲线图表
• 充电计费管理
• 充电桩分组管理
• 权限控制（不同用户不同权限）
• 远程控制（启动/停止充电）
• 告警推送（故障/离线）
• 数据分析（充电效率统计）
• 与现有 PLC 系统集成

---

📞 技术支持

文档位置

• 完整文档: README_ChargeStationManagement.md
• 快速开始: QUICKSTART.md
• 界面说明: INTERFACE_LAYOUT.txt
• 本文件: 完整文件清单.md

示例代码

• 工具类: ChargeStationHelper.cs
• 示例代码: ChargeStationManagementExample.cs

日志调试

// 查看充电桩相关日志
// 日志标签: "ChargeStation"

---

✅ 检查清单

在部署到生产环境前，请确认：

• 所有文件都已添加到项目
• Newtonsoft.Json NuGet 包已安装
• Data 文件夹有读写权限
• 已在主窗口添加菜单项或按钮
• 已初始化测试数据并测试
• 管理窗口可以正常打开
• 增删改查功能正常
• 数据保存和加载正常
• 搜索功能正常
• 导出功能正常
• 已阅读完整文档
• 已测试与现有系统的集成

---

📝 版本信息

当前版本: v1.0.0
发布日期: 2024-01-15
开发者: MDCS System
许可: 内部使用

---

🎉 恭喜！

您已经获得了一个完整的充电桩管理系统！

快速开始：

1. 打开 QUICKSTART.md
2. 按照步骤操作
3. 5分钟内即可开始使用

需要帮助？

• 查看文档
• 运行示例代码
• 检查日志输出

祝您使用愉快！ 🚀