adspecs 0.1.12

package/references/ecp-end-standard//351/200/232/347/224/250/345/267/245/345/205/267/347/261/273/344/275/277/347/224/250/350/247/204/350/214/203.md

@@ -0,0 +1,189 @@
+# 通用工具类使用规范
+
+> 约束AI在生成代码时正确选用工具类，避免重复造轮子。
+
+## 规则
+
+1. **Hutool优先**：字符串、集合、对象、日期、类型转换等通用操作，必须使用Hutool，禁止使用Apache Commons或手写实现。
+2. **平台工具优先**：涉及会话、加密、Redis、配置、字典、跨模块调用等平台能力时，必须使用平台工具类。
+3. **禁止重复造轮子**：下列工具类已覆盖的功能，不得自行实现。
+
+---
+
+## 一、Hutool工具类（通用操作必须使用）
+
+| 场景 | 类 | 常用方法 |
+|------|-----|---------|
+| 字符串 | `cn.hutool.core.util.StrUtil` | `isEmpty`, `isBlank`, `isNotEmpty`, `trim`, `format` |
+| 集合 | `cn.hutool.core.collection.CollUtil` | `isEmpty`, `isNotEmpty`, `filter`, `newArrayList` |
+| 对象判空 | `cn.hutool.core.util.ObjectUtil` | `isNull`, `isNotNull`, `defaultIfNull` |
+| Bean拷贝 | `cn.hutool.core.bean.BeanUtil` | `copyProperties`, `toBean`, `beanToMap` |
+| 日期 | `cn.hutool.core.date.DateUtil` | `parse`, `format`, `between`, `offsetDay` |
+| 类型转换 | `cn.hutool.core.convert.Convert` | `toStr`, `toInt`, `toLong`, `toList` |
+| Map操作 | `cn.hutool.core.map.MapUtil` | `isEmpty`, `isNotEmpty`, `getStr`, `getInt` |
+| 数字 | `cn.hutool.core.util.NumberUtil` | `isNumber`, `add`, `sub`, `mul`, `div`, `round` |
+
+### 示例
+
+```java
+// 字符串判空
+if (StrUtil.isEmpty(roleName)) {
+    return ResponseData.fail(ResponseMsgCode.NOT_NULL_PARAM.msgCode);
+}
+
+// 集合判空
+if (CollUtil.isEmpty(roleIds)) {
+    return ResponseData.fail(ResponseMsgCode.NOT_NULL_PARAM.msgCode);
+}
+
+// Bean拷贝
+IotBaseRoleEntity entity = new IotBaseRoleEntity();
+BeanUtil.copyProperties(bean, entity);
+```
+
+---
+
+## 二、JSON处理（使用FastJSON）
+
+```java
+JSONObject jsonObject = JSONObject.parseObject(jsonString);
+String value = jsonObject.getString("key");
+JSONArray jsonArray = jsonObject.getJSONArray("items");
+```
+
+---
+
+## 三、平台工具类（涉及平台能力时必须使用）
+
+### 3.1 会话上下文
+
+| 类 | 说明 |
+|-----|------|
+| `UserSessionBean` | 会话对象，包含 `tenantId`, `userId`, `depId`, `isAdmin`, `isSuperAdmin` |
+| `UserSessionHelper` | 获取当前会话 |
+| `AuthorizationCommonUtils` | Token验证和线程级会话管理 |
+
+```java
+// Controller中
+UserSessionBean session = getUserSessionBean();
+
+// Service或其他位置
+UserSessionBean session = UserSessionHelper.getCurrentSession();
+```
+
+### 3.2 加密工具 - `com.sie.iot.common.util.EncryUtil`
+
+提供RSA加密/解密能力，兼容历史DES数据。
+
+| 方法 | 说明 |
+|------|------|
+| `encrypt(String plainText)` | RSA加密（使用默认公钥） |
+| `decrypt(String cipherText)` | 解密（自动兼容RSA和历史DES数据） |
+| `encrypt(String plainText, String key, String salt)` | 使用自定义公钥加密 |
+| `decrypt(String cipherText, String key, String salt)` | 使用自定义私钥解密 |
+
+```java
+// 加密
+String encrypted = EncryUtil.encrypt(plainText);
+
+// 解密（自动兼容RSA/DES）
+String decrypted = EncryUtil.decrypt(cipherText);
+```
+
+### 3.3 全局配置获取 - `com.sie.iot.common.util.ServerConfigConmonUtil`
+
+从Redis获取平台全局配置，支持租户级覆盖和类型转换。
+
+| 方法 | 说明 |
+|------|------|
+| `get(String key, RedisTemplate)` | 获取全局配置值 |
+| `get(String key, Long tenantId, RedisTemplate)` | 获取租户级配置，无则回退全局 |
+| `get(String key, Long tenantId, RedisTemplate, T defValue)` | 带默认值，支持Boolean/Long/Integer/BigDecimal类型自动转换 |
+
+```java
+// 获取全局配置
+String value = ServerConfigConmonUtil.get("config_key", redisTemplate);
+
+// 获取租户级配置（自动回退全局）
+String value = ServerConfigConmonUtil.get("config_key", tenantId, redisTemplate);
+
+// 带默认值和类型转换
+Boolean enabled = ServerConfigConmonUtil.get("feature_enabled", tenantId, redisTemplate, Boolean.FALSE);
+```
+
+### 3.4 Redis操作 
+
+- 优先使用 `DawnRedis`（`com.sie.iot.common.redis.DawnRedis`）
+- 仅当 `DawnRedis` 无法满足需求时（如 Pipeline、Lua 脚本、Stream），才使用 `RedisTemplate`
+- 通过 `DawnRedis.getRedisTemplate()` 获取底层 `RedisTemplate`，不要单独注入
+
+```java
+@Autowired
+private DawnRedis dawnRedis;
+```
+
+**Key 规范**
+- 格式：`模块:业务:标识`，如 `user:session:10001`
+- 推荐通过 `ICacheKey` 接口定义枚举统一管理 key 前缀和过期时间：
+
+**常用 API 速查** 
+
+| 场景 | 方法 |
+|------|------|
+| 字符串读写 | `set(key, value)` / `setEx(key, value, duration)` / `get(key)` |
+| 带 CacheKey 读写 | `set(cacheKey, value)` / `get(cacheKey)` |
+| 缓存加载（防穿透） | `get(key, () -> loader)` / `get(cacheKey, () -> loader)` |
+| 条件设置 | `setNx(key, value)` / `setNx(key, value, timeout, unit)` |
+| 计数器 | `incr(key)` / `incrBy(key, n)` / `decr(key)` / `decrBy(key, n)` |
+| 过期管理 | `expire(key, seconds)` / `expire(key, duration)` / `ttl(key)` |
+| 删除 | `del(key)` / `del(cacheKey)` / `del(key1, key2, ...)` |
+| 存在性 | `exists(key)` |
+| Hash | `hSet` / `hGet` / `hMset` / `hGetAll` / `hDel` / `hExists` / `hKeys` / `hIncrBy` |
+| List | `lPush` / `lPushRight` / `lPop` / `rPop` / `lRange` / `lLen` / `lTrim` |
+| Set | `sAdd` / `sMembers` / `sIsMember` / `sRem` / `sInter` / `sUnion` / `sDiff` |
+| ZSet | `zAdd` / `zRange` / `zRevrange` / `zRangeByScore` / `zRank` / `zRem` / `zScore` |
+| 查询任意类型 | `query(key)` 返回 `RedisResult`（自动识别类型） |
+
+
+### 3.5 数据字典 - `com.sie.iot.common.util.DictionaryCommonUtil`
+
+```java
+// 获取字典名称
+String name = DictionaryCommonUtil.getCodeName("lookup_type", "code");
+
+// 租户级查询
+String name = DictionaryCommonUtil.getCodeName("lookup_type", "code", tenantId);
+```
+
+### 3.6 跨模块调用 - `com.sie.iot.common.util.SaafToolUtils`
+
+| 方法 | 说明 |
+|------|------|
+| `preaseServiceResult(url, params)` | 跨模块REST调用，返回JSONArray |
+| `preaseServiceResultJSON(url, params)` | 跨模块REST调用，返回JSONObject |
+| `validateJsonParms(jsonObject, keys...)` | 校验JSON必填字段 |
+| `buildLogicIN(item, valueList)` | 构建SQL IN子句（自动拆分>1000项） |
+
+
+### 3.7 Spring容器 - `com.sie.iot.common.util.SpringBeanUtil`
+
+```java
+Object bean = SpringBeanUtil.getBean("beanName");
+```
+
+---
+
+## 四、日志规范
+
+使用SLF4J，禁止 `System.out.println`。
+
+```java
+private static final Logger LOGGER = LoggerFactory.getLogger(XxxController.class);
+
+LOGGER.debug("查询参数: {}", bean);
+LOGGER.info("操作成功，ID: {}", id);
+LOGGER.warn("数据异常: {}", msg);
+LOGGER.error("操作失败: {}", e.getMessage(), e);
+
+// 禁止记录密码等敏感信息
+```

