create-yss-spec 1.0.0

package/template/.codex/skills/yss-formily-schema-generator/references/workflow.md

@@ -0,0 +1,240 @@
+# YssFormily Schema Conversion Workflow
+
+This reference is for converting text, images, and Figma designs into YssFormily artifacts.
+
+## 1. Normalize the request
+
+Classify the target form first:
+
+| Form type | Signals |
+| --- | --- |
+| 查询表单 | 筛选、搜索、重置、查询、导出 |
+| 新增表单 | 新建、创建、录入、保存 |
+| 编辑表单 | 编辑、更新、修改 |
+| 详情表单 | 查看、详情、只读、描述列表 |
+| 复合表单 | 同页同时支持新增/编辑/查看 |
+
+Then decide the expected output:
+
+- schema only
+- schema + render snippet
+- schema + data model + scope/effects plan
+
+## 2. Extract a field table
+
+Before writing schema, create a mental table with:
+
+| Item | Meaning |
+| --- | --- |
+| key | stable field name |
+| title | display label |
+| type | business data type |
+| component | YssFormily component |
+| required | whether mandatory |
+| group | section placement |
+| span | layout width |
+| enum source | static or remote |
+| linkage | depends on or affects other fields |
+| custom render | slot/detail slot needed or not |
+
+If a field key is not explicit, generate a stable domain name.
+Avoid UI-only names such as `input1`, `selectA`, `fieldLeft`.
+
+## 3. Component mapping heuristics
+
+Use these defaults:
+
+| Input clue | Preferred YssFormily component |
+| --- | --- |
+| 单行文本 | `Input` |
+| 多行说明 | `Input.TextArea` |
+| 单选下拉 | `Select` |
+| 单选按钮 | `Radio.Group` |
+| 开关 | `Switch` |
+| 日期 | `DatePicker` |
+| 日期区间 | `DatePicker.RangePicker` |
+| 数值 | `InputNumber` |
+| 多选标签 | `Select` with multiple mode |
+| 文件上传 | `Upload` |
+| 可重复行 | `ArrayItems` |
+
+If the UI is clearly custom:
+
+- use `Slot` for edit mode
+- use `detail-*` slot for detail mode
+
+Typical custom cases:
+
+- SQL editor
+- code editor
+- rich text
+- complex helper panel
+- embedded table or tree selector
+
+## 4. Layout mapping heuristics
+
+Convert visual grouping to YssFormily structure:
+
+- page-level layout -> `FormLayout`
+- grid rows and columns -> `FormGrid`
+- section title -> `GroupHeader`
+- footer actions -> `AutoButtonGroup`
+
+Use `gridSpan` when:
+
+- field is visually full width
+- long text area spans across columns
+- custom editor needs horizontal space
+
+Conservative defaults:
+
+- ordinary field: `gridSpan: 1`
+- medium-wide field: `gridSpan: 2`
+- editor-like block: `gridSpan: 3` if page is wide enough
+
+## 5. Validation extraction
+
+Confidence levels:
+
+- high confidence:
+  required star, obvious numeric/date constraints, explicit helper text
+- medium confidence:
+  common business conventions such as name required, code length hint
+- low confidence:
+  hidden uniqueness checks, server-side validation, cross-form constraints
+
+Only encode low-confidence validation if the user explicitly described it.
+
+## 6. Linkage extraction
+
+Map visible interactions into one of these:
+
+| Situation | Mechanism |
+| --- | --- |
+| 简单显隐 | `x-visible` |
+| 简单禁用 | `x-disabled` |
+| 单字段依赖更新 | `x-reactions` |
+| 调接口更新选项 | `scope` handler |
+| 多字段协同或提交兜底 | `effects` |
+
+Examples:
+
+- “选择数据源类型后才显示 JDBC 配置” -> `x-visible`
+- “切换开关后禁用描述字段” -> `x-disabled`
+- “选择省份后重置城市并更新选项” -> `x-reactions`
+- “输入编码后查重” -> `scope` or async validator
+- “提交失败统一 toast” -> `effects`
+
+## 7. Output template
+
+Preferred answer skeleton:
+
+```md
+理解
+
+假设
+
+字段模型
+
+```ts
+// schema
+...
+```
+
+```ts
+// initial model shape
+...
+```
+
+```vue
+<!-- optional render snippet -->
+...
+```
+```
+
+## 8. Schema skeleton
+
+Use this as the default starting point:
+
+```ts
+const schema: ISchema = {
+  type: 'object',
+  properties: {
+    layout: {
+      type: 'void',
+      'x-component': 'FormLayout',
+      'x-component-props': {
+        layout: 'horizontal',
+        labelWidth: 120,
+      },
+      properties: {
+        grid: {
+          type: 'void',
+          'x-component': 'FormGrid',
+          properties: {},
+        },
+      },
+    },
+  },
+};
+```
+
+## 9. Query form special handling
+
+When the form is clearly a search form:
+
+- keep fields compact
+- avoid excessive required rules
+- place actions in `AutoButtonGroup`
+- include `Submit` and `Reset`
+- prefer light linkage over complex `effects`
+
+Typical query output includes:
+
+- schema
+- initial filter model
+- submit/reset handlers through `scope`
+
+## 10. Detail form special handling
+
+If the target is read-only or mixed add/edit/detail:
+
+- plan `mode`
+- check whether detail mode needs custom slots
+- do not generate editable controls only
+- leverage default descriptions rendering when enough
+
+Use custom detail slots only when:
+
+- value needs rich formatting
+- arrays should render tags
+- code or rich text should render in a viewer
+
+## 11. Figma-specific notes
+
+When converting from Figma:
+
+- extract semantic labels, not layer IDs
+- ignore purely decorative layers
+- map helper text and required marks into schema rules
+- convert footer buttons into action area, not ordinary fields
+- infer full-width editors from large framed regions
+
+Do not preserve design-only names such as:
+
+- `Frame 123`
+- `Input / Default`
+- `Group 14`
+
+Translate them into domain names and stable field keys.
+
+## 12. Image-specific notes
+
+When converting from screenshots:
+
+- distinguish placeholder text from actual label text
+- watch for tabs or segmented controls that imply conditional sections
+- identify whether a box is a custom editor or just a textarea
+- keep uncertain parts in assumptions
+
+If confidence is low, generate a clean schema baseline instead of fake precision.

