jetlinks-web

name	jetlinks-web
description	在 JetLinks 前端工作区中实现或改造 Vue3 页面，优先复用 `@jetlinks-web-core` 与 `@jetlinks-web` 的组件、hooks、utils。适用于列表页/详情页/弹窗开发、后端 EnumDict/I18nEnumDict 返回 `{value,text}` 的枚举渲染、目录落点判断、状态管理、类型与质量约束、Tab 回传、平台上下文、运行时注册扩展、路由菜单装配与查询参数编码等场景。除局部调整白名单外，任何新增页面、页面壳层重构、信息架构或主筛选 / 主列表 / 主详情承载变化，都必须先联合 `jetlinks-web-style` 形成交互方案档案，再进入实现。

JetLinks Web

Read references/web-development-rules.md first.

Workflow

1. Read references/web-development-rules.md and classify the task as page implementation, interaction solution selection, capability reuse, state/quality concerns, in-framework interaction polishing, or business-driven experience design.
2. Inspect adjacent production code and verify workspace facts (actual exports, package availability, adjacent examples, and module structure), then read references/component-source-rules.md when choosing components so the current workspace jetlinks-web-core remains the first source of truth.
3. Analyze the real business goal before sketching UI: target users, high-frequency tasks, key decisions, status transitions, exception paths, and whether the page is actually CRUD-heavy or should be workbench / detail / dashboard / process-oriented.
4. Before coding, check five decision facts: target user, first task after entering the page, success criterion, whether the user operates one object or many, and the source of any key metric/chart. If any one is critical and unknown, ask the user first; if two or more are unknown, or page type is still undecided across multiple patterns, you must stop and clarify before implementation.
5. Select only the minimal additional references from references/index.md based on task scope, and treat references as supporting material only after the business model is clear.
6. Unless the task hits the jetlinks-web-style local-tweak whitelist (single form field / single filter chip / single dialog content / styling-copy-props-only), load ../jetlinks-web-style/SKILL.md and form a solution profile before coding. Use the catalog shards linked from ../jetlinks-web-style/references/style-catalog.md (index): at minimum style-catalog-routing.md + style-catalog-core-base.md, and when templates imply object detail / master-detail / runtime-edit shell / prominent sidebar also style-catalog-core-detail-shell.md (see style-catalog-core.md); load only the matching ### subsections of style-catalog-templates.md for the recommended solution and up to 3 alternatives—do not load the entire templates file. If known facts clearly support one recommendation and the user asked for implementation, proceed with that recommendation and report it as the assumed choice; if critical facts are missing or 2+ templates remain equally plausible, ask the user to choose before coding. The thin index at references/interaction-solution-catalog.md only points to the catalog and must not be used as the source of template definitions.
7. After the solution profile is locked, load references/component-reuse-patterns.md and map every card, list, detail section, icon, dynamic edit, filter, drawer, tag, status, and resource-picker scenario to existing jetlinks-web-core components before creating local UI.
8. When page type is still unclear, load references/page-pattern-decision-rules.md first; when deciding whether a block should exist, load references/block-admission-rules.md; when borrowing from examples, load references/business-ui-example-rules.md.
9. When the page includes reusable search or filtering, first decide whether the current workspace ConditionFilter plus its route encode/decode toolchain should own the search layer; for generic condition search, tokenized editing, dynamic route query encoding, remote option panels, or quick filter sidebars, load references/condition-filter-rules.md and treat ConditionFilter as the first candidate. Before creating any field-specific search UI, first classify the field into generic editor categories such as text, number, date/time, range, boolean, option/reference, nested path, or valueless condition, and decide whether the value editor can be expressed through field-driven generic editors plus field-level transform hooks.
10. Prefer adjacent pages, same-domain modules, or similar business scenarios as references; extract interaction patterns, information architecture, component combinations, and feedback rhythm, but do not copy flows, metrics, page shells, local components, or API contracts from unrelated business domains.
11. When the task includes UI or interaction optimization, combine with $frontend-design only after locking these local style anchors plus the Ant Design / Ant Design Vue baseline; use it to refine hierarchy, feedback, and micro-interactions inside the current framework style instead of inventing a new visual language.
12. If the page skeleton or interaction path is still uncertain, or the user would benefit from validating direction first, provide a low-fidelity wireframe or effect sketch before implementation, then code after alignment.
13. Before coding frontend files, run the reuse and decomposition gate:
    • list the Vue/JSX/TSX files expected to be created or edited;
    • define each file's responsibility boundary;
    • search existing shared exports and adjacent implementations for reusable components, hooks, utils, services, and API wrappers;
    • decide whether UI, state orchestration, request logic, or data transforms should live in a component, hook, service/api, or util.