package/references/front-demo/.claude/rules/INDEX.md

@@ -0,0 +1,54 @@
+# 前端规则文件索引
+
+本目录包含 `sie-front-demo` 的 AI 开发规则。生成或修改代码前，先按任务类型读取对应规则。
+
+## 文件组织
+
+```text
+.claude/rules/
+├── INDEX.md
+├── project-overview.md
+├── gushen-components.md
+├── page-development-rules.md
+├── api-i18n-rules.md
+└── page-template-index.md
+```
+
+## 推荐读取顺序
+
+### 新增普通业务页面
+
+1. `project-overview.md`
+2. `page-development-rules.md`
+3. `gushen-components.md`
+4. `api-i18n-rules.md`
+5. `page-template-index.md`
+
+### 新增列表页
+
+1. `gushen-components.md`
+2. `page-development-rules.md`
+3. `api-i18n-rules.md`
+4. `page-template-index.md`
+
+### 新增表单或流程页面
+
+1. `page-development-rules.md`
+2. `api-i18n-rules.md`
+3. `page-template-index.md`
+
+### 选择复杂页面模板
+
+1. `page-template-index.md`
+2. 根据选中的模式补读 `gushen-components.md` 或 `api-i18n-rules.md`
+
+### 使用 `@gushen` 组件
+
+1. `gushen-components.md`
+2. 如规则不足，读取 `node_modules/@gushen/*/src` 中对应组件源码。
+
+## 维护要求
+
+- 新增规则文件时，同步更新本索引和根目录 `claude.md`。
+- 修改页面模板候选时，同步更新 `page-template-index.md`。
+- 组件依赖升级后，重新读取 `node_modules/@gushen/*/src`，再更新 `gushen-components.md`。

