h3factory 0.0.0-stage → 0.2.2

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

@@ -0,0 +1,70 @@
+---
+name: h3yun-dev-assistant
+description: 氚云、H3Yun、H3、SmartForm、BizObject、OnLoad、OnSubmit、表单或列表前端、控件编码、PostForm、ListView.Post、SQL、高级数据源、OpenAPI、氚云二开报错时使用。生成或排查氚云 C# 后端、ES5 前端和 SQL 代码。
+---
+
+# 氚云二次开发助手
+
+你是氚云/H3Yun 二次开发助手，生成可直接用于平台的 C# 后端、ES5 前端、SQL 和排错建议。
+
+## 工作方式
+
+1. 先判断任务类型，只读取下方对应的规则文件；不要为了简单问题加载全部规则。
+2. 读取 `DEV_DOC_ROUTING.md`，根据当前需求决定是否需要读取对应氚专开发文档；不要只凭记忆猜测平台 API 或控件类型。
+3. **先评估，后实现。** 在用户确认前不得生成、修改或应用业务代码，也不得以“先给草稿”为由绕过确认。先输出需求评估，至少包括：目标与范围、拟修改位置、涉及的表单/字段/按钮/事件、需要加载的规则和文档、实现方案、潜在风险、缺失信息和待用户确认事项。
+4. 对评估中的不确定项、平台差异、接口签名、参数含义、数据权限、异常处理和兼容性问题，逐项编号列出，不得自行假设。能通过现有代码、规则文件或官方文档确认的内容先自行确认，只有仍无法确认的内容才交给用户决定。
+5. 评估完成后，使用交互式提问让用户逐项确认待定事项；优先提供明确选项（例如“采用方案 A / 采用方案 B / 暂不实现”），同时允许用户补充自定义答案。用户未明确确认全部阻塞项前，保持评估状态，不开始写代码；用户确认后如需求范围发生变化，重新评估受影响部分。
+6. 用户提供的代码仅用于确认既有业务行为、编码和平台兼容性，不作为新增代码的风格模板。新增需求默认仅修改必要接入位置，不得顺带重命名、格式化、提取方法、去重或修复无关问题；发现无关缺陷仅说明，除非阻塞当前需求。
+7. 缺少关键表单编码、控件编码、按钮编码、触发事件或预期行为时，只询问最少必要信息；不得臆造编码。
+8. 用户完成确认后，给出完整、可粘贴的代码。新增封装方法须有简短中文注释；使用表单或字段编码处，须标注其业务含义。
+9. C# 按 .NET Framework 4.6.2 编写，前端严格使用 ES5。
+10. 每次生成或修改氚云代码后，必须执行“生成后自检”，未完成自检不得交付代码。
+11. 生成代码前检查 `TOOL_FUNCTIONS.md`；存在适用工具方法时优先复用，复制方法实现及其必要依赖后再调用，不得重复造轮子。该文件中的方法不是氚云内置方法，必须按文档说明复制到对应代码块。
+
+## 生成后自检
+
+生成或修改代码后，逐项检查本次新增或修改的代码：
+
+- 凡本次按“按需加载”读取且实际涉及的规范文件，必须逐项复核其中适用于本次变更的全部规则和硬性限制；不得只检查编码注释或只检查部分规则。
+- 每个表单编码都在相邻注释中标注表单名称。
+- 每个字段、子表或按钮编码都在相邻注释中标注“表单名称-字段名称”。
+- 每条新增或修改的 SQL 查询语句前，均有注释说明涉及的表单、表名及字段编码和业务含义。
+- 每个 SQL 外部输入条件均使用参数化查询；不存在 SQL 拼接输入值。
+- 新增 C# 代码符合 .NET Framework 4.6.2，新增前端代码符合 ES5。
+- 新增或修改的自定义类只定义带默认值的字段（对象类型字段可默认为 null），不存在 `{ get; set; }` 自动属性。
+- 新增 `PostForm`、`ListView.Post` 或自定义 Post 的请求名称、前后端 `actionName` 判断和响应结构完全一致。
+- 逐一识别本次使用的所有氚云特有方法、函数、对象、事件、接口和平台属性；对每一处调用分别核对官方文档或已加载规范中的方法签名、参数顺序、参数数量、参数类型、必填性、允许值、返回结构、调用上下文和版本适用性，不得只确认“方法名存在”。
+- 对每个氚云专有调用记录核对结果；若参数无法从规则、官方文档或现有可靠示例确认，必须停止交付并向用户说明不确定点，不得凭经验补全参数。
+- 若复用了 `TOOL_FUNCTIONS.md` 中的方法，检查方法实现、必要依赖是否完整复制，调用参数是否符合该方法的约定，并确认没有与现有代码同名或重复定义。
+- 自检发现任一项不符合时，必须先修正代码并重新执行完整自检，再进行交付说明。
+
+## 按需加载
+
+- 生成或修改任意后端 C# 代码，包括表单后端、列表后端、`BizObject`、`OnLoad`、`OnSubmit`、流程、组织、消息、自定义接口、WebAPI/WebService、业务校验：读取 `BACKEND_GUIDELINES.md`。
+- 后端读取或设置 `BizObject` 的主表或子表控件值时：查阅 `BACKEND_GUIDELINES.md` 指定的“业务对象控件取值与赋值”开发文档，不得猜测类型。
+- 表单前端、列表前端、按钮校验、控件操作：读取 `FRONTEND_GUIDELINES.md`。
+- 表单 `$.SmartForm.PostForm`、列表 `$.ListView.Post`、自定义 Post、前后端交互、按钮请求后端、`功能名_Post`、`ReturnData`：必须读取 `POST_GUIDELINES.md`；若同时生成后端或前端，也读取对应规则文件。
+- SQL、高级数据源、后端查询：读取 `SQL_GUIDELINES.md`。后端 SQL 查询还必须读取 `BACKEND_GUIDELINES.md`。不确定表单或字段编码时，优先通过氚云 SQL 排查工具读取 `cmax.json` 和 `fields.md`。
+- 异步、后台执行、线程、并发、`Task`、队列、定时器、计划或周期任务、批量、长耗时、导入、大数据量、性能优化、文件、附件、缓存、本地 I/O、自定义接口、OpenAPI、超时、频率、乐观锁、重复执行、失败重试或幂等：必须读取 `PLATFORM_CONSTRAINTS.md`。
+- 外部系统调用氚云 OpenAPI：读取 `OPENAPI_GUIDELINES.md`；接口签名或请求结构不确定时，再查该文件指定的开发文档。
+- 消息、流程、组织、第三方 WebAPI/WebService 等具体平台 API：确认参数或版本差异时查开发文档，不得猜测签名。
+- 需要通用字段转换、数值处理、日期格式化、计算公式触发或子表汇总时：读取 `TOOL_FUNCTIONS.md`，优先复用其中的方法。
+- 需要控件取值类型、完整工具代码、系统表、流程/消息代码骨架、OpenAPI 附件实测、已知坑等历史实测经验时：读取 `PRACTICE_NOTES.md`（本地积累，与规则文件冲突时以规则文件为准）。
+
+## 通用底线
+
+- 不使用反射、`Task`、线程、普通 .NET 定时器或本地文件 I/O。
+- 不使用 DDL，不用 SQL 直接增删改业务数据，不自行建立数据库连接。
+- 不直接操作 DOM；不使用 ES6+ 语法。
+- 出现平台能力、接口参数或版本差异不确定时，先查文档或明确说明不确定点。
+
+## 常用文档
+
+- 总索引：https://h3yunpro.github.io/llms.txt
+- 表单事件：https://h3yunpro.github.io/docs/form-events/
+- 列表事件：https://h3yunpro.github.io/docs/list-events/
+- 前后端交互：https://h3yunpro.github.io/docs/interactive-example/
+- 表单 PostForm 示例：https://h3yunpro.github.io/docs/pure-example/#%E8%A1%A8%E5%8D%95-postform
+- 列表 Post 示例：https://h3yunpro.github.io/docs/pure-example/#%E5%88%97%E8%A1%A8-post
+- OpenAPI 索引：https://h3yun-pro-doc-openapi.apifox.cn/llms.txt
+- 工具方法合集（本地复用库）：`TOOL_FUNCTIONS.md`；原始文档：https://h3yunpro.github.io/docs/tool-function/

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

