Protocol 包说明

简要说明：

• 目的：封装工控协议模块（模型、配置、页面、基础组件），以 npm 包形式复用到宿主 demo 中进行联调和测试。
• 用途：为 agent 提供足够的上下文（目录结构、API、事件、集成方式），便于自动化操作或代码生成。

主要特性：

• 协议数据模型：src/models（包含 collection、各协议 modbus 等）
• 协议配置页面：src/views（协议配置、IO 映射页面等）
• 协议内置组件：src/components（可复用的基础控件与面板）
• 小工具：src/utils（如 getUUID.ts、轻量 eventBus.ts）

项目结构（关键信息，基于仓库相对路径）：

• src/models：协议核心模型与解析器
  • protocolItem.ts：协议基类（提供 updateConfig(key,path,value)）
  • modbus/：Modbus 相关模型（如 index.ts、配置 JSON、configParser.ts）
• src/views：协议配置页面（供宿主项目渲染）
• src/components：复用组件（base/naiveUi 两套、目前全部使用naiveUi这一套，base暂不启用）
• src/utils：工具函数（getUUID.ts、eventBus.ts）

重要约定（对于 agent/自动化很关键）：

• 文件编码约定：

  • Protocol 包内源码、JSON、Vue SFC、README 一律使用 UTF-8 编码保存。
  • 代码注释允许使用中文，修改文件时必须保持原文件为 UTF-8，不要以 ANSI、GBK、UTF-16、带乱码转换的方式重写文件。
  • 若工具会自动改写编码或导致中文注释显示异常，应优先使用不会变更编码的文本补丁方式修改文件。
  • 提交前如果发现中文注释出现乱码，需要先修复编码问题，再继续提交。
  • 给 agent / prompt 的额外编辑约束：
    • 始终保留中文字符。
    • 不要将任何非 ASCII 字符替换为 ?。
    • 读取和写入文件时始终使用 UTF-8 编码。
    • 编辑 JSON 文件时，优先使用 apply_patch，或使用明确指定 encoding="utf-8" 的脚本方式处理。
    • 不要使用 PowerShell 的 Get-Content、Set-Content、Out-File 直接重写文件。

• Git 提交信息约定：

  • 提交标题统一使用 <类型>: <简短说明> 格式。
  • 类型 建议使用：feat、fix、refactor、docs、style、test、build、chore。
  • 提交说明统一使用中文，标题聚焦本次改动目的，不写冗长过程描述。
  • 一次提交只解决一个问题或完成一类改动，避免把模型、页面、文档、构建配置混在同一个提交中。
  • 示例：
    • fix: 修正 Modbus IO 映射位通道生成逻辑
    • feat: 为 processData 增加树形通道展示
    • docs: 补充 Protocol 编码与构建约定
    • build: 增加 typecheck 脚本并隔离输出配置

• 事件总线：src/utils/eventBus.ts 提供轻量的 on/off/emit 接口，用于模型间通信，避免在页面层写逻辑。

  • 事件名：protocol:configUpdated（当 ProtocolItem.updateConfig 被调用时会 emit）
  • payload 示例：{ protocolId, key, path, value }

• ProtocolItem.updateConfig(key,path,value)：

  • 会在找到对应配置节点时修改其 value，并通过事件总线发布 protocol:configUpdated。
  • 任何需要响应配置变更的模型（例如 Modbus 设备）应订阅该事件并根据 payload 决定是否更新自身状态或 IO 映射。

Modbus 特定说明（agent 关注点）：

• src/models/modbus/index.ts 中的 ModbusTCPSlaveDeviceProtocolItem 已实现订阅 protocol:configUpdated 的逻辑：
  • 构造函数会调用订阅函数（setupConfigListener()），当 general 下 configParams 或 dataModel 相关路径变化时，触发 updateIoDataFromConfig()。
  • updateIoDataFromConfig() 从 dataModel 中读取 startAddress、coil、discreteInput、holdingRegister、inputRegister 等计数，并按顺序生成 config.ioMapping。

如何在宿主（demo）中本地联调：

1. 本地引用（推荐使用 pnpm workspace 或本地包引用）：

# 在 workspace 根（包含 demo 和 Protocol）使用 pnpm link 或配置 workspace
pnpm install
pnpm -w install
# 若单独测试可在 demo 中 link 到本地 Protocol 包

2. 使用方式（代码示例）：

// 假设通过包导出 ProtocolCollection / ProtocolItem
import { ProtocolCollection } from 'protocol'

const c = new ProtocolCollection()
const item = c.create(/* ... */)

// 修改配置并触发事件（不用页面逻辑）
item.updateConfig('general', 'dataModel.coil', 10)
// ModbusTCPSlaveDeviceProtocolItem 会监听并自动更新 ioMapping

3. 若要手动监听事件（扩展或调试）：

import EventBus from '@/utils/eventBus'

EventBus.on('protocol:configUpdated', payload => {
  console.log('config updated', payload)
})

建议给 agent 的 prompt 要点（用于自动化操作或修复）：

• 指出目标协议类型（例如 ModbusTCPSlaveDevice）和期望的 dataModel 值。
• 指定是否希望修改 startAddress 或各类计数（coil、holdingRegister 等）。
• 如果需要自定义映射生成规则，说明命名/地址策略（目前实现为按地址自增，name 为 ${type}_${address}，长度为 1）。

发布与打包：

• 包含的字段与入口由 package.json 控制（请参考仓库根或子包的 package.json）。
• 本地构建命令使用 npm run build，不要直接执行 vite build。
• 类型检查命令使用 npm run typecheck，不要直接执行默认的 vue-tsc，否则可能把 .js / .d.ts 误写进 src。
• 推荐在发布前在 demo 中进行本地联调与 E2E 测试，确认 config.ioMapping 的变化被正确渲染与保存。

附录：关键文件列表

• src/models/protocolItem.ts
• src/models/modbus/index.ts
• src/models/modbus/configParser.ts
• src/models/modbus/modbusTcpSlaveDevice.json
• src/utils/eventBus.ts

该 README 旨在为自动化 agent 提供直接可用的语义信息：结构、事件、示例、以及集成步骤。如需更机器可解析的格式（例如 JSON schema 或更细粒度的 API 描述），我可以生成相应的文档或示例文件。

技术栈

• 框架：Vue 3（组合式 API，使用 <script setup>）
• 语言：TypeScript
• 构建工具：Vite
• 包管理：pnpm（工作区建议使用 pnpm workspace）
• UI 库：Naive UI（项目内 src/components/naiveUi）
• 状态 / 事件通信：轻量内部 eventBus（src/utils/eventBus.ts），可根据需要替换为 mitt / eventemitter3 等成熟库
• 配置 / 模型：使用 JSON 配置文件（src/models/modbus/*.json）和自定义 ConfigParser 解析
• 测试：项目未强制指定测试框架；建议使用 Vitest 或 Jest 做单元与集成测试

（以上为 agent/维护者应知的主干技术栈，便于自动化工具生成兼容代码或调试脚本。）

Vue 3 + TypeScript + Vite

This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 <script setup> SFCs, check out the script setup docs to learn more.

Learn more about the recommended Project Setup and IDE Support in the Vue Docs TypeScript Guide.