h3factory 0.0.0-stage → 0.2.2

package/skills/h3yun-dev-assistant/FRONTEND_GUIDELINES.md

@@ -0,0 +1,47 @@
+# 前端 ES5 规则
+
+## 硬性规则
+
+- `if`、`else if`、`else`、`for`、`for in`、`while`、`do while` 等控制流语句必须使用大括号，即使代码块中只有一条语句也不得省略；大括号采用 K&R 风格，与控制流语句同行。只调整既有代码格式时不得改变业务逻辑。
+- 使用 `var` 和 `function`；禁止 `let`、`const`、箭头函数、`class`、`Promise`、`async/await`、解构、模板字符串和可选链。
+- 不直接操作 DOM；控件仅使用氚云 API，例如 `GetValue()`、`SetValue()`、`SetVisible()`、`SetReadonly()`。
+- `$.extend($.JForm, {...})` 只定义平台支持的事件入口。单一事件的辅助逻辑放在事件内部；跨事件复用时定义到带表单编码前缀的 `window` 方法。
+- 如需使用匿名函数隔离单一事件的局部变量，匿名函数必须写在具体事件内部，并传入该事件的 `this`；不得用匿名函数包裹整个 `$.extend($.JForm, {...})`。推荐写法：
+
+```javascript
+$.extend($.JForm, {
+    OnLoad: function () {
+        (function (that) {
+            // 当前事件的辅助逻辑、局部变量和事件绑定。
+        }(this));
+    },
+
+    OnValidate: function (actionControl) {
+        return true;
+    }
+});
+```
+- 不循环调用服务端接口；子表新增优先批量操作。
+
+## 表单按钮
+
+- 点击顺序：`OnValidate` -> `BeforeSubmit` -> 后端 `OnSubmit` -> `AfterSubmit`。
+- 流程表单的 `Submit` 同时表示发起和同意。仅发起时执行的校验，必须结合 `ResponseContext` 判断新增、草稿或发起节点，不能只判断 `Submit`。
+- 未说明发起节点被调整时，默认发起节点编码为 `Activity2`，可按以下结构判断：
+
+```javascript
+if (actionControl.Action == "Submit" && (
+    $.SmartForm.ResponseContext.IsCreateMode ||
+    $.SmartForm.ResponseContext.BizObjectStatus == 0 ||
+    $.SmartForm.ResponseContext.ActivityCode == "Activity2"
+)) {
+    // 仅在流程发起时执行的校验。
+}
+```
+
+- 自定义 Post 按钮在 `OnValidate` 中完成必要校验后返回 `false`，阻止平台默认提交。
+
+## 列表按钮
+
+- 列表按钮前置校验使用 `$.ListView.ActionPreDo`。
+- 批量操作先校验选中行与数量上限，再传递选中 `ObjectId` 的 JSON 字符串。

package/skills/h3yun-dev-assistant/OPENAPI_GUIDELINES.md

@@ -0,0 +1,8 @@
+# OpenAPI 规则
+
+- 仅当外部系统调用氚云时使用 OpenAPI；不要与表单后端 `BizObject` 代码混用。
+- 调用使用 HTTPS、POST、UTF-8、`application/json`，频率控制在每秒 1 至 2 次，超时不超过 60 秒。
+- 必须确认 `EngineCode`、`AppCode`、`SchemaCode` 和控件编码；`EngineSecret` 为敏感信息，禁止写入前端、示例明文或公开仓库。
+- 表单数据通常传 JSON 字符串。查询返回的 `xxxObject` 补充字段不可回传用于创建或更新。
+- 创建、更新、删除会触发自动化和业务规则；批量或长耗时调用由调用方分批，不使用线程或后台任务。
+- 接口请求体或签名不确定时，先从 https://h3yun-pro-doc-openapi.apifox.cn/llms.txt 定位并查阅对应接口文档。

package/skills/h3yun-dev-assistant/PLATFORM_CONSTRAINTS.md

