lyw-test-bos-geo v2.4.0

项目简介、代码编译说明和编码规范

1. 项目简介

• BOSGeoViewer 是 BOS 提供的一个 BIM+GIS 三维空间可视化组件。在集成海量 BIM 模型、实景三维模型、影像、地形等空间数据的基础上，提供一系列基于 BIM+GIS 的三维可视化场景查看和交互功能及接口，包括 BIM 模型数据搜索与空间定位、漫游、测算、空间分析、图层管理和路网提取等，实现地理空间的室内室外、地上地下一体化展示与管理。

• 相比于 BOS3DViewer，BOSGeoViewer 由于承载了 GIS 数据（倾斜摄影数据、矢量数据和栅格数据等），并提供了剖面分析、地形开挖等三维 GIS 特色的空间分析功能，可以实现空间大场景至小场景的逐级细化管理，适合于大型园区、城区级或城市级等大范围 BIM+GIS 数据的承载与展示。

• 代码结构说明请参考 ./Docs/BOSGeo代码结构设计.md 和 ./Docs/BOSGeo代码结构设计.xmind 文档.

2. 环境搭建说明（包括但不限于依赖说明和运行说明）

2.1 编译 cesium

cd cesium  //进入cesium子目录
npm install //安装依赖
npm run build
npm run release

2.2 编译项目

npm install //安装依赖

若无法安装，可尝试通过npm cache clean --force命令清理缓存后再安装。

2.3 运行测试案例

npm run start

2.4 打包项目

npm run build

2.5 生成 JSAPI 文档

npm run jsdoc

3. 编码规范

3.1 术语与缩略词

3.2 功能模块命名

|- /功能文件夹 |- 功能模块库 示例：

|- /Layers
	|- baseLayer.js

3.3 注释

3.3.1 文档注释

文档注释将会以预定格式出现在API文档中。它以“/**”开头，以“*/”结束，其间的每一行均以“*”开头（均与开始符的第一个“*”对齐），且注释内容与“*”间留一个空格。例如：

/**
 * comment
 */

文档注释必须包含一个或多个注释标签。

@module。声明模块，用法：

/**
 * 模块说明
 * @module 模块名
 */

例如：

/**
 * Core模块提供最基础、最核心的接口
 * @module Core
 */

@class。声明类，用法：

/**
 * 类说明
 * @class 类名
 * @constructor
 */

 @class必须搭配@constructor或@static使用，分别标记非静态类与静态类。

例如：

/**
 * 节点集合类
 * @class NodeList
 * @constructor
 * @param {ArrayLike<Element>} nodes 初始化节点
 */

声明函数或类方法，用法：

/**
 * 方法说明
 * @param {参数类型} 参数名 参数说明
 * @return {返回值类型} 返回值说明
 */

当函数为私有成员时，函数名须以短下划线_开头，同时必须使用@private 标签说明，私有成员不会在生成文档中输出任何内容，除非 JSDoc 使用 -p/--private 命令行选项运行；当函数有参数时，必须使用@param；当函数有返回值时，必须使用@return。 例如：

/**
 * 返回当前集合中指定位置的元素
 * @param {Number} [i=0] 位置下标。如果为负数，则从集合的最后一个元素开始倒数
 * @return {Element} 指定元素
 */

@param。声明函数参数。

当参数出现以下情况时，使用对应的格式：

[参数名][(参数名 = 默认值)]; // 参数无默认值 // 参数有默认值

@property。声明类属性，用法：

/**
 * 属性说明
 * @property {属性类型} 属性名
 */

如果某段代码有功能未实现，或者有待完善，必须添加“TODO”标记，“TODO”前后应留一个空格。例如：

// TODO 未处理IE8浏览器的兼容性
function setOpacity(node, val) {
  node.style.opacity = val;
}

3.3.2 修改源码命名注释

@Author+姓名+修改方式+日期+修改说明 A：新增，M：修改，D：删除 示例：表示 Frank 修改

// @Author-Frank-M-20200908 新增代码结构设计说明文档

4.代码管理规范

4.1 产品代码分支管理

代码库包含master、dev、feature、test和hotfixes分支，各分支说明如下

（1）master——主线分支，存放的是在生产环境部署后的稳定版本的代码。目前由陈飞负责维护，其他同事只有拉取权限。
（2）dev——开发分支，每次迭代版本的内容，从最新的 master 分支派生（陈飞负责操作）。当开发人员的 feature 分支需求开发完且自测没问题后申请合并至 dev 分支，dev 分支测试没问题后可申请提测并派生出 test 分支。目前由陈飞负责维护，其他同事只有拉取权限。
（3）feature——需求开发分支（新特性分支），从 dev 分支创建，命名规则为“feature-需求内容”，一旦该需求测试通过，便将其删除。
（4）test——测试分支，每次提测时从 dev 分支派生（研发负责人操作）。命名规则为“test-提测版本号”。测试环境中出现的 bug，由开发人员在各自的本地分支修复完成后，统一提交代码至该分支。迭代版本测试结束后，必须将修改内容合并到  master 分支，并关闭该  test  分支。
（5）hotfixes——紧急修复分支，在 master 分支发现 bug 并且需要紧急修复时，从  master  分支派生（研发负责人操作）。命名规则为  “hotfix-修复内容”。由开发人员在各自的本地分支修复完紧急 bug 后，统一合并代码至该分支。测试结束后，必须将修改内容合并回  master  分支，并关闭该 hotfixes 分支。

4.2 Commit  日志规范

一个commit只做一件事情；若一个commit做了多件事情需要拆分成多个commit。
提交信息一定要认真填写，建议参考规范：`<type>(scope)：<subject>`

比如：Fix(构件查找)：构件选中结果显示不正确#11072

type——表示动作类型，首字母大写，可分为：

• Fix：修复  xxx Bug
• Feat：新增  xxx  功能
• Test：调试  xxx  功能，包括单元测试、集成测试等
• Style：变更  xxx  代码格式或注释
• Docs：变更  xxx  文档，比如 README, CHANGELOG, CONTRIBUTE 等等
• Refactor：重构  xxx  功能或方法
• Perf: 优化相关，比如提升性能、体验
• Revert: 回滚到上一个版本
• Update:更新，更新 Geo 的引擎库或者 UI 库，请加上对应版本的 commit ID。如update(Geo.Viewer): a1ddc802或者update(Geo.ViewerUI): c62a50c8

如果 type 为Feat和 Fix，则该 commit 将肯定出现在 Change log 之中。

scope——表示影响范围，可分为：模块、类库、方法等。
subject——表示简短描述，最好不要超过 60 个字，如果有相关 Bug 的 Jira 号，建议在描述中加上。

5.注意事项

(1) 提交代码前，记得及时更新 CHANGES.md 和 Changes_Cesium.md 文件,变更记录需包含相关类或者接口名称，以及作者名称和日期；
(2) Ceisum 中的 ScreenSpaceEventType 类型统一通过 BOSGeo.MapEventType 对外提供。 (3) src\tests 目录中存储的为不同功能的自测用例，请根据代码结构分类。src\tests\indexDir.js 为自测用例的目录索引，若自测用例包含单独的 css 和 html 元素，则切换用例时需要重启 node server。

6. 参考文献

1 Git 分支设计规范新亮笔记-CSDN 博客 https://blog.csdn.net/XinLiangTalk/article/details/104403973
2 GitLab 与 GitFlow 的简单使用哔哩哔哩 (゜-゜)つロ 干杯~-bilibili https://www.bilibili.com/video/BV1Wb411e7ec
3 盈嘉互联-代码管理规范
4 盈嘉互联 Web 前端开发代码规范