14. Check existing capabilities before creating new abstractions, in this order:
    • same feature directory near the target page;
    • same modules/<module>-ui/** module;
    • sibling modules in the same business domain or with the same interaction/data pattern;
    • shared packages and source exports such as @jetlinks-web-core/*, @jetlinks-web/*, and jetlinks-web-core/src/*/index.ts;
    • public module exports, registries, runtime extension points, or documented cross-module APIs. Reuse, configure, or adapt existing capabilities when stable. Do not deep-import private code from another business module unless it is already an accepted local pattern.
15. If any created or edited Vue/JSX/TSX file may exceed 300 lines, if a UI/logic structure appears twice or more, or if request/business orchestration would enter a UI component, split before implementation. Do not postpone decomposition as cleanup.
16. Implement the smallest complete change with Vue 3 SFC + script setup lang="ts" after confirming reusable abstractions, extraction boundaries, current workspace exports, and the comment insertion points required by references/quality-and-type-rules.md.
17. After coding, check created or modified Vue/JSX/TSX file line counts. Any file over 300 lines is a blocking issue unless this is a narrow bug fix on an already-large file and the exception is explicitly reported.
18. Before final output, verify how the current workspace handles frontend i18n for user-visible copy such as 页面标题、区块标题、字段展示名、表格列头、按钮、Tab、空态、Tooltip、校验提示和枚举文案; follow adjacent code instead of scattering hardcoded strings.
19. When backend fields come from EnumDict / I18nEnumDict or are shaped as { value, text }, load references/enum-rendering-rules.md: render text to users, use value for submit/filter/status logic, and never display [object Object] or duplicate backend enum copy maps.
20. Run quality, comment, and type checks with references/quality-and-type-rules.md before final output; if no comment is added, explicitly confirm that the touched frontend files contain no complex business rule, compatibility branch, hidden state linkage, race guard, or public contract that needs one.
21. Pair with $jetlinks-conventions whenever naming/import/i18n consistency or user-visible copy changes are involved, and with $jetlinks-delivery when commit or PR output is requested.

Required Constraints