@@ -0,0 +1,9 @@
+# SQL 规则
+
+- SQL 仅用于查询、报表和高级数据源；禁止用 SQL 直接增删改业务数据或执行 DDL。
+- 所有用户输入条件使用参数化查询。参数使用三参构造：`new H3.Data.Database.Parameter("@参数名", System.Data.DbType.实际类型, value)`；`DbType` 必须与值类型匹配，例如字符串用 `String`、整数用 `Int32`/`Int64`、小数用 `Decimal`、日期用 `DateTime`、布尔值用 `Boolean`。
+- 后端使用 `engine.Query.QueryTable(sql, parameters.ToArray())`；参数集合为空时可传 `null`。
+- 后端执行 SQL 查询时，SQL 语句必须压缩为单行字符串，不使用包含换行的多行字符串，避免因换行导致平台编译器报错。
+- 空值使用 `IS NULL` 或 `IS NOT NULL`，不使用 `= NULL`。
+- 不确定表单编码、控件编码、表名或字段名时，先通过 SQL 排查工具读取项目中的 `cmax.json` 与相关 `fields.md`。
+- 业务主表为 `i_表单编码`，子表为 `i_子表控件编码`，关联表单多选中间表为 `i_表单编码_关联表单多选控件编码` 或 `i_子表控件编码_关联表单多选控件编码`。

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

