envi-code/CODEBUDDY.md

CODEBUDDY.md

This file provides guidance to CodeBuddy Code when working with code in this repository.

本文件是仓库内唯一的项目说明（原 ai.memory/ 已合并至此）。与代码不一致时以 cmake/ 脚本和当前代码为准。

项目概览

• 产品：上海华软 Envi3D 2026（环境设计） —— CAD/BIM 机电(MEP)插件套件。
• 形态：ObjectARX / ZRX 插件（DLL，后缀 .arx / .zrx），运行在 CAD 宿主内，含大量 MFC 界面与自定义图元实体。
• CMake 项目名：SHS_Code2026（version 1.0.0）。
• 主代码目录：SourceCode/Code2026/（约 2900 .cpp + 3100 .h；另有天正 tg_shs/ 系列库）。
• 远端：origin = ssh://git@39.107.55.179:222/gjm/envi-code.git（Gitea），主分支 main。

目标平台（由 preset 与编译宏区分）：

平台	SDK	版本	对应 CAD
AutoCAD	ObjectARX	R18 ~ R26	CAD 2010 ~ 2027
中望CAD	ZRX	Z2023 ~ Z2026	ZWCAD 2023 ~ 2026

构建

统一使用 CMake，不再使用 Visual Studio 工程文件（.vcxproj / .sln 已全部删除）。唯一例外：SourceCode/Code2026/StartApp/StartApp.sln（C# 启动器，独立于 CMake）。

所有命令在 SourceCode/Code2026/ 下执行（cmakelists.txt 与 cmakepresets.json 同目录）：

cd SourceCode/Code2026

cmake --preset R250                          # 配置（AutoCAD 2025-2026）
cmake --build --preset R250 --config Release # 编译
cmake --build --preset R250 --config Debug

cmake --build --preset R250 --config Release --target HvacCmd        # 单模块
cmake --build --preset R250 --config Release --target Build_SH_CORE  # 聚合目标

• 要求 CMake ≥ 3.21；生成器 Visual Studio 18 2026，架构 x64，/MP 多进程编译。
• preset 文件名是小写 cmakepresets.json（Windows 文件系统大小写不敏感，等价 CMakePresets.json）。
• 工具集随 CAD 版本变化：v143（R24x/R25x/R26x、Z202x）、v142、v141、v140、v110、v100、v90。
• C++ 标准在顶层 cmakelists.txt 中按 SDK 版本自动切换：ARX >25 → C++20；ARX 20~25 与 ZRX >2021 → C++14；ARX >19 → C++03；更老 → C++98。
• 输出目录：bin/Code2026/{Debug|Release}-x64-<标签>、lib/Code2026/...，标签为 R<版本><子版本> 或 Z<版本>。
• 加密模块的产物再落到子目录 <PRODUCT>-<MODE>（如 ENV_2025_V6_S0-BAL_REMOTE）。
• Debug 构建通过 post-build 调用 copyarx.exe，按 sh_output_path.json（ACAD）/ zw_output_path.json（中望）把产物部署到 c:\ShangHuaSoft\Envi3D-2026-M。Release 不部署。

预设（cmakepresets.json，13 套 + 3 个 base）

分组	preset
AutoCAD	R180 R190 R200 R210 R220 R230 R240 R243 R250 R260
中望CAD	Z2023 Z2024 Z2025 Z2026

继承链：base → acad_base / zwcad_base → 各版本 preset。关键 cache 变量：CAD_SDK_ROOT（../../arx/ 或 ../../zrx/）、DEP_LIB_ROOT / DEP_INC_ROOT（../dep_lib / ../dep_inc）、PRODUCT=ENV_2025_V6_S0、TRIAL_YEAR=2026、GENERATE_BIN_DIR / GENERATE_LIB_DIR。

顶层聚合目标

• Build_TG → wfA wfB wfS wfAnotate wfoutdoor
• Build_SH_CORE → AecRxBase + CoreCommand_TRIAL_YEAR + CoreCommand_BAL_REMOTE
• Build_SH_GLOBAL → MFCCtrl sqliteserver AdsXRx ThunderProof

批量编译与打包（autoCompile/WF2026/）

