adspecs 0.1.40 → 0.1.42

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "adspecs",
       "description": "AI Coding研发协同开发插件",
-      "version": "0.1.40",
+      "version": "0.1.42",
       "source": "./",
       "author": {
         "name": "Qingwen Chen",

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "adspecs",
   "displayName": "adspecs AI Plugin",
   "description": "AI first工程规范驱动开发插件",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "author": {
     "name": "Qingwen Chen",
     "email": "cqinwn@qq.com",

package/.codebuddy-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "adspecs",
   "displayName": "adspecs AI 工程规范驱动开发插件",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "AI-first specification-driven development plugin for ECP platform full-lifecycle development",
   "descriptionZh": "AI优先的工程规范驱动开发插件，覆盖需求分析、PRD、系统设计、任务拆解、TDD、代码评审、Wiki同步全流程",
   "author": {

package/.qoder-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "adspecs",
   "displayName": "adspecs AI 工程规范驱动开发插件",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "AI-first specification-driven development plugin for ECP platform full-lifecycle development",
   "descriptionZh": "AI优先的工程规范驱动开发插件，覆盖需求分析、PRD、系统设计、任务拆解、TDD、代码评审、Wiki同步全流程",
   "author": {

package/.workbuddy-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "adspecs",
   "displayName": "adspecs AI 工程规范驱动开发插件",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "AI-first specification-driven development plugin for ECP platform full-lifecycle development",
   "descriptionZh": "AI优先的工程规范驱动开发插件，覆盖需求分析、PRD、系统设计、任务拆解、TDD、代码评审、Wiki同步全流程",
   "author": {

package/README.md

@@ -291,7 +291,7 @@ adspecs init
 | `front-demo/`              | Vue 3 前端演示项目（Vite + TS + Element Plus） |
 | `antd-front-demo/`         | Ant Design React 前端演示项目                  |
 | `ant6-front-standard/`     | Ant Design 6 前端编码规范（12 篇）             |
-| `vue3-front-stantard/`     | Vue 3 前端编码规范                             |
+| `vue3-front-standard/`     | Vue 3 前端编码规范                             |
 | `python-end-standard/`     | Python 后端参考                                |
 | `yudaocloud-end-standard/` | 芋道 Cloud 后端集成参考                        |
 | `tools/`                   | 辅助工具集                                     |

package/bin/adspecs.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 'use strict';
 
 const { Command } = require('commander');
@@ -25,7 +25,7 @@ program
   .option('--company <name>', '公司名称', 'XX有限公司')
   .option('--confidentiality <level>', '文件密级: 公开|内部资料|机密|绝密', '内部资料')
   .option('--mode <mode>', '初始化模式: simple|classic|full|demo')
-  .option('--front-demo <stack>', '前端演示技术栈: vue|antd', 'vue')
+  .option('--front-demo <stack>', '前端演示技术栈: vue|antd')
   .option('--modules <list>', '后端模块列表（逗号分隔，格式 {port}-crm-{name}:{package}）')
   .option('--non-interactive', '非交互模式，所有未提供的参数使用默认值')
   .option('--force', '跳过冲突决策，所有已存在区域直接重新创建')

package/hooks/commit-queue.js

@@ -20,7 +20,8 @@ const platform = require('./platform');
 
 // ── 配置 ──────────────────────────────────────────────
 // 队列文件放在目标项目根目录的平台状态目录下。
-// 使用 process.cwd() 获取目标项目根目录（平台运行 hook 时 CWD 即为目标项目）。
+// 项目根由 platform.getProjectRoot() 解析：优先 CLAUDE_PROJECT_DIR 环境变量，兜底 cwd
+// （会话中途 cd 到子目录时，状态文件仍落在真正的项目根，避免队列分裂）。
 const PROJECT_ROOT = platform.getProjectRoot();
 const QUEUE_DIR = platform.getStateDir(PROJECT_ROOT);
 const QUEUE_FILE = path.join(QUEUE_DIR, '.commit-candidates');

package/hooks/hooks.json

@@ -1,24 +1,23 @@
 {
-  "_comment": "跨平台 Hook 配置 — 同时支持 Claude Code、Qoder 和 WorkBuddy。所有脚本命令使用项目根目录相对路径（hooks/xxx.js），由 /project-init 将插件 hooks/ 复制到目标项目根。平台运行时 CWD 即为目标项目根目录。",
   "hooks": {
     "SessionStart": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "node hooks/session-start.js"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.js\""
           },
           {
             "type": "command",
-            "command": "node hooks/wiki-queue.js init"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/wiki-queue.js\" init"
           },
           {
             "type": "command",
-            "command": "node hooks/commit-queue.js init"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/commit-queue.js\" init"
           },
           {
             "type": "command",
-            "command": "node hooks/session-logger.js init"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-logger.js\" init"
           }
         ]
       }
@@ -28,7 +27,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node hooks/session-logger.js mark"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-logger.js\" mark"
           }
         ]
       }
@@ -40,24 +39,18 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node hooks/wiki-queue.js enqueue"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/wiki-queue.js\" enqueue"
           }
