环境配置与运行

本页说明工具链配置、启动调试、验证命令和数据库操作入口。编码要求见后端工程规范、前端工程规范和公共开发约定。

以下命令均从仓库根目录执行。前端和文档站使用 pnpm --dir 指定目录，无需切换当前工作目录。

前端和文档站的 package.json 均声明使用 pnpm；文档站以 pnpm-lock.yaml 为唯一依赖锁定源，package-lock.json 仅为历史兼容文件，禁止使用 npm install 重新生成或更新它。若要清理历史锁文件，另行提交专门变更，不在普通开发任务中顺手删除。

统一工具入口

项目不依赖某台电脑的绝对路径。通过 dev.ps1 调用工具，入口会解析并检查所需工具；正常命令成功即证明本次可用，无需再执行预检。新环境需要定位工具或工具链异常时使用 dev.ps1 doctor <工具>，不把全工具诊断作为每次任务前置步骤。

每台电脑可从 .agents/tools/toolchain.example.psd1 复制一份 .agents/tools/toolchain.local.psd1，填写本机 JDK、Maven、Node、pnpm 和 Python 路径。该本机文件不提交 Git。数据库连接配置放在 .agents/mcp/dm8-mcp/.env。

常用入口：

.\.agents\tools\dev.ps1 java -version
.\.agents\tools\dev.ps1 maven -version
.\.agents\tools\dev.ps1 node --version
.\.agents\tools\dev.ps1 pnpm --version
.\.agents\tools\dev.ps1 python --version

报告“工具不存在”前必须先运行 doctor 诊断。

诊断只选择所需工具，例如 dev.ps1 doctor pnpm（同时检查 Node）或 dev.ps1 doctor maven（同时检查 Java）；不带工具名时检查全部。无关工具缺失不阻塞当前任务，主 Agent 和子 Agent 可复用同环境的有效诊断，工具链变化或异常后重新核对。OK 仅表示定位到工具文件，实际命令运行结果才证明可用。

传入可能与 PowerShell 参数名冲突的参数（如 Python -c）时，显式使用 -Command python -ToolArgs @('-c', '<代码>')；该包装脚本不接收管道标准输入，多行脚本使用脚本文件或参数数组。

启动顺序

1. 确认数据库和 Redis 可访问。
2. 任务需要时启动 SnailJob、SnailAI 等独立服务。
3. 在仓库根目录运行统一入口；默认启动前后端，可显式选择单端。已有监听进程先核对项目归属，不自动终止或替换其他服务。

.\.agents\tools\dev-env.ps1 ensure
.\.agents\tools\dev-env.ps1 ensure -Service backend -TimeoutSeconds 120
.\.agents\tools\dev-env.ps1 ensure -Service frontend

只需要查看状态时：

.\.agents\tools\dev-env.ps1 status

端口已监听不等于接口健康或本次代码已加载。脚本核对进程归属并在启动进程提前退出时立即报告失败；不能确认归属时报告端口占用，不自动杀进程。真实接口回归前仍核对应用可用性及相关代码已加载。前端启动脚本默认不自动打开浏览器；页面验证按根 AGENTS.md 由 Agent 按改动范围自行执行。统一入口固定使用前端 80、后端 8080；ensure 默认复用已有服务，不自动重启，任务需要加载本次代码时按下文核对后重启本项目本地开发服务。

进程归属核对会检查监听进程及其父进程链；统一入口启动的 PowerShell 包装进程使用 -EncodedCommand 时，脚本会解码其命令再匹配仓库路径。

复用已有服务验证本次修改时，先只读核对服务进程归属、启动时间及其运行代码或产物是否包含本次变更；前端热更新后刷新目标页面，后端可结合启动记录、构建产物和本次行为的可观察结果判断。仅有端口、健康接口或旧版本用例通过，不能证明本次代码已加载。确需重启时，先核对环境、监听进程及父子进程归属，定向停止已确认属于本项目的既有本地开发服务，再用 dev-env.ps1 ensure -Service backend 或 -Service frontend 启动，核对服务可用性及本次代码行为；服务由此前任务启动不构成额外确认点。不明归属、其他项目以及生产或其他受保护环境的服务不适用此项重启授权。无法确认进程归属或代码新鲜度时，继续可执行的静态与独立检查；若因此无法取得本任务必要的真实接口或页面检查结果，将对应范围标为“验证受阻”，不用旧代码运行结果证明本次修改。