package/template/.codex/skills/yss-frontend-scaffold-generator/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: yss-frontend-scaffold-generator
+description: Use when creating a new YSS frontend micro-application from the standard frontend template. The target template is the template branch of the YSS frontend template Git repository. This v1 skill defines the required inputs, safety checks, template workflow, and Harness registration evidence; it does not include an automated scaffold script yet.
+---
+
+# YSS Frontend Scaffold Generator
+
+用于从标准 YSS 前端模板创建 0-1 前端微应用工程。当前 v1 只定义流程和证据要求；自动生成脚本后续补齐。
+
+## Template Source
+
+```text
+repo: http://192.168.167.142:8081/Data-Middleground-Develop-Area/product-code/ai-frontend/yss-design/yss-frontend-template.git
+branch: template
+```
+
+模板基线：Vue 3、TypeScript、Vite、Qiankun、pnpm、Ant Design Vue、`@yss-ui/components`、`@yss-ui/hooks`、Orval。
+
+## Inputs
+
+- `app_name`：应用名。
+- `microapp_name`：微应用注册名。
+- `base_route`：基础路由。
+- `openapi_source`：OpenAPI 文件、URL 或 Harness spec 路径。
+- `target_git_url` 或 `output_dir`：目标实现仓库或本地输出目录。
+- `package_manager`：默认 pnpm。
+- `init_git`：是否初始化 Git；默认必须用户明确确认。
+
+## Workflow
+
+1. 确认当前任务已经通过 Harness 入口分诊，且实现位置已记录在 proposal、design、build entry review、实施计划或实现路由记录中。
+2. 确认目标是外部实现仓库；只有用户明确选择时才输出到 Harness 仓库的 `apps/frontend/`。
+3. 只读检查模板分支是否可访问：`git ls-remote --heads <repo> template`。
+4. 需要生成工程时，克隆或复制模板到用户确认的目标位置；不得默认写入 Harness 仓库。
+5. 替换应用名、微应用名、路由、`micro-config.json`、环境变量和 README 中的模板占位。
+6. 配置 OpenAPI source，并准备 Orval 生成命令。
+7. 记录验证命令：`pnpm install`、`pnpm lint:check`、`pnpm type-check`、`pnpm build`、`pnpm generate:api`。
+8. 按 `docs/templates/implementation-repo-registry-template.md` 回写前端实现仓库登记。
+
+## Expected Template Shape
+
+```text
+openapi/
+packages/src/api/
+packages/src/router/
+packages/src/views/
+packages/src/styles/
+micro-config.json
+orval.config.ts
+package.json
+packages/package.json
+```
+
+## Boundaries
+
+- 不直接创建远端 Git 项目，除非用户明确要求。
+- 不推送、不创建 MR / PR，除非用户明确要求。
+- 不绕过 OpenAPI Draft / Freeze；API client 生成必须有可追溯 OpenAPI source。
+- 不把模板示例页面当作业务功能交付。
+- 生成后仍需使用 `yss-page-module-development`、`yss-components`、`api-integration` 等专项 skill 实现业务页面。
+
+## Output
+
+- 前端工程生成位置或目标仓库信息。
+- 模板来源和 commit / branch 证据。
+- 替换参数清单。
+- install / lint / type-check / build / generate:api 命令。
+- Harness 实现仓库登记草案。
+- 未覆盖项和 `TODO-HUMAN-REVIEW`。