• batch_build.bat → python cmake_batch_build.py，读 cmake_batch_build.json 中的包定义，逐 preset 执行 cmake --preset + cmake --build --preset --config release -j 8，日志写 <preset>.log。
• 打包：Inno Setup（*.iss）+ Python（SHSCompile.py）+ 多个 .bat，覆盖 ACAD/中望、1 年期/加密版，以及客户专版（中广核、国能集团）。如 环境设计-ACAD-加密自动打包.bat、环境设计-中望-1年期自动打包.bat。

CMake 封装（cmake/functions.cmake）

• add_custom_module(dir folder)：add_subdirectory + 以目录名作为 target 名并设 FOLDER；add_custom_module_2(dir target folder) 用于目录名 ≠ target 名（如 ISODraft → ISODraftCmd、tg_shs/shs_kernal → wfK）。
• target_link_objectarx(target EXT)：链接 CAD SDK + 全局头 ShsGlobalIncludes（inc/、inc/implement/），定义 CMAKE、ARX=<版本> 与模块导出宏（如 HVACCMD_EXPORT）。
• simple_link_cad_sdk：按 IsZWCAD() 选择 ThirdParty::ARX / ThirdParty::ZRX。
• add_def_file_name(SOURCES <Name>)：向源列表追加 <Name>.def / <Name>_zrx.def（导出 acrxEntryPoint、acrxGetApiVersion）。
• target_set_name_and_suffix(target <Name> ".arx")：设置 OUTPUT_NAME/SUFFIX，中望平台自动改 .zrx。
• set_encryption_definitions_and_output_path(target MODE)：授权模式，见下节。
• set_debug_post_build：调用 copyarx.exe 部署（仅 Debug）。
• cmake/ThirdPartyDeps.cmake：定义 ShsGlobalIncludes 与 ThirdParty::ARX / ZRX / SQLite3 / cURL / TG / modernGlue / BitAnswer 等接口目标；按 SDK 版本条件追加库（acdrawbridge 需 >19，acpal/acgeoment 需 >23）。
• 顶层 cmakelists.txt 用 add_custom_module 注册全部模块并组织 FOLDER（SH/Core、SH/Pipe …）；CoreLibrary、CoreCommand 走各自的 add_subdirectory（因内部有双版本逻辑）。

授权 / 加密

• CoreLibrary、CoreCommand 通过 get_encryption_modes() 由同一套源码编译出两个目标：
  • CoreCommand_BAL_REMOTE / CoreLibrary_BAL_REMOTE（网络锁 / 正式版）
  • CoreCommand_TRIAL_YEAR / CoreLibrary_TRIAL_YEAR（1 年期试用版，Release 下定义 TRIAL_YEAR=<年份>）
• 其它业务模块只链接 CoreCommand_BAL_REMOTE；CoreLibrary_${MODE} 由加密模块内部引用。
• 依赖 BitAnswer（加密狗库）；加密表由 utility/generateEncryptionTable 生成。

架构

分三层：

1. 实体层：CoreLibrary 定义海量自定义图元 AecDbXxx（继承 AcDbEntity），是数据模型核心；同时含绘图/分解/布尔等基础能力。
2. 命令层：各 *Cmd 模块实现 MFC 对话框 + Jig 交互 + ARX 命令注册（acrxEntryPoint → acedRegCmds->addCommand，命令组名各模块自定）。
3. 链接关系：业务模块 → AecRxBase / CoreCommand / sqliteserver / MFCCtrl。

模块在顶层 cmakelists.txt 中按 FOLDER 分组：