Windows 使用 Java 21 时，项目已在 DigitalConstructionApplication、Spring 早期环境处理器（WindowsNettyEnvironmentPostProcessor）及根 POM 中内置 Windows/Java 21/Netty 本地回环兼容自愈机制：自动检测 Windows 环境，优先使用工程内短路径 .tmp 目录（规避 AF_UNIX 108 字节路径硬限制），并自动设置 IPv4 优先、禁用 Netty 本地 JNI 探测和限制事件循环线程数。因此在 IDEA 中直接右键启动、执行单元测试（mvn test）或执行 mvn spring-boot:run 均已开箱即用，不再需要手动配置 VM Options。Spring Boot 4 的早期处理器实现应使用 org.springframework.boot.env.EnvironmentPostProcessor；该接口包名须与 spring.factories 及 .imports 注册项一致，否则应用会在环境准备阶段启动失败。

dev-env.ps1 ensure 会自动保障工程内 .tmp 安全目录并注入同等参数，亦支持通过 $env:DCP_JAVA_TEMP_DIR 自定义路径；脚本会自动创建缺失目录，不再要求人工前置在系统盘创建 C:\Temp。

需要前台查看日志或单独调试时，在不同终端分别启动后端和前端。

后端：

.\.agents\tools\dev.ps1 maven -pl digital-construction-admin -am spring-boot:run

后端启动类为 digital-construction-admin/src/main/java/com/bokun/DigitalConstructionApplication.java。其中 -am 会先纳入并编译 admin 依赖的工程模块；根 POM 已声明 Spring Boot Maven 插件，避免从工程根目录执行该命令时出现 No plugin found for prefix 'spring-boot'。

前端：

.\.agents\tools\dev.ps1 pnpm --dir .\digital-construction-ui install
.\.agents\tools\dev.ps1 pnpm --dir .\digital-construction-ui dev

Windows 运行已打包后端 jar

Windows 本地用 Java 21 运行已打包后端 jar 时，由于代码内已内置自愈逻辑，直接使用 java -jar 即可正常启动；如需在命令行显式显性指定参数，可使用如下命令：