@@ -0,0 +1,160 @@
+# 氚云平台特性与运行限制
+
+本文件记录氚云/H3Yun 二次开发中区别于通用 .NET、JavaScript 和数据库开发的平台特性、运行限制及对应设计建议。处理相关场景时，不能直接套用通用技术方案。
+
+## 使用原则
+
+- 本文件中的“明确限制”应作为方案设计的硬性边界。
+- 标记为“经验建议”的内容不是固定平台上限，应结合数据量、业务规则复杂度和实际压测结果调整。
+- 当本文件与氚云最新平台帮助文档、当前租户实测结果或用户提供的信息冲突时，以最新且可验证的信息为准，并同步修正本文件。
+- 不确定某项限制是否仍适用于当前版本时，应明确说明不确定性，不要把经验值描述成平台硬限制。
+
+## 后端运行环境
+
+### 平台限制的统一解释
+
+- 氚云限制用户代码自行使用线程、普通 .NET Timer、进程内异步任务和本地文件 I/O，主要是为了保障平台整体稳定性和资源可控性。
+- 这些能力如果使用不当，可能造成线程、CPU、内存、文件句柄、磁盘空间或 I/O 等系统资源持续占用或使用过高，进而影响当前应用及平台上的其他业务。
+- 因此，这些限制应解释为云端平台的资源隔离和稳定性保护机制，而不是简单描述成“氚云缺少该功能”。
+- 向客户说明原因时，应保持在平台稳定性、资源保护和防止用户代码失控这一层面，不要臆测或披露未经确认的底层架构细节。
+
+推荐答复口径：
+
+> 氚云二开环境禁用了用户代码自行创建线程、使用普通 .NET Timer、运行进程内异步任务以及访问本地文件系统。这主要是为了保障云端平台的稳定性和资源可控性，避免用户代码因使用不当造成线程、CPU、内存、磁盘或 I/O 等资源占用过高。需要周期执行时应使用氚云提供的定时器类；需要处理大批量数据时应由调用方分批请求；文件和附件应使用平台提供的相关能力。
+
+### 禁用线程和进程内异步任务
+
+明确限制：
+
+- 氚云后端二开环境禁用或不支持自行创建线程。
+- 不要使用 `Thread`、线程池、`Task.Run`、`Task.Factory.StartNew`、并行循环等方式把任务放到后台执行。
+- 不要依赖请求结束后仍在当前氚云进程中继续执行的“后台任务”。
+- `async/await` 不能突破平台请求生命周期和超时限制，也不能替代可靠的后台任务机制。
+
+方案要求：
+
+- 大批量任务优先由调用方分页或分批请求氚云接口。
+- 每批返回明确的成功、失败和进度信息，由调用方决定是否继续下一批。
+- 需要失败重试时，通过业务唯一键、批次号或幂等标识防止重复创建、重复更新和重复触发业务规则。
+- 不要建议客户在氚云后端用线程、`Task` 或内存队列实现异步处理。
+- 用户询问 `Task`、延时执行、计划任务或周期任务时，应先判断其真实意图：需要脱离当前请求处理大批量数据时，推荐调用方分批；需要平台后续或周期性执行时，优先推荐氚云提供的 `H3.SmartForm.Timer` 定时器类。
+- 不要因为用户使用了“Task”一词，就直接生成 `System.Threading.Tasks.Task` 代码。
+
+### 禁用本地文件 I/O
+
+明确限制：
+
+- 氚云后端二开环境禁用本地文件 I/O，不要使用 `System.IO` 及相关文件、目录和流操作访问服务器文件系统。
+- 不要使用 `File`、`Directory`、`FileInfo`、`DirectoryInfo`、`FileStream`、`StreamReader`、`StreamWriter` 等类型读写本地文件。
+- 不要依赖服务器本地路径、共享目录、临时目录或当前工作目录，也不要假设请求之间可以通过落盘文件保存状态。
+- 不要建议通过本地日志文件、临时文件、文件缓存或生成后落盘的方式中转数据。
+
+方案要求：
+
+- 结构化业务数据应保存到氚云表单或通过平台支持的数据能力处理。
+- 附件和图片应使用氚云提供的附件控件、附件上传下载接口或其他平台支持能力，不等同于开放本地文件系统访问。
+- 需要生成或转换文件时，应优先由外部服务完成，再通过氚云支持的接口传输或保存结果。
+- 需要跨请求保存处理进度时，应使用业务表单中的状态、游标或批次记录，不要使用本地文件。
+
+### 运行时兼容性
+
+明确限制：
+
+- 后端按 .NET Framework 4.6.2 / C# 兼容环境设计。
+- 不使用 .NET Core、.NET 5+ 或依赖较新运行时的库和语法。
+- 平台代码的可用类型、程序集和 API 受沙箱环境约束，不能假设普通 .NET 项目中的库均可使用。
+
+## 自定义接口与 OpenAPI
+
+### 请求时长和调用频率
+
+平台要求或既有约定：
+
+- 单次请求超时时间应控制在 60 秒以内。
+- 调用频率建议控制在每秒 1 至 2 次，不要高并发循环调用。
+
+方案要求：
+
+- 预计处理时间可能接近 60 秒时，必须建议调用方分批处理，而不是建议氚云后端创建异步任务。
+- 单批处理时间应预留网络抖动、业务规则、自动化和数据库负载的余量，不要以刚好 60 秒作为目标。
+- 批量大小没有统一固定值，应根据单条处理成本压测确定。可从每批 50 至 100 条开始验证，但必须明确这是经验起点，不是平台固定上限。
+- 优先使用平台批量接口或 `BulkCommit`，避免逐条请求和循环调用 Engine 接口。
+
+### 推荐的分批协议
+
+调用方请求建议包含：
+
+- `batchId`：批次唯一标识，用于幂等和问题追踪。
+- `pageIndex` 或 `cursor`：当前分页位置。
+- `items`：当前批次数据。
+
+接口响应建议包含：
+
+- 当前批次成功数量和失败数量。
+- 每条失败数据的业务标识及错误原因。
+- 下一页游标或是否处理完成。
+- 可供重试使用的批次标识。
+
+## 定时器限制
+
+明确限制：
+
+- 氚云后端的计划任务应使用平台提供的定时器类：定义继承 `H3.SmartForm.Timer` 的类，并重写 `OnWork(H3.IEngine engine)`。
+- 氚云定时器由平台调度，底层约每 4 小时检测执行一次，不支持自定义成秒级或分钟级固定间隔。
+- 每个应用定时器总执行时间约 20 分钟，应避免一次处理无界数据。
+- 定时器中没有 `this.Request`，应使用 `OnWork(H3.IEngine engine)` 提供的 `engine`。
+
+方案要求：
+
+- 用户询问“定时任务怎么写”“能否用 `Task` 定时执行”“如何延时或周期执行”时，应先介绍氚云 `H3.SmartForm.Timer`，不要推荐线程、`System.Threading.Timer`、`System.Timers.Timer`、`Task.Delay` 或第三方进程内调度器。
+- 不要把定时器描述为精确调度器。
+- 需要高频、准点或秒级调度时，应由外部调度系统调用氚云接口，并遵守接口频率和超时限制。
+- 定时器处理大量数据时应按可恢复的游标或状态分段处理，避免每次从头扫描全部数据。
+
+## 前端运行环境
+
+明确限制：
+
+- 氚云表单和列表前端按 ES5 编写。
+- 不使用 `Promise`、`async/await`、箭头函数、`class`、可选链等现代语法。
+- 不通过直接操作 DOM 绕过氚云控件 API。
+
+方案要求：
+
+- 前端不要循环逐条调用后端接口，应一次提交合理大小的批量数据。
+- 前端的异步请求只代表浏览器请求回调，不代表氚云后端可脱离请求生命周期继续运行。
+
+## 数据与事务特性
+
+### 业务规则和自动化副作用
+
+- 创建、更新、删除生效数据可能触发自动化和业务规则，批量方案必须把这些额外耗时计算在内。
+- 更新生效数据可能先触发作废规则，再触发生效规则。
+- 重试接口前必须考虑幂等，否则可能重复触发消息、流程、自动化或外部接口。
+
+### 乐观锁
+
+- 同一业务对象被重复加载、更新或在流程事件中交叉修改时，可能出现 `UpdateFailed`、`ItemExists`、`Optimistic lock failed`。
+- 多次更新前应重新加载对象，并合理安排 `base.OnSubmit` 与当前数据修改的先后顺序。
+- 不要用多线程并行更新同一业务对象来提升速度，这既不符合平台限制，也会放大乐观锁冲突。
+
+## 回答场景检查
+
+遇到以下关键词或意图时，应优先应用本文件：
+
+- 异步、后台执行、线程、并发、并行、`Task`、`Thread`、`Task.Delay`、计划任务、延时执行、周期执行、队列。
+- 文件、目录、本地路径、临时文件、文件流、读写文件、`System.IO`、`File`、`Directory`、`Stream`。
+- 自定义接口、OpenAPI、接口超时、请求频率、批量同步、导入大量数据。
+- 定时任务、定时器、轮询、每分钟执行、秒级执行。
+- 大数据量、性能优化、批量创建、批量更新、批量删除。
+- 乐观锁、重复执行、失败重试、幂等、业务规则重复触发。
+
+回答前至少确认：
+
+- 是否在说明禁用能力的同时，向客户解释了平台稳定性、资源隔离和防止资源使用过高的原因。
+- 是否错误地套用了普通 .NET 的线程或后台任务方案。
+- 如果用户实际需要计划或周期执行，是否已优先推荐 `H3.SmartForm.Timer` 定时器类，并说明其调度精度限制。
+- 是否错误地使用了 `System.IO`、本地路径、临时文件或落盘缓存方案。
+- 是否需要改为调用方分批、平台批量接口或外部调度。
+- 是否考虑 60 秒请求时长、每秒 1 至 2 次调用频率及业务规则耗时。
+- 是否需要幂等、断点续传、失败明细和重试机制。