package/template/.codex/skills/yss-hook/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: "yss-hook"
+description: "YSS 业务逻辑 Hook 开发规范与最佳实践。涉及 useRequest、分页查询、参数管理、数据转换、树数据加载等逻辑抽象时必须使用。"
+---
+
+# YSS Hook 开发标准
+
+Use this skill when you need to extract page logic into `views/**/hooks/useXxx.ts` or when a page has repeated request, pagination, tree loading, or parameter handling.
+
+## Authoritative Docs And Boundary
+
+- YSS UI Hooks documentation: `http://192.168.164.27:3200/hooks`
+- Local reference index: `references/frontend-docs.md`
+
+This skill owns page business logic hooks: request execution, pagination, parameter merging, selection state, and response mapping. Use `api-integration` when the task needs Orval API import/mutator details. Use `yss-components` for layout and component rendering. Use `yss-use-table-height` or `yss-use-tree-height` for height calculations.
+
+中文说明：这个技能只管页面业务逻辑 Hook。组件怎么摆交给 `yss-components`，接口怎么导入和调用交给 `api-integration`，高度计算交给高度专项技能。
+
+## Core rule
+
+- Keep data fetching, parameter merging, and result mapping inside hooks.
+- Keep page components focused on layout, event wiring, and rendering.
+- Use one hook per business domain, not one hook per tiny helper.
+
+## Recommended hook shape
+
+```ts
+export function useReportTable() {
+  const loading = ref(false);
+  const tableData = ref<any[]>([]);
+  const currentParams = ref({
+    page: 1,
+    pageSize: 20,
+  });
+
+  const pagination = reactive({
+    current: 1,
+    pageSize: 20,
+    total: 0,
+    showSizeChanger: true,
+    showQuickJumper: true,
+  });
+
+  const { run: fetchList } = useRequest(apiFn, {
+    manual: true,
+    onSuccess: (res) => {
+      tableData.value = res?.data?.list || [];
+      pagination.total = res?.data?.total || 0;
+    },
+    onError: () => {
+      tableData.value = [];
+      pagination.total = 0;
+    },
+  });
+
+  const query = (params: Record<string, any>) => {
+    currentParams.value = { ...currentParams.value, ...params };
+    return fetchList(currentParams.value);
+  };
+
+  const handlePageChange = (current: number, pageSize: number) => {
+    pagination.current = current;
+    pagination.pageSize = pageSize;
+    return query({ page: current, pageSize });
+  };
+
+  return {
+    loading,
+    tableData,
+    currentParams,
+    pagination,
+    query,
+    handlePageChange,
+  };
+}
+```
+
+## Request rules
+
+- Prefer `useRequest` for all page requests.
+- Use `manual: true` unless the request must fire on mount.
+- Handle success and failure in the hook, not in the page component.
+- Reset list state on failure when stale data would be misleading.
+
+## Parameter rules
+
+- Keep `currentParams` as the single source of truth.
+- Reset `page` to `1` when filters change.
+- Update only `page/pageSize` on pagination actions.
+- Reuse `currentParams` for refresh, export, and submit after edit.
+
+## Tree data rules
+
+Use the same pattern for tree data:
+
+- keep the request and tree mapping in the hook
+- expose `treeData`, `treeLoading`, `selectedKey`, and `handleSelect`
+- keep selection side effects in the hook when they affect data loading
+
+## Return contract
+
+Expose only what the page needs:
+
+- loading flags
+- list or tree data
+- current params
+- pagination or selection state
+- request and action methods
+
+## Implementation order
+
+1. Define the state domains: list, pagination, filters, tree, detail.
+2. Write the request entry with `useRequest`.
+3. Normalize parameters with one merged params object.
+4. Map API responses into page-ready state.
+5. Expose a minimal action surface to the page.
+
+## Checklist
+
+- no duplicated request flow in the page component
+- no split source of truth for params
+- success, failure, and empty-data cases are handled
+- data mapping happens in the hook, not the template
+- pagination and tree loading are decoupled when they represent different domains
+
+## Do not
+
+- do not copy the same request logic into multiple pages
+- do not keep pagination state in both the hook and the component
+- do not let the page component perform nontrivial response mapping
+- do not mix unrelated domains into one hook unless they are inseparable

