From 9c1361382cb8debac8c3afd43e5088e2e72246ce Mon Sep 17 00:00:00 2001
From: dayjoy <xuchaoying@byteawake.com>
Date: Mon, 18 Aug 2025 16:31:35 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0TOCO=E5=B9=B3?=
 =?UTF-8?q?=E5=8F=B0=E7=AE=80=E4=BB=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .gitignore         |   1 +
 knowledge-brief.md | 140 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 141 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 knowledge-brief.md

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..757fee3
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+/.idea
\ No newline at end of file
diff --git a/knowledge-brief.md b/knowledge-brief.md
new file mode 100644
index 0000000..52e3a51
--- /dev/null
+++ b/knowledge-brief.md
@@ -0,0 +1,140 @@
+# TOCO平台简介
+
+## 平台概述
+
+TOCO是一款专业的软件研发平台，专注于软件设计和核心代码的自动生成。基于DDD（领域驱动设计）、分层设计、CQRS等经典软件工程理论，提供从数据库到API的全栈开发能力，显著提升开发设计和编程效率。
+
+核心价值在于从软件工程理论出发，提供可视化的软件设计能力，设计结果可直接转换为标准格式的代码，提升编码一致性和效率。主要特性包括可视化设计、模型关联、多人协作、代码生成器等。
+
+## 核心设计元素
+
+### 1. 模块（Module）
+模块是系统领域的具体细分，映射为Java工程中的module，代表系统的叶子子域。
+- **命名规则**：小写英文字母+下划线（如meeting、user_detail），禁止添加固定后缀
+- **代码产物**：生成独立的Java Module，采用entrance、service、manager、persist、common分层结构
+
+### 2. 枚举（Enum）
+表达常量值集合，可被其他模块使用，可作为字段类型。
+- **命名规则**：以_enum结尾
+- **枚举值**：全大写字母+下划线
+- **代码产物**：在common模块生成Java类，类名以Enum结尾，位于common.enums包路径
+
+### 3. 值对象（EO）
+POJO对象结构，可被其他模块使用，可作为实体字段类型。
+- **命名规则**：以_eo结尾
+- **字段限制**：只能为基本类型（含List）、EO、Enum
+- **代码产物**：在persist层生成，类名以Eo结尾，位于persist.eo包路径
+
+### 4. 实体关系（ER/Entity）
+实体及其关系，一个实体对应一个数据库表，关系为实体间的外键依赖关系。包含名称、字段、字段类型、主键、索引等属性。是聚合的基础，也是DTO和VO的派生基础。
+
+### 5. 聚合对象（BO/业务对象）
+对一组密切关联实体的封装，从聚合根开始，通过实体关系按层级组装其他实体。
+- **特点**：提供内存一致性视图和数据操作入口
+- **限制**：只能在单一模块中组合，一个实体只能属于一个聚合对象
+- **代码产物**：生成BO和BaseBO，BaseBO封装实体属性和关系
+
+### 6. 数据传输对象（DTO）
+表达以某个Entity为基础，通过外键关系关联多个Entity的数据结构。
+- **分类**：BaseDTO（派生自Entity）和普通DTO（派生自BaseDTO）
+- **字段扩展**：支持正向替换和反向注入
+- **预定义方法**：根据根Entity的唯一索引自动生成RPC方法
+- **跨模块使用**：公开DTO的预定义RPC可被其他模块订阅调用
+
+**获取方式判断原则**：
+- 主键或唯一索引查询 → 使用预定义方法
+- 其他复杂查询条件 → 使用读方案
+
+### 7. 视图对象（VO）
+基于BaseDTO派生，用于视图层与前端的数据传输。
+- **用途**：作为HTTP API返回值，不能作为RPC返回值
+- **继承规则**：DTO字段为基础类型时保持一致，DTO字段时需转换为对应的VO
+- **转换方法**：自动生成基础convert方法和带数据拼装的convert方法
+- **根VO vs 子VO**：根VO有uuid标识可被引用，子VO附属于根VO无uuid
+
+**获取方式判断原则**：
+- 主键或唯一索引查询 → 预定义方法获取DTO后转换
+- 其他复杂查询 → 通过读方案获取DTO后转换，或直接获取VO
+
+### 8. 查询对象（WO）
+表达以某个Entity为基础，通过外键关系关联多个Entity的查询结构。作为ReadPlan的查询上下文使用，支持数据过滤功能。
+
+### 9. 读方案（ReadPlan）
+描述如何基于查询对象从数据库获取DTO和VO列表数据。
+- **核心能力**：
+    - 根据查询条件返回符合条件的DTO或VO的id列表
+    - 根据字段过滤条件对列表字段数据进行过滤
+- **排序支持**：默认排序和自定义排序两种方式
+- **代码产物**：自动生成RPC方法（返回DTO）或Java方法（返回VO）
+
+### 10. 查询传输对象（QTO）
+读方案的查询参数结构，每个读方案对应一个QTO。调用方按QTO结构传入查询参数。
+
+### 11. 写方案（WritePlan）
+所有数据库写操作都通过写方案实现，每个写方案只能操作一个聚合内部的表。
+- **操作类型**：CREATE、UPDATE、DELETE、CREATE_ON_DUPLICATE_UPDATE、FULL_MERGE、PARTIAL_MERGE
+- **代码产物**：生成对应的RPC方法，参数为BTO，返回聚合根主键
+
+### 12. 业务变更传输对象（BTO）
+写方案自动生成的参数结构，按照写方案选定的操作实体根据关系形成树形集合。
+
+### 13. 服务层方法（RPC）
+按可见性分为公开RPC（可被其他模块订阅）和非公开RPC（仅当前模块使用）。
+- **参数类型限制**：只能为QTO、BTO、Enum、基本类型
+- **返回值类型限制**：只能为DTO、Enum、基本类型
+- **创建方式**：DTO创建自动生成、读方案自动生成、写方案自动生成、自定义RPC
+
+### 14. 应用程序接口（API）
+定义对外暴露的HTTP接口。
+- **参数类型限制**：只能为QTO、BTO、Enum、基本类型
+- **返回值类型限制**：只能为VO、Enum、基本类型
+- **返回包装**：框架自动包装返回值（code、message、data）
+
+### 15. 流程服务（FunctionFlow）
+针对复杂业务的流程拆解，把业务过程分解成流程节点。
+- **使用场景**：API/RPC涉及写服务超过3个时推荐使用
+- **节点类型**：顺序节点、条件节点、选择节点、开始节点
+- **代码产物**：生成FlowConfig、Service、FlowNode、FlowContext
+
+## 最佳实践原则
+
+### 1. 设计分析结果应用
+- **细节设计分析**：针对简单需求直接分析读写方案、接口等
+- **流程拆解设计分析**：针对复杂需求拆解为多个短流程，必须调用createFunctionFlow
+
+### 2. 写方案创建原则
+分析出所有写数据场景，按聚合维度分组，每个写场景都需要创建对应的写方案。
+
+### 3. 接口参数类型选择
+- **读场景**：参数优先使用QTO
+- **写场景**：参数优先使用BTO
+- **严格限制**：DTO、VO不能作为参数；QTO、BTO不能作为返回值
+
+### 4. 数据获取方式判断
+严格按查询条件判断，不能根据返回值是否需要数据拼装判断：
+- 主键或唯一索引 → 预定义方法
+- 其他复杂条件 → 读方案
+
+## 代码编写指南
+
+### 基本原则
+- **准确性优先**：不产生编译错误，不调用不存在的函数/字段
+- **单一职责**：Controller做参数校验，Service做业务逻辑
+- **复用性考虑**：复杂逻辑拆分为多个函数，单函数不超过30行
+- **循环优化**：避免在循环中执行数据库操作
+
+### 特殊规则
+- **异常处理**：统一使用IgnoredException(code, "message")
+- **BO校验**：业务不变性规则写在BO的聚合校验函数中
+- **系统代码**：不要修改/** This block is generated by vs **/标注的代码
+- **代码结构**：使用{}和注释分块提升可读性
+
+### 注解说明
+- **@AutoGenerated**：标识自动生成的类和方法
+    - locked=true：不建议修改
+    - uuid：唯一标识，包含|字符表示特殊格式
+
+## 技术栈
+- **语言/框架**：Java、SpringBoot
+- **数据访问**：MyBatis-plus（读）、Hibernate（写）
+- **分层结构**：entrance、service、manager、persist、common