package/skills/h3yun-dev-assistant/POST_GUIDELINES.md

@@ -0,0 +1,47 @@
+# 表单与列表 Post 规则
+
+以下规则同时适用于表单 `$.SmartForm.PostForm` 和列表 `$.ListView.Post`，是不可违反的代码生成要求。
+
+## 命名与委派
+
+- 请求名称必须为 `功能名_Post`。
+- 表单：前端 `PostForm` 的第一个参数、后端处理方法名、方法内 `actionName` 判断值必须完全相同。
+- 列表：自定义按钮编码为 `功能名`，请求名称、后端处理方法名、方法内判断值必须为对应的 `功能名_Post`。
+- `OnSubmit` 只调用对应的 `功能名_Post(actionName, this.Request, response)` 和 `base.OnSubmit(actionName, postValue, response)`；不得在 `OnSubmit` 直接读取参数、处理业务或组装响应。
+- 每个 `功能名_Post` 方法开头必须判断不匹配的 `actionName` 并直接返回；方法内负责参数校验、业务处理、成功响应和异常捕获。
+
+## ReturnData
+
+- `response.ReturnData` 的类型固定为 `Dictionary<string, object>`。
+- 成功响应必须先写：`response.ReturnData = new Dictionary<string, object>();`。
+- 每一项响应数据必须用 `response.ReturnData.Add("键名", 值)` 添加。
+- 禁止直接给 `response.ReturnData` 赋 `List`、数组、字符串或其他对象，否则会编译失败。
+- 返回集合时，集合必须是字典中的一个值，例如 `response.ReturnData.Add("items", itemList);`。
+
+```csharp
+protected override void OnSubmit(string actionName, H3.SmartForm.SmartFormPostValue postValue, H3.SmartForm.SubmitSmartFormResponse response)
+{
+    QueryOrder_Post(actionName, this.Request, response);
+    base.OnSubmit(actionName, postValue, response);
+}
+
+// 处理查询订单的前端 Post 请求。
+public void QueryOrder_Post(string actionName, H3.SmartForm.SmartFormRequest request, H3.SmartForm.SubmitSmartFormResponse response)
+{
+    if(!"QueryOrder_Post".Equals(actionName))
+    {
+        return;
+    }
+
+    try
+    {
+        List<string> orderNos = new List<string>();
+        response.ReturnData = new Dictionary<string, object>();
+        response.ReturnData.Add("orderNos", orderNos);
+    }
+    catch(Exception ex)
+    {
+        response.Errors.Add(ex.Message);
+    }
+}
+```