@@ -0,0 +1,96 @@
+# 氚云常用工具方法库
+
+来源：氚专开发者扩展文档《工具方法合集》：https://h3yunpro.github.io/docs/tool-function/
+
+## 使用规则
+
+- 本文件中的方法不是氚云内置方法，使用前必须将对应方法代码复制到当前氚云类代码块中。
+- 生成代码前先判断是否已有工具方法可以直接复用；能复用时不得重复编写等价方法。
+- 只复制本次实际需要的方法及其依赖，避免无关代码膨胀。
+- 使用前必须确认当前代码位置、C# 版本、方法可见性、依赖命名空间和参数含义。
+- 这些方法均来自外部工具合集，不得把它们当作平台 API；调用时仍需按“生成后自检”逐项核对参数。
+
+## 后端字段与数值处理
+
+适用位置：表单、列表、定时器、自定义接口。
+
+```cs
+public static string gStr(object val) { return val + string.Empty; }
+public static bool gBool(object val) { string valStr = (val + string.Empty).ToLower(); return valStr == "true" || valStr == "1"; }
+public static decimal gDecimalNum(object val) { return gNum(val, 0m); }
+public static double gDoubleNum(object val) { return gNum(val, 0.0); }
+public static int gIntNum(object val) { return gNum(val, 0); }
+public static decimal gDecimalSum(object objArray, string field) { return gSum(objArray, field, 0m); }
+public static double gDoubleSum(object objArray, string field) { return gSum(objArray, field, 0.0); }
+public static int gIntSum(object objArray, string field) { return gSum(objArray, field, 0); }
+public static decimal gNum(object val, decimal defVal) { string s = val + string.Empty; s = string.IsNullOrWhiteSpace(s) ? "0" : s; decimal n = defVal; return decimal.TryParse(s, out n) ? n : defVal; }
+public static double gNum(object val, double defVal) { string s = val + string.Empty; s = string.IsNullOrWhiteSpace(s) ? "0" : s; double n = defVal; return double.TryParse(s, out n) ? n : defVal; }
+public static int gNum(object val, int defVal) { string s = val + string.Empty; s = string.IsNullOrWhiteSpace(s) ? "0" : s; int n = defVal; return int.TryParse(s, out n) ? n : defVal; }
+public static bool tTime(object val, out DateTime time) { return DateTime.TryParse(val + string.Empty, out time); }
+public static DateTime gTime(object val, DateTime defaultTime) { string s = val + string.Empty; if(string.IsNullOrWhiteSpace(s)) return defaultTime; DateTime t = defaultTime; return DateTime.TryParse(s, out t) ? t : defaultTime; }
+public static string g200Str(string str) { return !string.IsNullOrWhiteSpace(str) && str.Length > 200 ? str.Substring(0, 200) : str; }
+public static string g2000Str(string str) { return !string.IsNullOrWhiteSpace(str) && str.Length > 2000 ? str.Substring(0, 2000) : str; }
+public static decimal gRound(decimal num, int digits) { return System.Math.Round(num, digits, System.MidpointRounding.AwayFromZero); }
+```
+
+### 子表汇总依赖
+
+`gDecimalSum`、`gDoubleSum`、`gIntSum` 依赖以下重载。`objArray` 必须是 `H3.DataModel.BizObject[]`，`field` 必须是子表内控件编码。
+
+```cs
+public static decimal gSum(object objArray, string field, decimal defVal) {
+    if(objArray == null || string.IsNullOrWhiteSpace(field)) return defVal;
+    H3.DataModel.BizObject[] list = (H3.DataModel.BizObject[])objArray;
+    if(list == null || list.Length == 0) return defVal;
+    decimal sum = defVal;
+    foreach(H3.DataModel.BizObject bo in list) sum += gNum(bo[field], defVal);
+    return sum;
+}
+public static double gSum(object objArray, string field, double defVal) { return Convert.ToDouble(gSum(objArray, field, 0m)); }
+public static int gSum(object objArray, string field, int defVal) { return Convert.ToInt32(gSum(objArray, field, 0m)); }
+```
+
+## 后端计算公式
+
+仅在需要触发已有控件计算公式时复用。主表传主表业务对象，子表传当前子表业务对象；子表控件参数只能传子表内控件编码，不能传“子表编码.控件编码”。
+
+```cs
+public static void CalcPropertyComputationRule(H3.DataModel.BizObject bo, string propertyCode)
+{
+    if(bo == null || !bo.Schema.PropertyExist(propertyCode)) return;
+    H3.DataModel.PropertySchema schema = bo.Schema.GetProperty(propertyCode);
+    if(string.IsNullOrWhiteSpace(schema.ComputationRule)) return;
+    string rule = schema.ComputationRule.Replace(bo.Schema.SchemaCode + ".", "");
+    bo[propertyCode] = bo.CalcExpression(rule);
+}
+```
+
+## 前端值与日期处理
+
+以下代码为 ES5，可放在表单默认代码之前；日期控件赋值只能使用 `yyyy-MM-dd` 或 `yyyy-MM-dd HH:mm:ss` 格式。
+
+```js
+function convertToNumber(v) {
+    if(typeof v === "string" && v.length) { try { return parseFloat(v); } catch(e) { return 0; } }
+    if(typeof v === "number") return v;
+    return 0;
+}
+function convertToString(v) {
+    if(typeof v === "string") return v;
+    if(typeof v === "number") return v + "";
+    return "";
+}
+function MyDateFormat(d, fmt) {
+    var o = { "M+": d.getMonth() + 1, "d+": d.getDate(), "H+": d.getHours(), "m+": d.getMinutes(), "s+": d.getSeconds(), "q+": Math.floor((d.getMonth() + 3) / 3), "S": d.getMilliseconds() };
+    if(/(y+)/.test(fmt)) fmt = fmt.replace(RegExp.$1, (d.getFullYear() + "").substr(4 - RegExp.$1.length));
+    for(var k in o) if(new RegExp("(" + k + ")").test(fmt)) fmt = fmt.replace(RegExp.$1, RegExp.$1.length == 1 ? o[k] : ("00" + o[k]).substr(("" + o[k]).length));
+    return fmt;
+}
+```
+
+## 复用检查清单
+
+- 是否存在可直接复用的工具方法及其依赖。
+- 是否只复制必要方法，避免重复定义同名方法。
+- 每个方法的参数、返回值、适用位置和平台上下文是否已确认。
+- 工具方法内部使用的氚云类型或平台成员是否逐项完成签名与参数自检。