-        ],
-        "conditions": {
-          "filePattern": "\\.(java|py|ts|js|go|rs|cs|md|vue|tsx|jsx)$"
-        }
+        ]
       },
       {
         "matcher": "Write|Edit|SearchReplace",
         "hooks": [
           {
             "type": "command",
-            "command": "node hooks/commit-queue.js enqueue"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/commit-queue.js\" enqueue"
           }
-        ],
-        "conditions": {
-          "filePattern": "pipeline-manifest\\.json$"
-        }
+        ]
       }
     ],
     "Stop": [
@@ -65,15 +58,15 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node hooks/wiki-queue.js report"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/wiki-queue.js\" report"
           },
           {
             "type": "command",
-            "command": "node hooks/commit-queue.js report"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/commit-queue.js\" report"
           },
           {
             "type": "command",
-            "command": "node hooks/session-logger.js report"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-logger.js\" report"
           }
         ]
       }

package/hooks/platform.js

@@ -72,12 +72,16 @@ function getPluginRoot(hooksDir) {
 
 /**
  * 获取目标项目根目录
- * 两种平台均使用 process.cwd()（运行时 CWD 即为目标项目）
+ * 优先 CLAUDE_PROJECT_DIR（Claude Code 执行 hook 时注入，恒指向会话项目根），
+ * 兜底 process.cwd()。
+ * 背景：旧实现仅用 cwd——会话中途 cd 到子目录（如 front-demo/）后，Stop hook 会把
+ * .wiki-update-queue / marker / 日志等状态误写进子目录，产生项目状态分裂。
+ * Qoder/WorkBuddy 不注入该环境变量，行为与旧版一致。
  *
  * @returns {string}
  */
 function getProjectRoot() {
-  return process.cwd();
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
 
 /**

package/hooks/session-logger.js

@@ -18,7 +18,8 @@ const path = require('path');
 const platform = require('./platform');
 
 // ── 路径解析 ──────────────────────────────────────────────
-// 使用 process.cwd() 定位目标项目（不用 __dirname，因为 __dirname 指向插件目录）
+// 项目根由 platform.getProjectRoot() 解析：优先 CLAUDE_PROJECT_DIR，兜底 cwd
+// （不用 __dirname——它指向插件目录而非目标项目）
 const PROJECT_ROOT = platform.getProjectRoot();
 const STATE_DIR = platform.getStateDir(PROJECT_ROOT);
 const MARKER_FILE = path.join(STATE_DIR, '.session-save-marker');

package/hooks/wiki-queue.js

@@ -19,7 +19,8 @@ const platform = require('./platform');
 
 // ── 配置 ──────────────────────────────────────────────
 // 队列文件放在目标项目根目录的平台状态目录下。
-// 使用 process.cwd() 获取目标项目根目录（平台运行 hook 时 CWD 即为目标项目）。
+// 项目根由 platform.getProjectRoot() 解析：优先 CLAUDE_PROJECT_DIR 环境变量，兜底 cwd
+// （会话中途 cd 到子目录时，状态文件仍落在真正的项目根，避免队列分裂）。
 const PROJECT_ROOT = platform.getProjectRoot();
 const QUEUE_DIR = platform.getStateDir(PROJECT_ROOT);
 const QUEUE_FILE = path.join(QUEUE_DIR, '.wiki-update-queue');

package/package.json

@@ -1,65 +1,65 @@
-{
-  "name": "adspecs",
-  "version": "0.1.40",
-  "description": "AI first 工程规范驱动开发插件 — 支持 npm 安装和 CLI 初始化",
-  "bin": {
-    "adspecs": "bin/adspecs.js"
-  },
-  "main": "./src/utils.js",
-  "files": [
-    "bin/",
-    "src/",
-    ".claude-plugin/",
-    ".qoder-plugin/",
-    ".codebuddy-plugin/",
-    ".workbuddy-plugin/",
-    ".adspecs/",
-    "skills/",
-    "hooks/",
-    "references/",
-    "scripts/postinstall.js",
-    "scripts/sync-version.js",
-    "CLAUDE.md",
-    "README.md",
-    "INSTALL.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "scripts": {
-    "test": "node --test src/**/*.test.js",
-    "postinstall": "node scripts/postinstall.js",
-    "prepublishOnly": "node scripts/prepublish-check.js",
-    "version": "node scripts/sync-version.js && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json .qoder-plugin/plugin.json .codebuddy-plugin/plugin.json .workbuddy-plugin/plugin.json",
-    "sync-version": "node scripts/sync-version.js"
-  },
-  "dependencies": {
-    "commander": "^12.0.0",
-    "@inquirer/prompts": "^7.0.0",
-    "chalk": "^4.1.2"
-  },
-  "devDependencies": {},
-  "keywords": [
-    "adspecs",
-    "claude-code",
-    "qoder",
-    "workbuddy",
-    "plugin",
-    "scaffold",
-    "cli",
-    "project-init",
-    "ai-first"
-  ],
-  "author": "Qingwen Chen <cqinwn@qq.com>",
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "https://gitee.com/yuebon/adp-plugins.git"
-  },
-  "homepage": "https://gitee.com/yuebon/adp-plugins#readme",
-  "bugs": {
-    "url": "https://gitee.com/yuebon/adp-plugins/issues"
-  }
-}
+{
+  "name": "adspecs",
+  "version": "0.1.42",
+  "description": "AI first 工程规范驱动开发插件 — 支持 npm 安装和 CLI 初始化",
+  "bin": {
+    "adspecs": "bin/adspecs.js"
+  },
+  "main": "./src/utils.js",
+  "files": [
+    "bin/",
+    "src/",
+    ".claude-plugin/",
+    ".qoder-plugin/",
+    ".codebuddy-plugin/",
+    ".workbuddy-plugin/",
+    ".adspecs/",
+    "skills/",
+    "hooks/",
+    "references/",
+    "scripts/postinstall.js",
+    "scripts/sync-version.js",
+    "CLAUDE.md",
+    "README.md",
+    "INSTALL.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test src/**/*.test.js",
+    "postinstall": "node scripts/postinstall.js",
+    "prepublishOnly": "node scripts/prepublish-check.js",
+    "version": "node scripts/sync-version.js && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json .qoder-plugin/plugin.json .codebuddy-plugin/plugin.json .workbuddy-plugin/plugin.json",
+    "sync-version": "node scripts/sync-version.js"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^4.1.2"
+  },
+  "devDependencies": {},
+  "keywords": [
+    "adspecs",
+    "claude-code",
+    "qoder",
+    "workbuddy",
+    "plugin",
+    "scaffold",
+    "cli",
+    "project-init",
+    "ai-first"
+  ],
+  "author": "Qingwen Chen <cqinwn@qq.com>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://gitee.com/yuebon/adp-plugins.git"
+  },
+  "homepage": "https://gitee.com/yuebon/adp-plugins#readme",
+  "bugs": {
+    "url": "https://gitee.com/yuebon/adp-plugins/issues"
+  }
+}

package/references/vue3-front-standard/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/vue3-front-standard/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/vue3-front-standard/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`。