envi-code/CODEBUDDY.md

# CODEBUDDY.md

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

> 另见 `ai.memory/`：随仓库提交的跨机器项目记忆（概览 / 构建 / 模块 / 工作日志 / 约定）。开始工作前建议先阅读。本文件与其保持一致，冲突时以 `ai.memory/` 与当前构建脚本为准。

## 项目概览

- **产品**：上海华软 **Envi3D 2026（环境设计）** —— CAD/BIM **机电(MEP)插件套件**。
- **形态**：ObjectARX / ZRX 插件（DLL，后缀 `.arx` / `.zrx`），运行在 CAD 宿主内，含大量 MFC 界面与自定义图元实体。
- **CMake 项目名**：`SHS_Code2026`（version 1.0.0）。
- **主代码目录**：`SourceCode/Code2026/`（C++ 约 2888 `.cpp` + 3104 `.h`；另有天正 `tg_shs/` 系列库）。
- **远端**：`origin` = `ssh://gjm@47.93.46.28:1216/srv/git/new-start.git`，主分支 `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/` 目录下执行（preset 与 `cmakepresets.json` 同目录）：

```bash
cd SourceCode/Code2026

# 配置 + 编译（示例：AutoCAD 2025-2026）
cmake --preset R250
cmake --build --preset R250

# 只构建单个目标（例如某个模块）
cmake --build --preset R250 --target HvacCmd
```

- 要求 CMake ≥ 3.21；生成器固定 `Visual Studio 18 2026`，架构 `x64`。
- 工具集（toolset）由 preset 指定，随 CAD 版本变化：`v143 / v142 / v141 / v140 / v110 / v100 / v90`。
- C++ 标准自动切换：ARX 26 → C++20；ARX 20~25 与 ZRX → C++14；ARX 20 → C++03；更老 → C++98。
- 输出目录：`bin/Code2026/{Debug|Release}-x64-<标签>` 与 `lib/Code2026/...`，标签形如 `R250` / `Z2026`。
- Debug 构建会通过 post-build 调用 `copyarx.exe`，按 `sh_output_path.json`（ACAD）/ `zw_output_path.json`（中望）把产物部署到 `c:\ShangHuaSoft\Envi3D-2026-M`。

### 预设（`SourceCode/Code2026/cmakepresets.json`，共 13 套）

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

关键 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` → 调用 `cmake_batch_build.py` 批量编译多个 preset。
- 打包脚本：Inno Setup（`*.iss`）+ Python（`SHSCompile.py`）+ 多个 `.bat`，覆盖 ACAD/中望、1 年期/加密版，以及客户专版（中广核、国能集团等）。如 `环境设计-ACAD-加密自动打包.bat`、`环境设计-中望-1年期自动打包.bat`。

### CMake 构建体系（`cmake/`）

- `cmake/functions.cmake`：核心封装
  - `add_custom_module(dir folder)`：注册子模块（自动 `add_subdirectory` + 设 FOLDER）；`add_custom_module_2(dir target folder)` 用于目录名≠目标名的情况。
  - `target_link_objectarx(target EXT)`：链接 CAD SDK、全局头 `ShsGlobalIncludes`、定义 `CMAKE` 与 `ARX=<版本>`。
  - `simple_link_cad_sdk`：按 `IsZWCAD()` 自动选择 `ThirdParty::ARX` / `ThirdParty::ZRX`。
  - `set_encryption_definitions_and_output_path(target MODE)`：**授权模式**，见下。
  - `set_debug_post_build`：调用 `copyarx.exe` 部署。
- `cmake/ThirdPartyDeps.cmake`：定义 `ThirdParty::ARX` / `ZRX` / `SQLite3` / `cURL` / `TG` / `modernGlue` / `BitAnswer` 等接口目标；按 SDK 版本条件追加库（如 `acdrawbridge` 需 >19，`acpal`/`acgeoment` 需 >23）。
- 顶层 `cmakelists.txt`：`add_custom_module` 注册全部模块并组织 `FOLDER`（`SH/Core`、`SH/Pipe` …）。

## 授权 / 加密

- `CoreCommand`、`CoreLibrary` 通过 `get_encryption_modes()` 由**同一套源码编译出两个目标**：
  - `BAL_REMOTE`（网络锁 / 正式版）
  - `TRIAL_YEAR`（1 年期试用版，定义 `TRIAL_YEAR=<年份>`）
- 依赖 **BitAnswer**（加密狗库）；加密表由 `utility/generateEncryptionTable` 生成。

## 架构

分三层：

1. **实体层**：`CoreLibrary` 定义海量自定义图元 `AecDbXxx`（继承 `AcDbEntity`），是数据模型核心；同时含绘图/分解/布尔等基础能力。
2. **命令层**：各 `*Cmd` 模块实现 MFC 对话框 + Jig 交互 + ARX 命令注册。
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`, `PipeHanger`, `PlumbingCmd`, `Pool3dCmd` | 管道/工艺/ISO 图/支吊架/给排水/水池 |
| `SH/Structures` | `ArchCmd`, `ElecCmd`, `HvacCmd`, `SPLDCmd` | 建筑/电气/暖通/道路 |
| `SH/Other` | `shsTK`, `Dimension`, `EarthWormMain`, `EarthWormCmd` | 通用工具、标注、主程序 |
| `TG/*` | `tg_shs/*` | 天正系列库 |