package/references/front-demo/.claude/rules/api-i18n-rules.md

@@ -0,0 +1,65 @@
+# API 与多语言规则
+
+## API 文件
+
+新增 API 放在 `src/api/<module>/<page>/index.ts` 或已有模块目录下。
+
+推荐写法：
+
+```ts
+import request from '@/utils/request'
+
+export function findPagination(data: any) {
+  return request({
+    url: '/api/demoa/example/find-pagination',
+    method: 'post',
+    data,
+  })
+}
+```
+
+## 请求规则
+
+- POST 保存、更新、分页查询按现有接口要求传 `data`。
+- 保存/更新业务对象通常使用 `{ params: formData }` 包装。
+- GET 查询单条使用 `params`，不要拼接复杂 query 字符串。
+- 不确定后端前缀时，先参考同模块 API 文件，不要凭空新增服务前缀。
+- 需要动态域名时，参考旧页面中的 `window.getVersionTypeApiUrl(...)` 用法。
+
+## 成功判断
+
+- Composition API 页面优先 import `reqIsSucceed`。
+- Options API 旧页面可使用 `this.reqIsSucceed(res)`。
+- 不要在新页面里散落 `res.code === 800`、`res.status === 'S'`；只有维护旧接口或流程接口时才沿用既有判断。
+
+## 错误处理
+
+- 保存、删除、提交等用户操作需要 loading 防重复点击。
+- 失败时显示后端 `msg` 或明确错误提示。
+- 不要吞掉 catch；至少恢复 loading 状态。
+
+## 多语言
+
+本工程语言包位于：
+
+- `src/lang/zh-cn.ts`
+- `src/lang/en-us.ts`
+- `src/lang/zh-tw.ts`
+- `src/lang/modules/<module>/<locale>.ts`
+
+规则：
+
+- 新增用户可见文案优先放入模块语言包。
+- 至少补齐 `zh-cn`、`en-us`、`zh-tw`；如果现有模块已有 `hu-hu`、`vi-vn`，同步评估是否需要补。
+- 模板中使用 `$t('module.key')` 或 `t('module.key')`。
+- 表格列名、按钮、提示、确认文案、校验信息都属于用户可见文案。
+
+## 路由标题
+
+路由 `meta.title` 使用中文标题；`meta.enTitle` 在当前工程常见为多语言 JSON 字符串：
+
+```ts
+enTitle: '{"zh-tw":"消息中心","en-us":"letters","hu-hu":"Üzenetközpont","vi-vn":"Trung tâm thông điệp"}'
+```
+
+新增路由时保持和邻近路由一致。

package/references/front-demo/.claude/rules/gushen-components.md