.\.agents\tools\dev.ps1 java `
  '-Djdk.net.unixdomain.tmpdir=.tmp' `
  '-Djava.io.tmpdir=.tmp' `
  '-Djava.net.preferIPv4Stack=true' `
  '-Dio.netty.transport.noNative=true' `
  '-Dio.netty.eventLoopThreads=2' `
  '-jar' `
  'digital-construction-admin\target\digital-construction-admin.jar'

这组参数适用于 Temurin、Dragonwell 等 Java 21 发行版的 Windows 本地开发验证，Linux 生产部署不施加改动。已验证 Temurin 21.0.12.1+1 与 Dragonwell 21.0.11.0.11 可稳定启动。IDEA 和 Maven 不要同时启动同一服务，避免端口冲突。

验证入口

常用检查汇总

轻量入口复用现有工具，不自动按文件路径推断验证范围，也不启动浏览器或修改数据库。默认只检查文档；显式选择需要的检查，独立只读检查默认最多两项并发，测试单独执行以避免共享缓存竞争；任一检查失败则整体返回失败。

.\.agents\tools\verify.ps1
.\.agents\tools\verify.ps1 -Check Docs,FrontendLint -Preview
.\.agents\tools\verify.ps1 -Check FrontendLint -LintPath 'src/components/YearSelect/yearOptions.ts'
.\.agents\tools\verify.ps1 -Check FrontendLint,FrontendTypes -LintPath 'src/components/YearSelect' -ThrottleLimit 2
.\.agents\tools\verify.ps1 -Check FrontendTest -TestPath 'src/components/YearSelect/yearOptions.spec.ts'
.\.agents\tools\verify.ps1 -Check FrontendFormat -FormatPath 'src/components/YearSelect/yearOptions.ts'
.\.agents\tools\verify.ps1 -Check RuleRefs

-Preview 只显示命令，不执行验证。FrontendTest 必须指定实际测试文件，FrontendFormat 必须指定实际格式检查文件或目录；FrontendLint -LintPath 接受受影响文件或目录，省略时保留全 src lint。路径相对前端目录，多个路径使用数组传入；类型检查仍分析全工程依赖，不机械裁成单文件。-ThrottleLimit 为 1～4，设为 1 顺序执行；单项检查不启动并发作业。RuleRefs 检查根 AGENTS.md 与 .agents/skills/** 下全部 Markdown 的严格 UTF-8、相对链接和锚点，并校验 SKILL.md 声明，规则文件改动后运行。

按需用 -ReportPath '<已存在目录>/验证结果.json' 保存命令、范围参数、开始时间、耗时和退出码，失败结果也保留；默认不生成报告文件。预览禁止与报告路径同时使用，避免覆盖真实证据。过程报告放忽略的 test-artifacts/ 等目录；参数和报告不放凭据。JSON 不代替工具的用例明细，前端测试执行/失败/跳过数量仍核对原输出。选择检查时结合调用链，共享权限、状态和序列化变化不能仅按文件位置缩小回归；这些结果不代表页面或完整业务验收。入口不默认执行全量构建、安装依赖或修复代码。

后端与前端专项验证

后端：将 <模块> 替换为本次涉及的 Maven 模块路径，按公共开发约定 · 验证范围选择入口。以下命令是不同检查范围，不是每次依次执行的步骤。

编译检查：适用于只需证明编译正确性的改动；不能代替受影响核心行为的回归。

.\.agents\tools\dev.ps1 maven -pl '<模块>' -am compile

定向回归：优先指定能覆盖影响范围的现有测试类，使用包装入口自动核验实际执行证据：

.\.agents\tools\verify-backend-tests.ps1 -Module '<模块>' -Test '<目标测试类>'

-Module 指向仓库内单个含 pom.xml 的目标模块；-Test 接受逗号分隔的精确简单类名或全限定类名，不接受通配符或方法筛选。可用 -Profile 选择单个 profile，-Preview 只预览；-ReportPath 可保存本次命令、目标模块、逐类执行/失败/错误/跳过数与证据问题，不能与预览同时使用。

入口固定显式设置 -Dmaven.test.skip=false、-DskipTests=false，通过 -am 构建上游，-Dsurefire.failIfNoSpecifiedTests=false 允许上游没有目标测试。目标模块必须有本次新生成或重写的 Surefire XML，逐个目标类至少执行一个非跳过用例，计数与明细一致且无失败/错误，Maven 退出码也必须为零。旧报告、缺失或全跳过不能通过；参数化和嵌套用例按明细计数，部分跳过单独报告。不得在同一模块并发运行其他 Maven 测试，以免混入其他运行的报告。-Dtest 只筛选执行，不保证只编译所选测试源码。

确需方法筛选等包装入口不支持的场景，仍可通过 dev.ps1 maven 传入明确参数，显式关闭跳过选项并人工核对本次报告；不能用不支持的参数静默降级为全量测试。

完整模块回归：用于影响范围无法可靠收敛、大范围模块变化或正式模块交付。

.\.agents\tools\dev.ps1 maven '-Dmaven.test.skip=false' -pl '<模块>' -am test

根 POM 的 Surefire 同时使用 <groups>${profiles.active}</groups> 和 <excludedGroups>exclude</excludedGroups>。当前默认 dev profile 对应 @Tag("dev")，现有业务回归采用该标签；新增测试沿用同类标签，切换 profile 时核对选择范围。关闭 maven.test.skip 不会取消标签过滤。

回归后检查目标模块 target/surefire-reports/ 本次生成的报告，确认目标测试类实际执行，记录执行、失败和跳过数量。目标测试缺失、执行数量为零或只有旧报告时，不得凭 BUILD SUCCESS 报告通过；先排查标签、profile 和筛选条件，不通过删除过滤或跳过测试伪装通过。

修改验证脚本后可运行 .agents/tools/tests/verify-tools.tests.ps1：它用隔离临时报告和替代 Maven 入口验证证据判定与退出码，不连接数据库，也不替代项目业务回归。

前端：按任务风险选择相关命令，将 <相关 spec> 替换为相对前端目录的测试文件路径；无需每次全部执行。

.\.agents\tools\dev.ps1 pnpm --dir .\digital-construction-ui vitest run '<相关 spec>'
.\.agents\tools\dev.ps1 pnpm --dir .\digital-construction-ui exec vue-tsc --noEmit
.\.agents\tools\dev.ps1 pnpm --dir .\digital-construction-ui lint
.\.agents\tools\verify.ps1 -Check FrontendFormat -FormatPath 'src/<相关文件或目录>'
.\.agents\tools\dev.ps1 pnpm --dir .\digital-construction-ui build

提交与发布安全

首次使用本仓库时，在仓库根目录启用版本化提交钩子；该配置写入当前仓库的本地 Git 配置，不会修改全局 Git：

git config core.hooksPath .githooks

commit-msg 和 pre-push 钩子以及文档发布脚本共同调用 .agents/tools/check-commit-message.ps1。提交标题必须有中文摘要，正文中的自然语言也必须使用中文；命令、路径、类名、接口标识、版本号、提交元数据等必要技术内容可以保留原文。pre-push 会按本次推送范围再次检查新提交，避免单次提交钩子被跳过后把英文提交带入远端。手动检查提交信息时可执行：

powershell -NoProfile -ExecutionPolicy Bypass -File .\.agents\tools\check-commit-message.ps1 -MessageText "通用：修复：示例问题"

提交标题示例：项目管理：新增：项目成员批量导入功能、公文协同：修复：公文编辑请求参数格式错误、工程基础：优化：项目列表查询性能、通用：文档：精简协作规则与交付入口。不隶属于具体模块时使用“通用”；必要类名、方法名、路径及 Issue/PR 号保留原文。

提交推送的触发条件、分支、暂存范围、待验收情形的处理和例外条件按根 AGENTS.md 的“Git 提交信息规范”执行，本节不再重复；普通提交推送直接使用 Git，不调用文档发布脚本，发布脚本的目录限制和构建检查不扩展为普通推送门槛。提交或推送只表示变更进入版本控制流程，不表示业务验收通过、页面验收通过或正式发布。推送前还要核对当前分支的上游和未推送提交范围；文档发布脚本默认拒绝推送包含文档站之外文件的未推送提交。只有已经明确授权把其他提交一起推送时，才使用 -AllowOtherOutgoingCommits，并在交付回报中说明。

文档检查与发布

普通内容修改执行轻量检查；仅在用户明确要求本地文档构建或发布到服务器时执行构建。单独请求本地构建时只执行构建，不提交、推送、上传或发布，也不需要服务器发布授权。文档检查在写文档阶段完成，发布脚本不再重复执行：

.\.agents\tools\dev.ps1 pnpm --dir .\digital-construction-ui-docs docs:build

需要复检文档内容时手动执行 docs:check；需要核对构建产物时手动执行 docs:check:dist，两者都不进入发布脚本。

docs:check 检查根 AGENTS.md、项目 Skill 和文档站 Markdown 的严格 UTF-8 编码、本地链接/图片及标题锚点，并核对导航链接；同时报告未被导航或任何页面引用的文档站孤儿页面（站点首页、文档站根 README.md 和 deploy/ 私有部署资料不参与该项），并校验 modules/ 下六类文档头部的 文档版本 是否存在且为两位小数。敏感信息扫描覆盖规则文件和将进入文档站的公开文本，跳过不发布的 deploy/、检查脚本和本机私有配置；根 README.md、业务源码、MCP 运行说明和附件不在这条公开文档扫描中，不能把通过 docs:check 表述为全仓库敏感信息审查，仍需按发布范围人工核对。docs:check:dist 扫描本次构建的最终文本产物；命中只输出文件、位置和规则名称，不输出匹配内容。

扫描识别私钥、常见访问令牌、带凭据 URL 和明确的密码/密钥赋值；示例使用 <占位符>、${环境变量} 或明确的“示例/你的密码”等占位值。文本扫描不能保证识别全部敏感信息；附件、图片、业务敏感信息和内部地址仍须人工核对。外部链接不联网检测。

一键发布脚本 digital-construction-ui-docs/deploy/publish-docs.ps1 按“构建 → 提交推送 → 上传”执行，构建失败即停止，不继续提交推送或上传。发布前不重复运行 docs:check 和 docs:check:dist，文档质量与敏感信息检查由写文档时的 verify.ps1 负责。用户已有明确授权的普通提交推送按根 AGENTS.md 执行。脚本会校验提交信息；推送前默认要求上游与实际目标 origin/<当前分支> 一致，并逐个检查未推送提交涉及的文件；业务改动即使随后回退，仍属于推送范围。只构建、不提交推送或上传时使用 -CheckOnly。证据格式见最新验证证据。

修改发布范围门禁后，可从仓库根目录运行 digital-construction-ui-docs/deploy/test-publish-docs.ps1 做离线回归：它在独立临时仓库运行真实发布脚本的范围检查逻辑，替代构建入口并拦截推送，覆盖文档路径、回退、合并和显式授权，不连接远端或上传。

正常发布不自动暂存整个文档目录。需要创建提交时，以 -CommitPath 显式传入仓库相对的具体文档文件数组，例如 -CommitPath 'digital-construction-ui-docs/index.md'；指定文件按当前工作区的完整内容提交，不保留该文件内的部分暂存选择，其他文件的暂存内容保持不变。同一文件含无关改动时，不把它直接传给 -CommitPath；普通提交先按片段仅提交已授权内容。发布仍须满足以下工作区与产物范围检查，不通过扩大提交范围或使用 -SkipGit 绕过。未指定时不创建提交，但仍可推送已有的文档站提交；推送前会检查分支的未推送提交是否包含其他目录，支持此前提交成功而推送失败的重试。正常 Git 发布要求文档目录没有剩余未提交改动，避免上传产物混入其他任务内容；仓库其他目录的暂存不阻塞文档发布。-SkipGit 保留显式跳过 Git、直接使用工作区构建的模式，不与 -CommitPath 混用；-CheckOnly 不执行提交、推送或上传。调用发布脚本本身仍须处于用户授权的发布范围，构建成功不等于取得发布授权。

验证范围

验证层次、复用和停止条件见公共开发约定 · 验证范围，各端特有检查见对应开发规范。真实页面的检查范围、用户指定的分工、证据依赖与暂停条件以根 AGENTS.md 为准；源码、类型检查、构建及示例预览不能证明页面交互通过。

按根 AGENTS.md“验证与页面证据”，由 Agent 根据实际风险选择足够的检查，用户显式要求浏览器验证时执行；不因前后端任务或改动数量一律启动浏览器。选用浏览器后从真实入口操作，不能以 API 注入或内部状态冒充，文件上传例外按根规则。必要检查遇工具或环境障碍时，在授权内排障后仍无法完成则报告“验证受阻”，继续独立检查，不自动转给用户或追加整套无关检查；已有足够证据且未选择浏览器时不因此标为受阻。实现与验证状态分别按交付状态定义报告。

具备交互环境且需要登录时，Agent 主动读取私有根 README.md“私有开发环境账号”，按受影响角色使用，无需请示。读取后确认文件/账号缺失，或登录证实账号失效，才因账号问题标为“验证受阻”；账号可用但浏览器拒绝安全输入或操作失败时，先尝试允许的其他真实入口，仍失败则按工具障碍报告，不认定账号失效或要求重复提供。凭据不得进入公开文档、Issue、截图、日志、外部材料或交付回报，证据只记录角色。

账号、权限、工具操作或代码新鲜度问题使必要检查无法完成时标“验证受阻”；用户豁免列“未验证”，用户指定的验收列“待验收”，不得混用，也不因未选浏览器自动产生待验收项。证据字段见最新验证证据。

数据库操作

数据库查询、结构检查、DDL、DML、迁移、初始化和验证 SQL 统一通过项目纳管入口执行；开发库使用项目 MCP dcp-dm8-dev，入口是 .agents/mcp/launch.ps1，生产库须另行核实已获授权的项目纳管生产入口。仓库不保存业务 .sql 文件，不使用命令行 SQL 客户端、临时 Java/Python 直连或项目外 MCP。开发客户端注册模板和启动说明见 .agents/mcp/mcp.json 与 .agents/mcp/README.md。

执行前核对环境、对象和影响范围，执行后回读验证；DML 报实际影响行数，DDL 报对象变更结果。AI 的开发数据库操作授权以根目录 AGENTS.md“不可省略的硬约束”为准。正式交付使用经过清理、脱敏并验证可恢复的 DM8 备份或导出包。

表结构与流程定义双环境同步

根 AGENTS.md 规定普通开发与生产发布分开；用户授权修改或升版流程 JSON 后即有双库专项授权，默认由 Agent 同步 dev、prod 并完成必要发布/启用，无需额外实施口令，用户当次限制优先。本节维护实际同步步骤；本授权不扩展到无关配置、业务数据或运行实例。表结构包括表、字段、类型、默认值、约束和索引；流程定义数据包括版本、节点、连线、办理人规则、流转条件、布局及必要关联配置。

1. 开发实施：核对本次对象，完成开发环境变更和真实验证；只改代码或 JSON 不能声明数据库同步完成。用户限定仅改文件时遵从限制，交付文件成果并列开发环境待执行范围。
2. 待发布清单：在受影响模块现有数据库设计或流程详细设计的发布章节保留可追踪清单；按内容归入一处，交付回报链接引用，不新增流水日志。记录对象/源文件及版本、开发验证证据、拟发布差异、旧新应用或定义的兼容条件、存量数据/在途实例影响、执行顺序、核验方式和回退或恢复方案。未经授权未访问生产时，生产现状标“发布前待回读核对”，不猜测真实差异；范围明确的小变更可用紧凑表格，不要求大方案。用户限制文档修改时在交付回报提供清单并注明待归档。
3. 生产发布前核对：表结构等普通生产发布须有具体授权；流程定义双库授权按根规则直接执行，无需重复请示。通过纳管入口回读生产现状，更新实际差异及方案；有新增影响超出授权时仅暂停依赖部分。发布前清单必须逐项核销，不能因开发任务结束而漏掉结构或定义变更；与应用强耦合的变更按兼容顺序成套发布。dcp-dm8-dev 不能冒充生产入口，也不能为同步擅自切换受保护连接配置。
4. 同步与版本保护：只同步本任务结构及流程定义，不复制业务数据、运行实例、历史办理记录或覆盖环境专属配置。流程版本和发布状态分别按目标环境核对，不照搬开发物理 ID；已发布版本和在途实例按流程编排规范保护，明确兼容和切换方式。
5. 回读与结项：每个执行环境分别记录对象、前后差异、结果与证据，不含凭据或私有地址；DDL 核对结构，流程定义核对版本、内容与发布状态，DML 报影响行数。执行失败时说明错误、已产生的变更及恢复措施，不盲目重试。prod 内网经有限连通检查确认不可达后停止本次尝试，完成 dev 与独立验证、记录生产待同步后交付，不持续等待、不默认让用户手动导入；恢复时重读生产现状。已连接但导入失败不得归为网络不通。普通表结构开发保留清单即可交付“开发完成、生产待发布”；其他未完成的发布明确原因。仅当两库实际执行、回读及适用验证均通过才称“双环境同步完成”，成功后更新清单对应条目的发布结果。

私有配置

私有环境凭据台账在私有仓库根 README，本机覆盖在 Git 忽略的私有配置中；凭据不得进入公开文档站、Issue、截图、日志、外部材料或其他仓库。本项目私有仓库受跟踪的 application*.yml 可按实际环境维护配置，也可使用环境变量或忽略的私有配置覆盖；不再单独禁止生产 profile 的凭据入库。维护凭据或连接目标仍须满足根规则的受保护配置授权。

应用本地覆盖当前没有仓库内示例：按根 pom 的 local profile，只有本机自行放置已被 Git 忽略的 application-local.yml 并激活 local profile 时才会被 Spring Boot 加载，默认 dev profile 不读取该文件。

对象存储（MinIO）连接配置位于 application.yml 的 oss 节点，含 config-key、endpoint、domain-url、prefix、access-key、secret-key、bucket-name、region、is-https 和 access-policy；config-key 是上传文件记录中的存储服务标识。连接配置不再从数据库读取，全部字段可用同名大写环境变量覆盖（如 OSS_ENDPOINT、OSS_ACCESS_KEY、OSS_SECRET_KEY），部署时按环境注入，不写入公开文档站。

交开投影像服务端代理配置

JKT_TILE 影像统一经平台后端代理取图，上游账号与 token 不进入浏览器。服务端凭据按数据库 credentialRef（默认 JKT_MAP）从环境变量读取：JKT_MAP_USERNAME 及 JKT_MAP_PASSWORD_MD5（或 JKT_MAP_PASSWORD），也可通过 GIS_JKT_CREDENTIALS_FILE 指定私有 properties 文件。真实值从项目私有凭据台账“交开投 2.5D 影像”小节取得，由部署人员注入，不写入仓库与文档。

生产 142 以 systemd drop-in 注入（/etc/systemd/system/digital-construction-platform.service.d/jkt.conf 的 [Service] 段配置 Environment=JKT_MAP_USERNAME=…、Environment=JKT_MAP_PASSWORD_MD5=…，改后 systemctl daemon-reload && systemctl restart digital-construction-platform）。开发本地可用仓库忽略的 .tmp/gis-jkt.properties（默认 GIS_JKT_CREDENTIALS_FILE 指向位置）。

网络前提：后端代理要求平台服务器能访问供应方影像服务 113.207.1.170:5005（HTTP）。2026-11-08 实测华为云 VPC（142/141/68）均未放行公网出方向，生产出图前需由网络管理开通 142 → 113.207.1.170:5005/TCP；开通前生产选择该底图会返回 502。前端不读取任何交开投配置，构建产物不含供应方凭据。

BIM 底座运行依赖（黑洞引擎）

黑洞引擎按环境使用独立项目空间，项目 ID 由 profile 配置固定，凭据只经部署环境注入：

环境	引擎服务端地址	项目空间	浏览器端资源
dev（含本机开发）	http://15.50.3.12:9012	交开投数智建管平台-DEV（3a24c81b-151f-9a5c-169e-f5d79bc12be8）	直接访问引擎
prod	http://15.50.3.12:9012	交开投数智建管平台-PROD（3a24ce26-7194-6c89-6494-439cf8b0fdab）	经平台 8888 的 /blackHole3D/ 同源反代

配置分两层：

• application-dev.yml / application-prod.yml 分别固定本项目空间的 bim.engine.base-url、proj-id、bim.engine.origin 与 bim.viewer.resource-base；部署时仍可用同名环境变量覆盖，但不得用同一项目 ID 同时服务两环境。
• 账号与密码在 application-dev.yml / application-prod.yml 中提供可被环境变量覆盖的默认值（实际值见私有根 README.md）；部署环境仍以 dev /etc/digital-construction-platform/preview.env、prod /etc/systemd/system/digital-construction-platform.service.d/bim.conf 覆盖。凭据不进入浏览器、公开文档、截图与日志。

BIM_ENGINE_BASE_URL=http://<引擎主机>:<端口>
BIM_ENGINE_USERNAME=<服务端账号>
BIM_ENGINE_PASSWORD=<服务端密码>
BIM_ENGINE_PROJ_ID=<该环境项目ID>
BIM_ENGINE_ORIGIN=<浏览器访问引擎的源>
BIM_ENGINE_USE_REQUEST_ORIGIN=true   # 生产经平台同源反代时开启
BIM_RESOURCE_BASE=<资源根地址>
# 可选：BIM_ENGINE_FOLDER_NODE_ID、BIM_ENGINE_CHUNK_MB（默认4）、BIM_UPLOAD_MAX_SIZE_MB（默认2048）

• 前端 SDK 固定使用与引擎部署同版本的资产（本部署 3.2.0.3772），放在 digital-construction-ui/public/bh-sdk/<版本>/javascript/，按版本目录隔离浏览器缓存；该目录随前端构建产物发布，不提交到仓库。升级引擎后需同版本替换 SDK 并重验加载、选择、属性。
• 初始化必须注册资源授权与路径索引（addAuthorPath/addPathIndex，配合 window.pathCtrlUrlTxt/pathCtrlUrlRes/pathCtrlUrlIndex/skyBoxUrl/minIOUrl/isMinIO）；缺少注册时引擎只会有加载回调而无几何。
• 生产页面只经 HTTPS 8888 提供，浏览器不得直接请求 HTTP 引擎资源（混合内容会被拦截）。生产 nginx 增加 /blackHole3D/ 同源反代并透传 Host，后端按请求 Origin 生成 SDK 与资源地址（BIM_ENGINE_USE_REQUEST_ORIGIN=true），IP 与域名入口各自同源。
• 大文件：平台 multipart 默认 2G（SPRING_MULTIPART_MAX_FILE_SIZE/SPRING_MULTIPART_MAX_REQUEST_SIZE 可覆盖）。2026-11-09 已将 dev 的 minio.tangyucong.top、prod 的 /fourthphase-minio/、两端 /dev-api/、/prod-api/ 均调整为 2g 并关闭请求体缓冲；配置备份为 *.bak-bim-* / *.bak-20261109-bim。
• 开发服务器 1.12.68.9 位于腾讯云，当前无法访问内网引擎 15.50.3.12:9012（TCP 连接超时），远程 dev 的转换与预览暂不可用；本机开发环境可直连引擎，BIM 链路以本机开发验证为准。生产 142 与引擎同内网，已实测可达。
• 引擎单槽位转换：同一时刻只处理一个转换任务，其余排队；大模型转换耗时显著，勿据单样本推断容量。

GIS CAD 入图运行依赖

• Python：开发环境使用 Python 3.14，需安装 ezdxf==1.4.5。GIS 模块 runtime/ 随仓库携带 Windows x64 可嵌入 Python 3.14.7 与锁定依赖；后端未显式配置 GIS_PYTHON_COMMAND 时，优先使用 runtime/python/python.exe，其次使用统一入口解析的工具链 Python，最后才用 PATH 的 python，IDEA 直接启动同样生效；显式配置 GIS_PYTHON_COMMAND 时以配置为准。运行时校验与重建见 digital-construction-modules/digital-construction-gis/runtime/README.md。2026-10-23 起 GIS 解析器只输出原始 CAD 平面清单，不再使用 pyproj，也不再读取旧坐标标定参数。生产 142（Kylin V10、x86_64、glibc 2.28、无外网）不能用系统 Python 3.7.9；2026-10-21 已验证随发布自带的 Python 3.12.15 + 离线 wheel 可运行。应固定版本并随发布打包解释器与 wheel，不在生产联网安装。
• DWG 转换：LibreDWG 0.14 dwg2dxf。Windows 开发运行时已随 runtime/bin/dwg2dxf/ 提交，未显式配置 GIS_DWG2DXF_COMMAND 时自动使用，开发同事不依赖 .tmp/tools；.tmp/tools 仅作为重建时的本机回退，显式配置 GIS_DWG2DXF_COMMAND 时以配置为准。官方未发布 Linux 预编译包，142 已从源码编译并验证 dwg2dxf 0.14 可用，生产需核对 GPL-3.0-or-later 的分发义务。开发服务器（1.12.68.9，Ubuntu 22.04）2026-10-24 已源码编译安装 /usr/local/bin/dwg2dxf（构建需 pkg-config，执行全量 make，make dwg2dxf 无该目标），并在 /etc/digital-construction-platform/preview.env 注入 GIS_DWG2DXF_COMMAND=/usr/local/bin/dwg2dxf；任务在 CONVERTING 前预检转换器可用性，缺失时以 CONVERTER_MISSING 失败并输出含配置与指引的中文错误。该机内存仅 2 GB，编译 LibreDWG 会使 DM8 被 OOM-kill，构建须限 -j2 以下并在业务低峰执行。
• 存储：开发默认 GIS_STORAGE_ROOT=.tmp/gis，保存上传源文件、解析配置和结果；生产必须配置为持久化绝对路径。生产服务工作目录为 .../current 软链，沿用相对 .tmp/gis 会在发布切换时丢失源文件和成果。
• 运行时路径：142 的验证产物当前位于 /opt/digital-construction-platform/staging/gis-runtime/（Python、wheels、LibreDWG）；正式启用前应移至 runtimes/ 并在 systemd 单元注入 GIS_PYTHON_COMMAND、GIS_DWG2DXF_COMMAND、GIS_STORAGE_ROOT，目录属主 dcpapp。
• 天地图：浏览器端 Key 通过 TIANDITU_BROWSER_KEY 或开发 profile 注入，会下发浏览器；服务器端 Key 不用于当前实现。
• 配准：解析阶段不做任何投影或坐标标定。新上传在版本工作台使用浏览器高德候选/手工点与原始 CAD 点对拟合，保存时由服务端派生平台坐标成果；gis.cad.transform.*、GIS_CAD_TRANSFORM_* 和 TM_APPROX 已退出配置与代码。
• 执行边界：POST /gis/drawings/receive 是唯一接收入口（受限线程池、GIS_CAD_WORKER_TIMEOUT 默认 900 秒、重启后在途任务标记中断可重试）；旧同步 POST /gis/drawings/import 映射已删除，请求返回 405。生产容量、并发和租约仍待 Q-GIS-007 冻结。
• 数据结构：开发库现有 18 张 GIS_ 表（3 张既有扩展 + 15 张保留新表）；GIS_TRANSFORM、GIS_CONTROL_POINT、GIS_TOPIC、GIS_SCENE_TOPIC 和 29 个退役列已于 2026-10-23 物理删除；查询与写入统一走项目 MCP 纳管入口。2026-10-24 生产库（68）已同步 GIS 新路线所需 14 张表 DDL、GIS_CRS/GIS_BASEMAP_SERVICE 基础数据与 30 行 GIS 菜单（含 normaladmin 角色关联）；生产无旧 GIS 表，不涉及旧表清理。