附录 A
WSaiOS UML Modeling Specification
WSaiOS UML 建模规范
A.1 建模目标
UML不是为了画图。
而是：
用统一的方法描述WSaiOS工程结构。
每张图必须满足：
- 可以对应代码
- 可以验证实现
- 可以指导开发
- 可以长期维护
如果一张图不能对应工程对象，就不建议放入正式文档。
A.2 UML使用原则
整个WSaiOS统一采用：
| UML类型 | 用途 | 是否必须 |
|---|---|---|
| Use Case | 功能分析 | √ |
| Package | 工程目录 | √ |
| Component | 模块关系 | √ |
| Class | 类设计 | √ |
| Sequence | 调用过程 | √ |
| Activity | 工作流程 | √ |
| State Machine | 生命周期 | √ |
| Deployment | 部署模型 | √ |
| Object | 调试示例 | 可选 |
统一使用九种图。
不再增加。
A.3 图编号规范
建议：
第55章
Figure 55-1
Figure 55-2
Figure 55-3例如：
Figure 55-1
Cognitive Execution Class Diagram这样：
以后引用：
十分方便。
A.4 Package颜色规范
建议：
整个WSaiOS保持一致。
例如：
蓝色
Core
绿色
Service
黄色
Capability
橙色
Workflow
紫色
Plugin
灰色
Application整本书统一。
A.5 Class命名规范
统一：
类：
PascalCase。
例如：
Kernel
Runtime
WorkflowEngine
KnowledgeService
DecisionEngine接口：
建议：
IKnowledge
IWorkflow
IRuntime抽象类：
建议：
AbstractServiceA.6 属性规范
统一：
+
public
#
protected
-
private例如：
Kernel
----------------
-id
-runtime
-status
----------------
+start()
+stop()
+restart()整本书一致。
A.7 Sequence规范
统一：
从左：
到右：
Application
↓
Capability
↓
Workflow
↓
Service
↓
Kernel不要：
交叉。
不要：
回跳。
这样：
容易阅读。
A.8 Activity规范
开始：
统一：
Start结束：
统一：
End条件：
统一：
Decision Node。
例如：
Start
↓
Knowledge
↓
Decision
Yes
↓
Execution
↓
EndA.9 State规范
状态：
统一：
Created
↓
Initialized
↓
Running
↓
Stopping
↓
Stopped不要：
每章：
自己：
创造：
状态。
A.10 Component规范
统一：
矩形。
例如：
Kernel
Runtime
Scheduler
Workflow
Execution箭头：
表示：
依赖。
不是：
调用。
A.11 Deployment规范
统一：
Client
↓
Server
↓
Database不要：
把：
Class：
画到：
Deployment。
A.12 Package规范
目录：
完全：
对应：
Git。
例如：
kernel/
runtime/
workflow/
service/
plugin/Package：
不是：
模块图。
A.13 PlantUML规范
统一：
所有：
源码：
例如：
@startuml
skinparam shadowing false
skinparam classAttributeIconSize 0
@enduml统一：
Style。
以后：
图片：
全部：
一致。
A.14 文件规范
建议：
docs/
uml/
chapter55/
chapter56/
……
chapter90/每章：
单独：
目录。
例如：
chapter55/
class.puml
sequence.puml
state.puml以后：
Git：
管理。
A.15 自动生成
建议：
CI：
自动：
PlantUML
↓
SVG
↓
PNG
↓
PDF避免：
人工：
导图。
A.16 与代码同步
例如：
workflow.py对应：
workflow_class.puml修改：
代码。
修改：
UML。
一起：
提交。
这样：
文档不会长期落后于实现。
A.17 UML与章节对应关系
建议建立统一映射表：
| 章节 | 推荐 UML 图 |
|---|---|
| Kernel | Class、State、Sequence |
| Runtime | Component、Sequence |
| Service | Class、Sequence |
| Capability | Component、Class |
| Workflow | Activity、Sequence、State |
| Scheduler | State、Sequence |
| Knowledge | Class、Sequence |
| Reasoning | Activity、Sequence |
| Decision | Activity、Sequence |
| Execution | Activity、Sequence |
| Plugin | Package、Class |
| API | Sequence |
| SDK | Package、Class |
| Security | Sequence、State |
| Deployment | Deployment |
| Version | Activity、State |
这样每一章的 UML 类型固定，避免重复和遗漏。
A.18 UML文档模板
建议每一章统一采用以下结构：
XX章
理论说明
↓
工程实现
↓
Class Diagram
↓
Sequence Diagram
↓
State / Activity Diagram
↓
PlantUML源码
↓
工程验证(MVP)这样每章既有理论，也有设计，又有实现验证。
A.19 UML工程目录
建议整个仓库结构如下：
WSaiOS/
├── docs/
│ ├── chapters/
│ ├── uml/
│ │ ├── chapter01/
│ │ ├── chapter02/
│ │ ├── ...
│ │ └── chapter90/
│ └── images/
├── src/
├── tests/
└── examples/其中 docs/uml 保存 PlantUML 源码，docs/images 保存导出的 SVG 或 PNG，方便出版和网页展示。
A.20 本附录总结
本附录建立了《WSaiOS》的统一 UML 建模标准，包括：
- UML 图类型规范；
- 类、接口、状态命名规范；
- Package 与目录映射；
- PlantUML 编码规范；
- 图编号规范；
- 文档组织规范；
- UML 与代码同步原则。