package/template/.codex/skills/yss-hook/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Hook"
+  short_description: "页面逻辑抽象、请求治理、分页与参数治理落地标准规范"
+  default_prompt: "Use $yss-hook to extract Vue page requests, pagination, and tree-loading logic into a reusable hook."

package/template/.codex/skills/yss-hook/references/frontend-docs.md

@@ -0,0 +1,9 @@
+# yss-hook Frontend Documentation
+
+Generated: 2026-06-29T16:11:14+00:00
+
+Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.
+
+- hooks: http://192.168.164.27:3200/hooks
+
+When documentation and local code differ, inspect the current project code before editing and prefer established local usage.

package/template/.codex/skills/yss-jdbc/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: yss-jdbc
+description: 用于 YSS JDBC 组件的使用与排障。当用户提到 Hutool Db、多数据源 JDBC、动态数据源连接、批量写入、JdbcSqlUtil 或 DefaultHutoolDbHolder 时调用。
+---
+
+# yss-jdbc
+
+用于处理 `yss-component-jdbc` 的动态连接、多数据源、Hutool Db 封装和批量操作问题。
+
+中文说明：本技能必须以本地源码为准，不再依赖旧的 `assets/*.java` 快照。
+
+## 何时使用
+
+- 用户要用 Hutool Db 访问已配置或动态拼装的数据源。
+- 用户在做多数据源同步、搬迁、批量写入。
+- 用户提到 `DefaultHutoolDbHolder`、`JdbcSqlUtil`、`DsParam`。
+- 用户排查 JDBC 工具类、自动配置、连接参数、批量 SQL 或动态数据源问题。
+
+## Source Index First
+
+Backend source location is environment-specific; resolve it with `yss-source-index/references/source-location.md`.
+
+Before changing code or giving exact class/config advice, read:
+
+`references/source-index.md`
+
+Use the index to locate current implementations such as:
+
+- `DefaultHutoolConfiguration`
+- `DefaultHutoolDbHolder`
+- `JdbcSqlUtil`
+- `DsParam`
+- JDBC-related auto configuration, properties, factory, holder, util, and tests
+
+中文说明：如果源码索引与本技能文字不一致，以源码索引和真实源码为准。
+
+## 工作方式
+
+1. 先读 `references/source-index.md`，确认当前组件入口和真实类名。
+2. 确认数据源是“Spring 已配置”还是“运行时动态输入”。
+3. 已配置数据源优先查 `DefaultHutoolDbHolder` 的当前 API。
+4. 动态外部连接优先查 `JdbcSqlUtil` + `DsParam` 的当前 API。
+5. 批量场景优先复用组件提供的批处理能力，不要手写低质量循环 SQL。
+6. 若源码存在测试或示例，优先按测试里的调用方式设计方案。
+
+## 选择规则
+
+- 已注册数据源：`DefaultHutoolDbHolder`
+- 临时连接外部库：`JdbcSqlUtil.getDb(...)`
+- 批量插入或批量 Map 数据：`JdbcSqlUtil` 的批处理能力
+- Spring Boot 接入问题：先看 auto-configuration 和 properties 类
+- 连接参数问题：先看 `DsParam` 字段、校验逻辑和工具方法签名
+
+## 检查清单
+
+- 数据源名称是否与配置一致。
+- 动态连接参数是否完整。
+- 批量操作是否需要事务包裹。
+- 是否错误地把 JDBC 工具层当成完整 ORM 使用。
+- 是否把账号、密码、URL 等敏感连接信息硬编码到业务代码。
+- 是否在 Repository/MyBatis 已覆盖的场景绕过统一持久层规范。
+
+## 修改约束
+
+- 不要在已有 Repository 体系里滥用 JDBC 工具类替代正常持久层。
+- 不要把账号密码直接写入代码常量。
+- 动态连接场景下优先校验连接参数，再执行写操作。
+- 不要凭记忆补类名、方法名或配置项；先从 source-index 跳到真实源码。
+
+## 按需读取
+
+- 源码索引：`references/source-index.md`
+- 组件路径线索：`yss-microservice-components/yss-component-jdbc`