FOLDER	模块	职责
SH/Global_Libraries	MFCCtrl, sqliteserver	MFC 控件库；SQLite 数据服务
SH/ThunderProof	AdsXRx, ThunderProof	防雷接地设计
SH/Core	AecRxBase, CoreImplement, CoreLibrary, CoreCommand	核心基类、自定义实体、主命令
SH/Pipe	PipelineCmd, PipelineSpecCmd, PIDLineCmd, ISODraft(→ISODraftCmd), PipeHanger(→PipeHangerCmd), PlumbingCmd, pool3dcmd	管道/工艺/ISO 图/支吊架/给排水/水池
SH/Structures	ArchCmd, ElecCmd, HvacCmd, SPLDCmd	建筑/电气/暖通/道路
SH/Other	shsTK, Dimension, EarthWormMain, EarthWormCmd	通用工具、标注、主程序
TG/*	tg_shs/*	天正系列库

关键模块：

• CoreLibrary：数据模型核心（自定义实体 AecDbXxx），头文件在 inc/ 与 inc/implement/，被所有模块共享。
• AecRxBase：ARX 基类库（AecDbEntityBase、AecDbCurveBase、Grip、双击编辑等）。
• CoreCommand：主命令集 + MFC 主界面/面板（BIM 面板、AI 助手 sh_ai.cpp / askaipaletteset.cpp）、PCF 导入导出（pcf.cpp、PcfIso.cpp）；生成两种加密版本。
• CoreImplement：仅在 Debug 下链接（自定义实体的实现层）。
• StartApp：C# (.NET WinForms) 启动器，不走 CMake，保留独立 StartApp.sln。
• tg_shs/：天正系列（shs_kernal→wfK、shs_twtkernal→wfKernal、shs_GeLib、shs_annotate→wfA、shs_twtanotate→wfAnotate、shs_blklib→wfB、shs_siteplan→wfS、shs_pipewire→wfpipew、shs_outdoor→wfoutdoor、shs_ximage/* 图像库、shs_dbf、shs_sqlite 等）。

新增模块约定

在模块目录放 CMakeLists.txt，并在顶层 SourceCode/Code2026/cmakelists.txt 用 add_custom_module(<相对目录> <FOLDER分组>) 注册。模板参考 HvacCmd/CMakeLists.txt：

add_library(<target> SHARED ${SOURCES})
add_def_file_name(SOURCES "<Name>")
target_set_name_and_suffix(<target> "<Name>" ".arx")
target_link_objectarx(<target> <XXX_EXPORT>)
target_precompile_headers(<target> PRIVATE StdAfx.h)
set_debug_post_build(<target> "<Name>" ".arx")

需要授权双版本时，参考 CoreCommand/cmakelists.txt 的 get_encryption_modes + foreach(MODE ...) + set_encryption_definitions_and_output_path 写法。

平台差异与注意事项

• 用 IsZWCAD() 判断目标平台；ZRX 产物后缀自动变 .zrx，链接 ThirdParty::ZRX；ARX 链接 ThirdParty::ARX。
• 编译宏：ARX=<版本号> 或 ZWCAD；模块导出宏（*_EXPORT）由 target_link_objectarx 注入。
• 部分库仅在特定 SDK 版本可用（如 acdrawbridge 需 >19，acpal/acgeoment 需 >23），已在 ThirdPartyDeps.cmake 处理。
• 禁止新增或依赖 .vcxproj / .sln（StartApp 除外）。cmake_output/ 下 CMake 生成的临时 *.vcxproj 是构建产物、已被 gitignore，不要误提交。
• .gitignore 忽略：Arx/、ZRX/、cmake_output/、bin/、lib/，以及 *.obj/*.pdb/*.user/.vs/ 等 VS 中间产物。

源码编码（重要）

全部 SourceCode/Code2026/**/*.cpp|*.h 已统一为 UTF-8 with BOM（2026-10 一次性重编码，约 6000 个文件）。新增或修改的 .cpp/.h 必须保存为 UTF-8 BOM：

• 例外：cmakelists.txt / CMakeLists.txt 保持 ASCII、无 BOM。
• 改完自检：python -c "print(open('f.cpp','rb').read(3))" 应为 b'\xef\xbb\xbf'；再查 raw.count(b'\xef\xbf\xbd')，非 0 说明中文已被写坏（不可逆），用 git checkout HEAD -- <file> 还原重做。
• 若遇到仍是 GBK/UTF-16 的老文件（从旧分支检出），先探明编码再改，不要假设。

测试 / 静态检查

本仓库没有单元测试框架（无 gtest/Catch2），也没有 lint 配置。验证方式是编译对应 preset，并在 CAD 中加载 .arx / .zrx 实测。

Git 协作

• 提交信息用中文。
• 远端是 Gitea，走 222 端口 SSH；各机器私钥不同，在本机 ~/.ssh/config 指定，不要把私钥文件名写进仓库。
• 推送到 main 需经 PR：git push origin HEAD:refs/for/main/<分支名> 触发评审，不要直接推 main。