关键模块：

- **CoreLibrary**：数据模型核心（自定义实体 `AecDbXxx`）。
- **AecRxBase**：ARX 基类库（`AecDbEntityBase`、`AecDbCurveBase`、Grip、双击编辑等）。
- **CoreCommand**：主命令集 + MFC 主界面/面板（BIM 面板、AI 助手面板等）；**生成两种加密版本**。
- **CoreImplement**：仅在 Debug 下有效（自定义实体的实现层）。
- **StartApp**：C# (.NET WinForms) 启动器，不走 CMake，保留独立 `StartApp.sln`。
- **tg_shs/**：天正系列（`shs_kernal`/wfK、`shs_twtkernal`/wfKernal、`shs_GeLib`、`shs_annotate`/wfA、`shs_twtanotate`/wfAnnotate、`shs_blklib`/wfB、`shs_siteplan`/wfS、`shs_pipewire`/wfpipew、`shs_outdoor`/wfoutdoor、`shs_ximage/*` 图像库、`shs_dbf`、`shs_sqlite` 等）。

## 目录结构

```
envi-code/
├── Arx/                 # AutoCAD ObjectARX SDK（R19.0~R26.0，gitignore）
├── ZRX/                 # 中望 ZRX SDK（Z2023~Z2026，gitignore）
├── SourceCode/
│   ├── dep_inc/         # 第三方头：modernGlue、rapidjson、curl
│   ├── dep_lib/         # 第三方库：modernGlue、pub(含 sqlite3/BitAnswer)
│   └── Code2026/        # ★ 主代码 + cmakelists.txt + cmakepresets.json + cmake/
├── bin/, lib/           # 编译产物（按 SDK 版本分子目录，gitignore）
├── cmake_output/        # CMake 生成目录（gitignore）
├── autoCompile/         # 打包/加密/发布脚本（.bat/.py/.iss）
├── utility/             # generateEncryptionTable（授权加密表生成）
└── ai.memory/           # 跨机器项目记忆
```

## 新增模块约定

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

```cmake
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>)
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`。
- **源码编码为 GBK/ANSI（无 BOM）**：新增或修改的 `.cpp/.h` 必须保存为 GBK。若存成 UTF-8，MSVC 会按 GBK 误读其中的中文，导致 `C2001: newline in constant`（中文全角标点如 `。` 紧跟字符串结尾引号时尤其容易触发）。提交前可用 `python -c "open('f.cpp','rb').read().decode('gbk')"` 校验。
- 部分库仅在特定 SDK 版本可用（如 `acdrawbridge` 需 >19，`acpal`/`acgeoment` 需 >23），已在 `ThirdPartyDeps.cmake` 处理。
- **禁止**新增或依赖 `.vcxproj` / `.sln`（`StartApp` 除外）。`cmake_output/` 下 CMake 生成的临时 `*.vcxproj` 是构建产物、已被 gitignore，**不要**误提交。
- `.gitignore` 忽略：`Arx/`、`cmake_output/`、`bin/`、`lib/`，以及 `*.obj/*.pdb/*.user/.vs/` 等 VS 中间产物。