package/template/.codex/skills/yss-jdbc/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS JDBC"
+  short_description: "动态数据源、JDBC 访问、批量写入与排障处理规范"
+  default_prompt: "Use $yss-jdbc to configure or debug Hutool Db, dynamic data sources, and JDBC batch access."

package/template/.codex/skills/yss-jdbc/assets/DefaultHutoolConfiguration.java

@@ -0,0 +1,9 @@
+package com.yss.cloud.jdbc.db;
+
+import org.springframework.context.annotation.ComponentScan;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+@ComponentScan("com.yss.cloud.jdbc.db")
+public class DefaultHutoolConfiguration {
+}

package/template/.codex/skills/yss-jdbc/assets/DefaultHutoolDbHolder.java

@@ -0,0 +1,33 @@
+package com.yss.cloud.jdbc.db;
+
+import cn.hutool.db.Db;
+import cn.hutool.db.Session;
+import com.yss.cloud.mybatis.MultiDataSourceHolder;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Component;
+
+import javax.annotation.PostConstruct;
+import javax.sql.DataSource;
+import java.util.Map;
+
+@Component
+@RequiredArgsConstructor
+public class DefaultHutoolDbHolder {
+    public final MultiDataSourceHolder multiDataSourceHolder;
+    public static Map<String,DataSource> dataSourceMapTemp;
+
+    @PostConstruct
+    public void init(){
+        dataSourceMapTemp = multiDataSourceHolder.getMultiDataSource();
+    }
+
+    public static DataSource getAppDs(String dsName){
+        return dataSourceMapTemp.get(dsName);
+    }
+    public static Db getDb(String dsName) {
+        return Db.use(getAppDs(dsName));
+    }
+    public static Session getSession(String dsName) {
+        return Session.create(getAppDs(dsName));
+    }
+}

