Documentation Guideline - Sanjel-Energy-Services/eService_WorkItems GitHub Wiki

Sanjel implements business applications based on one unified domain model. The documentation is critical to help stakeholders to understand the context of problem domain. It also critical for developers to jump in for troubleshooting and making improvement. On another side, the documentation helps all stakeholders to communicate in "Same Language".

The development process following Rathional Unified Process and adopts Agile development practices. The documentation system consists of following sections:

  • Raw Requirement. This is the original documentation from end user, it describes the problems or benifits, and the ideas for demands and improvements.
  • Business Process Diagram. This is in the format of UML Activity Diagram, normally people knows it as Flowchart. Normally we will describe the current process and future process to understand the changes needed to satisfy the requirements.
  • Domain Model Diagram. This is a conceptual model of business entities and relationships. It is in the format of UML Class Diagram.
  • System Collaboration Diagram. This is in the format of UML Sequence Diagram and applies new idea of Everything Collaborate. It describles the interactions among system/entities/people to achieve the value a system will deliver.
  • Test Case. This details the steps and mocked data to verify the new process and system behaviors.

The last four pieces of documentation are the four different perspectives describe the solution to raw requirement.

At Sanjel, we continue to evolve our applications since they were built. This is the beauty of Model Driven Development. The applications are in different age but working as one. Some of them are stepping into retirement and new ones are coming with modern technologies. Currently, following repositories are in use to host all applications.

This is the root of Sanjel business applications documentation. Following documentations can be found here.

  1. Sanjel Application Architecture
  2. Sanjel Development Process
  3. Application Delivery Process
  4. Top Level Sanjel Business Model
  5. Technical Guidelines

This is the domain model solution generate by Metametacube.com(MMC) provided by Metashare Inc. SanjelData model is maintained in MMC and the solution is automatically generated upon the model update. Following components are in the solution.

1. SanjelData.Entities: Domain model definitions. It is published as a Nuget Package in Sanjel Nuget store.
2. SanjelData.Dao: Data access layer. It can be customized as needed for query performance improvement. It is published as two Nuget Packages in Sanjel Nuget store.
3. SanjelData.Service: Service layer to provide a way for application to access SanjelData database. It aggregates the data object automatically based on business entities' relationship. It can be customized as needed for special requirements over standard methods. It is published as two Nuget Packages in Sanjel Nuget store.
4. SanjelData.Web: A default web application to manage the data in SanjelData database with a direct mapping from domain model.
5. SanjelData.WebApi: A default web application to provide RESTful API for third party applications' integration.

In eServiceMDM wiki, following documents can be found here

  1. Top level Sanjel business model and

中文翻译

Sanjel 基于统一的领域模型实现业务应用。文档对于帮助利益相关者理解问题领域的上下文至关重要。同时，它对于开发人员介入故障排查和系统改进也同样重要。另一方面，文档帮助所有利益相关者使用“统一语言”进行沟通。

开发过程遵循 Rational 统一过程（RUP），并采用敏捷开发实践。文档系统由以下几个部分组成：

  • 原始需求：这是来自最终用户的原始文档，描述了问题或期望带来的好处，以及对需求和改进的设想。
  • 业务流程图：以 UML 活动图的形式呈现，通常人们称其为流程图。我们通常会描述当前流程和未来流程，以了解为了满足需求所需的变更。
  • 领域模型图：这是业务实体及其关系的概念模型，采用 UML 类图的形式表达。
  • 系统协作图：采用 UML 时序图的形式，并应用“万物皆可协作”的新理念。它描述了系统/实体/人员之间的交互，以实现系统将要交付的价值。
  • 测试用例：详细列出验证新流程和系统行为所需的步骤和模拟数据。

最后四部分文档分别从不同视角对原始需求的解决方案进行描述。

在Sanjel，我们自应用程序构建以来一直在不断发展。这就是模型驱动开发的美妙之处。这些应用程序虽然处于不同的阶段和位置，但作为一个整体完美协作。它们中的一些正在逐渐退役，代替之的新应用正在使用更新的开发技术来实现。目前，Sanjel完整的应用包含以下这些仓库：

这是Sanjel业务应用文档的最高层文档地址（也就是你现在正在看到的）。它包含以下这些文档内容：

  1. Sanjel应用架构
  2. Sanjel开发流程
  3. 应用交付流程
  4. 顶级Sanjel商业模式
  5. 技术指南

这是Metashare股份有限公司提供的Metametacube.com（MMC）生成的域模型解决方案。SanjelData模型在MMC中维护，解决方案在模型更新时自动生成。解决方案中包含以下组件。

  1. SanjelData.Entities: 域模型定义。它在Sanjel Nuget商店以Nuget包的形式发布。
  2. SanjelData.Dao: 数据访问层。它可以根据需要进行定制，以提高查询性能。它在Sanjel Nuget商店以两个Nuget包的形式发布。
  3. SanjelData.Service: 服务层为应用程序访问SanjelData数据库提供了一种方式。它根据业务实体的关系自动聚合数据对象。它可以根据标准方法的特殊要求进行定制。它在Sanjel Nuget商店以两个Nuget包的形式发布。
  4. SanjelData.Web: 一个默认的Web应用程序，用于通过领域模型的直接映射来管理SanjelData数据库中的数据。
  5. SanjelData.WebApi: 为第三方应用程序的集成提供RESTful API的默认web应用程序。

以下是在eServiceMDM的wiki中的文档地址.