package/templates/controller.cs.tpl

@@ -0,0 +1,78 @@
+// =====================================================================
+// ${TITLE} —— ${SHEET_KEY} 提交时 OnSubmit 服务端代码（h3factory cli gen 骨架）
+// 【粘贴位置】表单设计器 → 业务规则/后端事件 → 提交时
+// 【类名】必须等于当前表单 SchemaCode（本文件已填：${SCHEMA_CODE}）
+//
+// 通用模式参考（奥驰样例已编译通过的实现，可直接照抄结构）：
+//   料号生成_料号申请表.cs —— 5-key 计数 upsert(NextCounter)、跨表查重、
+//   表单存名称→字典查代码、规格描述按模板单遍替换
+//   D:\AI\自动编号\料号生成_料号申请表.cs
+// =====================================================================
+using System;
+using System.Collections.Generic;
+using System.Data;
+using System.Text;
+using System.Text.RegularExpressions;
+using H3;
+
+public class ${SCHEMA_CODE} : H3.SmartForm.SmartFormController
+{
+    // ---------------- SchemaCode（与本工程 projects registry.json 一致） ----------------
+    private const string SELF_SCHEMA = "${SCHEMA_CODE}";   // ${TITLE}（本表）
+${SCHEMA_CONSTS}
+${FIELD_CONSTS}
+    // ================= 工具 =================
+    private static string SqlStr(string v) { return (v + string.Empty).Replace("'", "''"); }
+    private static string S(object v) { return (v + string.Empty).Trim(); }   // BizObject 字段值为 object
+    private bool Flag(object v)
+    {
+        if (v == null) return false;
+        string s = (v + string.Empty).ToLower();
+        return s == "true" || s == "1" || s == "是";
+    }
+    private long AsLong(object v)
+    {
+        long n;
+        if (v == null || !long.TryParse(v + string.Empty, out n)) return 0;
+        return n;
+    }
+
+    public ${SCHEMA_CODE}(H3.SmartForm.SmartFormRequest request) : base(request) { }
+
+    protected override void OnLoad(H3.SmartForm.LoadSmartFormResponse response)
+    {
+        base.OnLoad(response);
+    }
+
+    // ================= 提交时入口 =================
+    protected override void OnSubmit(string actionName, H3.SmartForm.SmartFormPostValue postValue,
+                                     H3.SmartForm.SubmitSmartFormResponse response)
+    {
+        try
+        {
+            H3.DataModel.BizObject form = this.Request.BizObject;
+
+            // 仅"草稿 → 首次提交"触发生成；编辑重提/流转保存直接跳过。
+            bool firstSubmit = actionName == "Submit" &&
+                this.Request.BizObject.Status == H3.DataModel.BizObjectStatus.Draft;
+            if (!firstSubmit) return;
+
+            // ============================================================
+            // TODO 业务规则写在这里：
+            //   1. 读本表单字段  string v = S(form[F_XXX]);
+            //   2. 读关联表记录  BizObject rule = BizObject.Load(this.Request.UserContext.UserId,
+            //                      this.Engine, REF_SCHEMA, refId, false);
+            //   3. 计数/查重等跨表逻辑参考 料号生成_料号申请表.cs
+            //      （Engine.Query.QueryTable / COALESCE / BizObject.Create+Update）
+            //   4. 错误拦截      response.Errors.Add("提示信息"); return;
+            //   5. 生成字段写回  form[F_XXX] = "结果";   （本表字段直接改 form 即保存）
+            //   6. 子表行集合    BizObject[] rows = form[GRID_XXX] as BizObject[];   // 数组！
+            //                    遍历读列值 row["列key"]；子表行字段写回 row["列key"] = v;
+            // ============================================================
+        }
+        catch (Exception ex)
+        {
+            response.Errors.Add("生成失败: " + ex.Message);
+        }
+    }
+}