package/template/.codex/skills/yss-jdbc/assets/DsParam.java

@@ -0,0 +1,19 @@
+package com.yss.cloud.jdbc.db;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import lombok.ToString;
+
+@Data
+@AllArgsConstructor
+@NoArgsConstructor
+@ToString
+public class DsParam {
+    private String driverClass;
+    private String jdbc;
+    private String userName;
+    private String password;
+
+
+}

package/template/.codex/skills/yss-jdbc/assets/JdbcSqlUtil.java

@@ -0,0 +1,92 @@
+package com.yss.cloud.jdbc.db;
+
+import cn.hutool.db.Db;
+import cn.hutool.db.Entity;
+import cn.hutool.db.Session;
+import cn.hutool.db.ds.simple.SimpleDataSource;
+
+import javax.sql.DataSource;
+import java.sql.SQLException;
+import java.util.*;
+import java.util.function.BiConsumer;
+import java.util.stream.Collectors;
+
+/**
+ * @author zhudaoming
+ */
+public class JdbcSqlUtil {
+
+    public static Db getDb(DsParam dsParam) {
+        return Db.use(
+                new SimpleDataSource(
+                        dsParam.getJdbc(),
+                        dsParam.getUserName(),
+                        dsParam.getPassword(),
+                        dsParam.getDriverClass()));
+    }
+
+    public static Db getDb(DataSource dataSource) {
+        return Db.use(dataSource);
+    }
+    public static Session getDbSession(DataSource dataSource) {
+        return Session.create(dataSource);
+    }
+
+    public static Session getDbSession(DsParam dsParam) {
+        return Session.create(new SimpleDataSource(
+                dsParam.getJdbc(),
+                dsParam.getUserName(),
+                dsParam.getPassword(),
+                dsParam.getDriverClass()));
+    }
+
+    public static List<Object[]> createBatchDataParam(Object[]... paramArray){
+        return new ArrayList<>(Arrays.asList(paramArray));
+    }
+    public static Object[] createQueryDataParam(Object... param){
+        return param;
+    }
+
+    public static void batchAddTableData(String toTable, List<Entity> entities, BiConsumer<String,List<Object[]>> taskCallback) throws SQLException {
+        if (!entities.isEmpty()){
+           String paramRex = entities.stream().findFirst().get().getFieldNames().stream().map(e->"?").collect(Collectors.joining(","));
+            String fields =entities.stream().findFirst().get().getFieldNames().stream().collect(Collectors.joining(","));
+            List<Object[]> allData = entities.stream().map(e -> e.values().toArray()).collect(Collectors.toList());
+            String batchSql = "insert into " +
+                    toTable +
+                    "(" +
+                    fields +
+                    ")" +
+                    "values" +
+                    "(" +
+                    paramRex +
+                    ")";
+            taskCallback.accept(batchSql,allData);
+        }
+    }
+
+    public static void batchAddMapData(String toTable, List<Map<String,String>> mapData, BiConsumer<String,List<Object[]>> taskCallback) throws SQLException {
+        if (!mapData.isEmpty()){
+            String paramRex;
+            String fields;
+            Optional<Map<String, String>> mapOptional = mapData.stream().findFirst();
+            Map<String, String> dataMap = mapOptional.get();
+            Set<Map.Entry<String, String>> entries = dataMap.entrySet();
+            paramRex = entries.stream().map(e -> "?").collect(Collectors.joining(","));
+            fields = entries.stream().map(Map.Entry::getKey).collect(Collectors.joining(","));
+
+            List<Object[]> allData = mapData.stream().map(m -> m.values().toArray()).collect(Collectors.toList());
+            String batchSql = "insert into " +
+                    toTable +
+                    "(" +
+                    fields +
+                    ")" +
+                    "values" +
+                    "(" +
+                    paramRex +
+                    ")";
+            taskCallback.accept(batchSql,allData);
+        }
+
+    }
+}