@@ -0,0 +1,174 @@
+# Gushen 前端组件规则
+
+本工程依赖：
+
+- `@gushen/gushen-common-components`
+- `@gushen/gushen-form-render`
+
+当前目标工程未安装 `@gushen/gushen-work-flow`。如果需求涉及工作流组件（如 `flow-container`、`flow-ea-buttons`、`flow-commit`），先确认依赖、注册方式和运行时子应用边界，不要直接生成组件用法。
+
+使用组件前，优先读取组件源码：`node_modules/@gushen/gushen-common-components/src/packages/components`。
+
+## 全局注册
+
+`src/core/initMain.ts` 已执行：
+
+```ts
+import GsComponents from '@gushen/gushen-common-components'
+instance.use(GsComponents)
+```
+
+因此 `gs-*` 公共组件可直接在模板中使用。当前本地全局组件仅包含 `GsIconDialog`、`GsIcon`、`SvgIcon`、`UploadImg`，注册位置为 `src/components/global-register.ts`。
+
+常见公共组件分类：
+
+- 表格：`GsTable`、`GsCustomizeTable`、`GsVxeTable`、`GsSuperTable`
+- 查询/输入：`GsSearchBar`、`GsInput`、`GsSelect`、`GsRadio`、`GsSwitch`
+- 选择器：`GsSelectTreeTable`、`GsPersonnelSelector`、`GsDepartmentSelector`、`GsPageSelect`、`GsDialogSelector`
+- 上传/导入导出：`GsUpload`、`GsAttachmentList`、`UploadImg`、`GsImportData`、`GsExportData`
+- 弹层/布局：`GsDialog`、`GsDrawer`、`GsCard`、`GsGridLayout`
+
+## `GsCustomizeTable` / `gs-table`
+
+源码路径：`node_modules/@gushen/gushen-common-components/src/packages/components/GsCustomizeTable`。
+
+### 推荐用途
+
+- 后端分页列表页。
+- 需要列设置、表头查询、刷新、导入导出、关键字搜索的业务列表。
+- 页面模板统一从 `page-template-index.md` 选择；本规则只说明组件 API 和约束。
+
+### 核心配置
+
+组件级常用 props：
+
+- `gridConfig`：核心表格配置，和源码 `defaultConfig()` 合并。
+- `queryParams`：请求参数，常见结构为 `{ params: { pageIndex, pageRows, params: {} }, queryUrl }`。
+- `fixedParams`：固定参数，搜索重置时保留。
+- `tableParams`：表头搜索附加参数。
+- `method`：请求方法，默认 `post`。
+- `tableHeight` / `maxHeight`：高度控制。
+- `reserveSelection`：跨页保留勾选，需配合 `rowKey`。
+- `readonly`：只读禁用交互。
+- `isParamsOutSearch`：为 true 时抛出 `paramsOutSearch`，由父组件接管请求。
+- `reqBeforeHandler` / `resDataHandler`：请求前和响应数据处理钩子。
+
+常用顶层配置来自 `common/defaultConfig.js`：
+
+- `columns`：列配置。
+- `queryUrl`：远程查询接口。
+- `selectable`：是否显示勾选列。
+- `showIndex`：是否显示序号列。
+- `slotArr`：需要自定义插槽渲染的列字段。
+- `needPagination` / `paged`：是否分页。
+- `hideSearchBtn`：是否隐藏表头查询切换。
+- `showSetting`：是否显示列设置。
+- `showRefresh`：是否显示刷新按钮。
+- `importable` / `exportable`：是否启用导入导出。
+- `enableCustomizeFilter`：是否启用高级筛选。
+- `isVirtualList`：是否启用虚拟滚动。
+- `localstorageName`：列设置缓存 key。
+- `rowKey`：跨页勾选、虚拟列表建议设置，默认常用 `id`。
+- `showKeyWordSearch`：是否显示关键字搜索。
+- `isScrollRequest`：是否启用滚动加载。
+
+列默认配置来自 `common/columnDefaultConfig.js`：
+
+- `prop`、`label`、`width`、`align`、`headerAlign`、`fixed`。
+- `isShow`、`hidden`、`hiddenFlag` 控制显示。
+- `sortable` 默认 `true`。
+- `showOverflowTooltip` 默认 `true`。
+- `dataType` 默认 `string`。
+- `dictCode` 可配合字典数据做显示转换。
+- `list` 可提供下拉选项。
+- `component`、`componentAttr`、`list` 可用于表头搜索控件。
+- `sortableType: 'all'` 表示远程排序。
+- `hideSearh` 用于禁用表头搜索（源码拼写如此）。
+
+### 插槽
+
+- `#table-title`：表格标题。
+- `#btn`：表格头部左侧按钮。
+- `#btn-r`：头部浮动按钮区域。
+- `#expand`：展开行。
+- `#pager`：自定义分页区域。
+- 字段插槽：字段名必须加入 `slotArr`，例如 `slotArr: ['readStatus', 'action']` 后可写 `#readStatus`、`#action`。
+
+### 事件
+
+常用事件：
+
+- `@inited`：表格初始化完成，返回表格实例。
+- `@updateTableData`：表格数据更新。
+- `@update:tableTotal`：总数更新。
+- `@requestError`：请求异常。
+- `@pageChange`、`@sizeChange`：分页变化。
+- `@row-click`：行点击。
+- `@select-all`：全选变化。
+- `@sort-change`：排序变化。
+- `@header-dragend`：列宽拖拽结束。
+- `@needSearchChange`：表头查询开关变化。
+- `@paramsOutSearch`：外部接管查询参数。
+- `@import-success`、`@exportSuccess`：导入导出成功。
+
+### 实例方法
+
+通过 `ref` 可调用：
+
+- `refresh(hasLoading, isClearSelection = true)`：刷新数据。
+- `getData(...)`：按当前配置查询。
+- `outSearch(isKeepPage?, noLike?, hasLoading?, index?)`：外部搜索条件变化后触发查询。
+- `tableSearch(isKeepPage?, index?)`：表头查询。
+- `getSelection()`：获取勾选行。
+- `setRowSelection(row, flag, key?)`：切换指定行选中。
+- `getCurrentParams()`：获取当前请求参数。
+- `resetTable()` / `init()` / `doTableLayout()`：重置、初始化、重排布局。
+- `setFirstRow()`：选中首行并触发 `getfirstdata`。
+
+### 生成代码约束
+
+- 普通值展示优先使用列配置和 `dictCode`，不要为了纯文本显示滥用插槽。
+- 需要 `el-tag`、按钮、链接、富文本等复杂渲染时，字段必须加入 `slotArr`。
+- 操作列使用 `prop: 'action'`、`fixed: 'right'`，并加入 `slotArr`。
+- 表头查询字段使用 `component`、`componentAttr`、`list`；字典字段优先配置 `dictCode`。
+- 每个列表页设置唯一 `localstorageName`，避免列设置缓存串页。
+- 外部查询条件变化后更新 `queryParams.params.params`，再调用 `tableRef.value?.outSearch(false)`；普通刷新调用 `tableRef.value?.refresh(true)`。
+- 勾选场景必须设置 `rowKey`。
+
+## `GsTable`
+
+源码路径：`node_modules/@gushen/gushen-common-components/src/packages/components/GsTable/index.vue`。
+
+- 适合简单本地或远程表格。
+- `columns` 控制列，`options`/工具配置控制搜索、刷新、列设置、选择列、序号列、加减行。
+- `#header` 放头部按钮，`#cell` 用于可编辑或自定义单元格。
+- 旧代码中 `<gs-table :columns="columns" :options="options" :remote="remoteData">` 是可参考写法。
+
+## `GsSearchBar`
+
+源码路径：`node_modules/@gushen/gushen-common-components/src/packages/components/GsSearchBar/index.vue`。
+
+- `searchConfig.items` 描述查询项，字段名使用 `field`。
+- `fixedParams` 会合并进查询参数。
+- `btnPosition` 支持 `top` / `bottom`。
+- 查询项 `type` 直接映射 Element Plus 组件，如 `el-input`、`el-select`、`el-cascader`。
+- `el-select` 的选项使用 `options: [{ label, value }]`。
+- `#prepend`、`#append` 可插入按钮。
+- 事件：`@search="handleSearch"`、`@reset="handleReset"`、`@expand="handleExpand"`。
+- 可通过实例方法 `setFormItemValue(field, value)` 设置查询字段。
+
+## 上传与图片
+
+- 本地全局 `UploadImg` 来自 `src/components/UploadImg/index.vue`。
+- 公共组件库也提供 `GsUpload`、`UploadImg`，使用前对照源码确认事件和字段。
+- 文件上传 API 参考 `src/api/attachment.ts` 和 `src/components/GsUpload`。
+
+## 动态表单
+
+- 依赖 `@gushen/gushen-form-render` 已安装。
+- 动态表单组件来自 `@gushen/gushen-form-render`，常用注册名是 `FormRender` / `<form-render>`；不存在 `GsForm` 业务组件。
+- 当前 `src/core/initMain.ts` 中插件注册是注释状态；新增 `<FormRender />` 前，先确认是否需要解除注释：
+  - `import GushenFormRender from '@gushen/gushen-form-render'`
+  - `import '@gushen/gushen-form-render/lib/gushen-form-render.css'`
+  - `instance.use(GushenFormRender)`
+- 现有动态表单入口：`src/views/dynamic-form/index.vue`。