• Do not invent component props, emits, hook signatures, or utils APIs that are not present in current workspace exports.
• When generating or substantially changing frontend code, actively add concise comments at key logic points such as business rules, compatibility conversion, hidden state linkage, race guards, and public composable/service/API contracts; do not wait for the user to ask again.
• Do not use the comment rule as permission to add noisy line-by-line comments; plain assignments, event forwarding, obvious computed values, and template rendering should stay uncommented.
• Do not duplicate existing jetlinks-web-core or @jetlinks-web abstractions with ad hoc local wrappers.
• Treat the current workspace jetlinks-web-core as the only first-class source for generic frontend components; jetlinks-project-ui-cli is only an optional external reference when the user explicitly asks for it, never a default dependency or import source.
• Do not repeat hand-written cards, lists, detail sections, icon selectors, drawers, tags, status chips, resource pickers, or dynamic editors inside business modules when jetlinks-web-core already provides a matching component or pattern.
• When existing components are not reused, state which jetlinks-web-core export, component implementation, and adjacent page were checked, plus the exact capability gap.
• Do not hardcode route auth buttons, menu metadata, API base behavior, or token handling when existing abstractions already cover them.
• Do not load every reference by default; choose only the files needed by the current scenario.
• Treat components/hooks/utils listed in references as candidates, not guaranteed facts; verify against current workspace exports before implementation.
• For pages with generic condition search, prefer ConditionFilter as the reusable search shell whenever the workspace already provides ConditionFilter plus route encode/decode utilities.
• For generic condition search fields such as date/time, range, boolean, option/reference, tree, nested path, or valueless conditions, prefer the field-driven generic value editor path provided by ConditionFilter field definitions and field-level hooks such as options, loadOptions, loadSelectedOptions, rename, routeAlias, and handleParamsItem; do not jump straight to a custom per-field component unless the generic path is proven insufficient in the current workspace.
• Only after the page is explicitly classified as a standard management page, and only when this is a narrow old-page patch, the user explicitly wants the old table style, or the search is a few fixed fields with no route echo / remote options / saved search needs, may you use ProSearch; the solution profile or implementation summary must record the exception reason. Adjacent pages using ProSearch is evidence to inspect, not a default for new pages.
• For backend enum fields shaped as { value, text } from EnumDict / I18nEnumDict, show text in tables, cards, details, tags, badges, and filter tokens; use value for request params, form models, comparisons, status color, and permissions. Do not render the object directly, do not submit { value, text } unless the API requires it, and do not duplicate backend enum text maps in frontend constants.
• Business goals come first and references come second; do not let a borrowed layout overrule the actual business task, user role, or decision path.
• Do not force every frontend requirement into a search-form + table + modal CRUD shell; first decide whether the business is better expressed as workspace, drill-down detail, timeline, dashboard, wizard, kanban, topology, or mixed interaction.
• Do not default to table plus full edit form; for object details, support summary, sectioned details, local editing, and related records when they fit the business.
• For lightweight fields such as name, tags, description, remark, or notes, prefer single-field editing via InputEditable, Editable, or FormItemEditable before opening a full edit dialog.
• For any single-object detail page (object detail workspace / master-detail workspace / runtime-edit toggle and their derivatives), the header summary zone must follow the catalog rule "反传统后台感硬约束 - 7. 详情页头部摘要区" and the matching section in references/component-reuse-patterns.md: name / description / remark are inline editable, tags are added/removed in place, status is switched via quick actions with a badge, ownership and meta info are read-only. Do not put an "编辑" button at the top that opens a form containing name / description / tags / status; do not move tag add/remove or basic-info edits into a separate edit dialog; keep the summary zone structure, field order, edit affordances, and quick-action position consistent across all detail pages.
• Across every module, the editing control, trigger, and save feedback for the same field type must be identical, per "反传统后台感硬约束 - 8. 编辑交互样式统一" in the catalog and the matching section in references/component-reuse-patterns.md. Use the fixed field-to-component map (name / description / remark → InputEditable / Editable / FormItemEditable; tags → ChipGroup / AppTag; status → j-badge-status + quick action; boolean → a-switch; enum → a-select / a-radio / a-checkbox; date → a-date-picker / a-range-picker; number → a-input-number; rich text / JSON / code → workspace shared editor; resource link → workspace shared resource picker; cross-field strong validation → EditDialog / JlDrawerShell / wizard). Use one trigger style site-wide (hover affordance → click inline), Enter to save / Esc to cancel / blur to save by default, near-field validation, toast feedback that carries the object name, and reserve secondary confirmation for destructive actions only. Do not let module A use chips for tags while module B uses a Select; do not let one page Enter-save while another only accepts button-click; do not build bespoke editable text / chip / inline form / validation bubble when jetlinks-web-core already exposes one.
• Functional introductions must help end users understand capability, enablement conditions, configuration impact, or next actions; do not render design notes, interaction principles, developer hints, or prototype labels.
• Before writing any user-visible copy (functional intro, description cards, guidance, empty/error/loading states, tooltips, button/tab/placeholder text, validation messages, popconfirms, dialog titles and descriptions, form field hints, submission feedback, help entries), first identify the concrete end-user role (operations, ops, platform admin, tenant admin, device admin, business admin, end consumer, integration partner, etc.), the goal action they came to perform, the terminology they actually understand, and their next step; if any one of these is unclear, ask the user before writing copy.
• Do not paste the user's raw requirement text, prompt, internal task description, requirement document wording, or developer story-card narrative directly into user-facing copy, intro cards, tooltips, empty states, help panels, or dialog descriptions; rewrite from the end-user's perspective with action-led, role-appropriate language.
• Do not expose developer-facing vocabulary in user-visible copy: no field keys, variable names, API paths, component names, topic names, command IDs, permission codes, internal schema names, "TODO", "待定", "占位文案", "待接接口", "这里以后接数据", "原型说明", "交互方式", "设计意图", or "本功能用于实现 / 我们将提供 / 这里展示用户希望的" style requirement-document phrasing.
• Empty/error/loading state copy must name the object and the next step (for example, "暂未接入设备，先创建一个产品再添加设备"); validation copy must give concrete limits and examples; success feedback must include the object name and the impact range when relevant.
• Do not duplicate the same functional intro across top banner, empty state, tooltip, and help entry; pick the closest carrier for each piece of information.
• Use Ant Design / Ant Design Vue and current workspace wrappers as the default visual and interaction language unless the user explicitly requires otherwise.
• When page shell or interaction solution still has multiple viable options, route the task through user-facing template selection first instead of silently defaulting to a traditional CRUD shell.
• When one recommendation is clearly supported and the user asked for implementation, do not block solely for template confirmation; record the assumed solution profile and continue.
• Solution profiling through ../jetlinks-web-style/SKILL.md is mandatory by default; only the local-tweak whitelist (single form field / single filter chip / single dialog content / styling-copy-props-only) may bypass it.
• Treat ../jetlinks-web-style/references/style-catalog.md (index) + ../jetlinks-web-style/references/style-catalog-templates.md + ../jetlinks-web-style/references/style-catalog-core.md + ../jetlinks-web-style/references/style-catalog-routing.md + ../jetlinks-web-style/references/style-catalog-core-base.md + ../jetlinks-web-style/references/style-catalog-core-detail-shell.md as the single source of truth for templates, ASCII skeletons, edit trigger gradient, density targets, and "不借鉴清单"; never invent template variants outside them.
• When presenting candidate templates, include each one's ASCII skeleton summary, core jetlinks-web-core component families to verify, edit trigger gradient, state/label anchor, and "不借鉴清单"; do not list only template names.
• Enforce the anti-admin-shell hard constraints from the catalog at implementation time: edit trigger gradient inline > sectional > drawer > modal > page; no default "4 KPI + top search + big table" stack; one main visual anchor per screen (primary CTA / key data band / real product status zone, pick one, do not stack); state before fields on lists and cards; no border-left: 3px solid / box-shadow: inset 4px 0 0 single-side colored bar as primary status signal; density targets per template; user-facing copy only; the edit dialog is not the only edit path.
• For object detail pages, follow ../jetlinks-web-style/references/style-catalog-core-detail-shell.md（详情页 10 条硬规则、AI 味自检、§7–§8、反向引用）与 references/component-reuse-patterns.md 场景矩阵： single-layer section cards, no sub-card nesting; section-header icon uses the unified primary/accent color, not a per-section decorative color; never turn non-metrics (categories, strings, zero values, relative time) into KPI boards; do not render fields whose value starts with "待配置" and hide the whole section when all its fields are filtered out; hero row carries at most 3 elements (name + status badge + 1 type chip); a single placeholder becomes a soft CTA at the section foot ("+ 补充 X →") rather than being silently dropped. Pass the 7-item "AI 味" self-check before output.
• Reverse references on asset detail pages (设备 / 产品 / 模型 / Skill / 大屏模板 / 规则 etc., "used by which agent / project / rule") must render as a main-area section with a count badge, populated by live reverse lookup, hidden entirely when empty; do not use a right-side sticky panel for reverse references.
• Sidebar active state follows the two-tier rule from the catalog: tier A (shallow nesting, 6-8 top-level links, e.g. application / developer centers) keeps the desaturated style (ink-1 + 500 weight, transparent background); tier B (deep nesting, 7+ modules × multi-level submenus with long-stay reuse, e.g. project workspace) uses the Linear-style left 2px accent bar + sunken background + accent icon. Within either tier, the implementation must stay consistent across modules.
• Sidebar collapsible parent-child groups must reuse a shared component (do not reimplement per place), following the 8-rule etiquette in the catalog (12px chevron-down caret at the weakest ink level, parent has no own active state but goes bold when a child is active, child region animates via CSS grid 0fr ↔ 1fr + min-height: 0; overflow: hidden, whole row clickable, persist-key to localStorage, ARIA wiring, child padding-left aligned to parent icon); collapsed icon-only sidebars must use v-if/v-else to switch between grouped and flat rendering, not nest the group component.
• Top-level tab root routes (workbench / application center / developer center / docs home etc.) do not render PageHead—the title is already expressed by the topbar nav active state, and rendering PageHead duplicates visual weight and squeezes content; non-root routes (detail pages / sub-routes) continue to render PageHead via the declarative API.
• Floating elements (FAB, floating panels, overlays) must use tokenized z-index (e.g. business modal 1000, custom drawer 1100, toast 1200, dev tools 9999); do not write raw z-index: 9999 / z-index: 1000. A page may host only one FAB at the default right-bottom anchor; additional floating elements stack via "same-anchor offset 56px left / 56px up".
• References should come from adjacent pages, same-domain modules, or similar business scenarios; borrow only what still matches the current business semantics, and do not transplant interaction flows from completely different domains.
• When pairing with $frontend-design, current workspace design tokens, Ant Design component language, typography, spacing scale, icon style, and motion rhythm override the skill’s default “bold aesthetic” guidance.
• Unless the user explicitly asks for a redesign, do not introduce a new brand palette, font system, page shell, or decorative style that conflicts with the current frontend framework.
• Prefer polishing existing interaction patterns such as search areas, operation bars, form grouping, cards, tabs, drawers, and loading/empty/error states instead of rebuilding the page into a self-styled showcase.
• Do not add decorative KPI cards, fake statistics, placeholder trend charts, or any data block that has no clear business meaning, action value, or source path just to make the page look full.
• If the source path, refresh trigger, or business use of a metric/chart is unclear, do not render it.
• Do not hardcode user-visible field display names, column titles, form labels, button text, tab names, placeholders, status copy, or validation messages directly in page code; use the current workspace i18n mechanism consistently, and use Chinese as the default or fallback text only when the local abstraction supports it.
• Wireframes, effect sketches, and design reasoning are alignment artifacts for developers and stakeholders; the final implemented UI must face end users and must not expose prototype labels, interaction explanations, design principles, or development notes on the page.
• If critical interaction decisions are under-specified, ask the user instead of guessing; if alignment is easier visually, show a wireframe or effect sketch first.
• If frontend changes cannot be fully verified in-session, state the exact pending quality or type-check commands and remaining UI risks.
• Before creating a new frontend component, hook, service, or util, search existing workspace capabilities first: @jetlinks-web-core/components, @jetlinks-web/components, @jetlinks-web-core/hooks, @jetlinks-web/hooks, @jetlinks-web-core/utils, @jetlinks-web/utils, and adjacent module components/**, hooks/**, utils/**, api/**, services/**.
• Reuse existing components/hooks/utils/services when they cover the need. If an existing capability covers most of the requirement through props, slots, config, or field schema, extend by configuration instead of creating a parallel implementation.
• Vue/JSX/TSX files over 300 lines are a blocking quality issue. Split into child components, hooks, services, or utils within the same task; do not treat decomposition as optional follow-up cleanup.
• Editing an existing file already over 300 lines is allowed only for narrow bug fixes. Feature work must first identify an extraction boundary and avoid making the large file larger.
• Extract by responsibility: repeated markup becomes a child component; state orchestration, watchers, and computed business state become hooks; API calls and request parameter assembly go to api/*.ts or service; reusable data transforms go to utils.
• Do not extract meaningless wrapper components just to reduce line count. A component must own a coherent UI responsibility. If props exceed 3, evaluate whether to pass a typed state object, use slots, move orchestration to a hook, or split responsibilities.
• UI components must stay side-effect-free: no direct API calls, no global state writes, no environment coupling, and no business orchestration hidden in render components.
• For frontend final output, report which reuse scopes were checked: same feature, same module, sibling/domain module, shared package, and public exports. If a new abstraction was created, state why none of those scopes provided a suitable capability.

Response Shape

1. Frontend task type and target module
2. Business goal, target users, and why this is or is not a standard CRUD page
3. Selected interaction template, confirmation mode, and which alternatives were rejected
4. Search-shell decision: ConditionFilter by default, or the explicit ProSearch exception reason
5. Enum rendering decision for backend EnumDict / I18nEnumDict fields when relevant
6. Which references were used, why they are business-relevant, and what was deliberately not borrowed
7. Current framework style anchors plus reused jetlinks-web-core components/hooks/utils/capabilities and key contracts
8. Any existing component not reused, with checked export/example and reason
9. If $frontend-design was used, which interaction or visual refinements stayed aligned with local style and Ant Design language
10. Whether a wireframe / effect sketch was provided or why it was unnecessary
11. Main code changes and compatibility risks
12. Verification evidence or pending commands, including UI interaction, state flow, route or permission behavior, type checks, created/modified Vue/JSX/TSX file line-count status, reuse scopes checked (same feature, same module, sibling/domain module, shared package, public exports), reused capabilities, and reasons for any new components/hooks/utils/services/API wrappers.