loom-react

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Link Loom React Development Skill

Link Loom React开发技能规范

This skill standardizes frontend development for Link Loom applications, enforcing consistency in styling, structure, and code quality.

本技能规范统一了Link Loom应用的前端开发标准，在样式、结构和代码质量上强制保持一致性。

1. Coding Standards

1. 编码规范

Flat-Style & Defensive Coding

扁平化风格与防御式编码

Guard Clauses: Check for null/undefined/error conditions early.
No Pyramid of Doom: Avoid deep nesting.
Hooks Rules: Respect hook dependencies and order.

Bad:

javascript

useEffect(() => {
  if (user) {
    if (user.isActive) {
      loadData();
    }
  }
}, [user]);

Good:

javascript

useEffect(() => {
  if (!user || !user.isActive) {
    return;
  }

  loadData();
}, [user]);

卫语句（Guard Clauses）：尽早检查null/undefined/错误状态。
避免嵌套地狱：不要使用深层嵌套代码。
Hooks规则：严格遵守Hooks的依赖项与调用顺序要求。

错误示例：

javascript

useEffect(() => {
  if (user) {
    if (user.isActive) {
      loadData();
    }
  }
}, [user]);

正确示例：

javascript

useEffect(() => {
  if (!user || !user.isActive) {
    return;
  }

  loadData();
}, [user]);

2. Naming Conventions

2. 命名约定

Strictly adhere to these naming conventions.

Type	Path Pattern	Naming Style	Example
Page	`src/pages/<Module>/<PageName>.page.jsx`	`PascalCase.jsx`	`src/pages/account/AccountProfile.page.jsx`
Component	`src/components/<Category>/<Name>/<Name>.component.jsx`	`PascalCase.jsx`	`src/components/shared/Navbar/Navbar.component.jsx`
Service	`src/services/<Module>/<SubModule>/<name>.service.js`	`[Domain][Entity]Service`	`IdentityUserManagementService`
Hook	`src/hooks/<name>.hook.jsx`	`useCamelCase.jsx`	`src/hooks/useAuth.hook.jsx`

必须严格遵循以下命名约定。

类型	路径模式	命名风格	示例
页面组件	`src/pages/<Module>/<PageName>.page.jsx`	`PascalCase.jsx`	`src/pages/account/AccountProfile.page.jsx`
通用组件	`src/components/<Category>/<Name>/<Name>.component.jsx`	`PascalCase.jsx`	`src/components/shared/Navbar/Navbar.component.jsx`
服务层	`src/services/<Module>/<SubModule>/<name>.service.js`	`[Domain][Entity]Service`	`IdentityUserManagementService`
自定义Hook	`src/hooks/<name>.hook.jsx`	`useCamelCase.jsx`	`src/hooks/useAuth.hook.jsx`

3. Directory Structure

3. 目录结构

Keep components modular.

text

src/
├── components/          # Reusable UI components
│   └── <Category>/      # e.g., shared, layout, forms
├── pages/               # Route-level components
│   └── <Module>/        # e.g., account, dashboard
├── services/            # API interaction logic
├── hooks/               # Custom hooks
└── layouts/             # Page layouts

保持组件的模块化设计。

text

src/
├── components/          # 可复用UI组件
│   └── <Category>/      # 例如：shared（通用）、layout（布局）、forms（表单）
├── pages/               # 路由级组件
│   └── <Module>/        # 例如：account（账户）、dashboard（仪表盘）
├── services/            # API交互逻辑
├── hooks/               # 自定义Hooks
└── layouts/             # 页面布局

4. Styling Guidelines

4. 样式指南

Primary Directive: Use Bootstrap 5 classes. Order of styling: Use it always:

Bootstrap 5 classes
Styled-components: Only if bootstrap do not have any implementation for the style you need.
Inline styles: Only if bootstrap and styled-components do not have any implementation for the style you need and if is strictly necessary.

Layout:

row

col-12

col-md-6

d-flex

justify-content-between

align-items-center

my-4

p-3

, and so on. Do not use MUI Grid.

Components: Primarily use MUI components or Link Loom SDK components. Only use custom components if MUI or Link Loom SDK do not have any implementation for the component you need.
Typography:
```
h1
```
,
```
p
```
,
```
text-muted
```
,
```
fw-bold
```
, and so on. Prevent usage of MUI Typography.
Avoid: Custom CSS for layout. Use custom classes only for specific design tokens (colors, branding) not covered by Bootstrap.
Icons: Use MUI icons and import them from
```
@mui/icons-material
```
as:

javascript

import { AccountCircle as AccountCircleIcon } from "@mui/icons-material";

核心要求：使用Bootstrap 5类。 样式优先级：必须按以下顺序使用：

Bootstrap 5 类
Styled-components：仅当Bootstrap没有你需要的样式实现时使用。
内联样式：仅当Bootstrap和Styled-components都没有对应的实现，且确实必要时使用。

布局：使用

row

、

col-12

、

col-md-6

、

d-flex

、

justify-content-between

、

align-items-center

、

my-4

、

p-3

等类。禁止使用MUI Grid。

组件：优先使用MUI组件或Link Loom SDK组件。仅当MUI或Link Loom SDK没有对应的组件实现时，才使用自定义组件。
排版：使用
```
h1
```
、
```
p
```
、
```
text-muted
```
、
```
fw-bold
```
等类。避免使用MUI Typography组件。
注意：不要为布局编写自定义CSS。仅在Bootstrap未覆盖的特定设计标记（颜色、品牌样式）时使用自定义类。
图标：使用MUI图标，并从
```
@mui/icons-material
```
导入，示例：

javascript

import { AccountCircle as AccountCircleIcon } from "@mui/icons-material";

5. Component Guidelines

5. 组件开发指南

Domain Driven Design (DDD) & Parity

领域驱动设计（DDD）与结构一致性

CRITICAL: Frontend structure MUST mirror the backend domain structure 1:1.

If backend is

workflow-orchestration/control-plane/flow-design/flow-definition

, frontend MUST be

src/components/pages/workflow-orchestration/control-plane/flow-design/flow-definition

Never disconnect a component from its domain.

关键要求：前端结构必须与后端领域结构1:1镜像对应。

如果后端结构是

workflow-orchestration/control-plane/flow-design/flow-definition

，前端结构必须为

src/components/pages/workflow-orchestration/control-plane/flow-design/flow-definition

。

绝对不能让组件脱离其所属的领域结构。

页面组件

Role: Orchestration ONLY. NO business logic.
Structure: Orchestrate
```
*Manager
```
or
```
*List
```
components.
Container: Always wrap content in
```
container-fluid my-4
```
.

职责：仅负责编排。禁止包含业务逻辑。
结构：编排
```
*Manager
```
或
```
*List
```
组件。
容器：必须始终用
```
container-fluid my-4
```
包裹内容。

Components

通用组件

Standard Set: Every feature typically needs:
- ```
manager/
```
  (Orchestrates View/Edit modes)
- ```
list/
```
  (Table/Grid view)
- ```
edit/
```
  (Form)
- ```
preview/
```
  (Read-only details)
- ```
quick-actions/
```
  (Optional)
Entry Point: Must implement
```
initializeComponent
```
function to load data.
Communication: Must implement
```
itemOnAction(action, entity)
```
for event handling (e.g.,
```
edit
```
,
```
delete
```
,
```
quick-view
```
).
Manager Pattern: The
```
*Manager
```
component controls state (
```
isEditMode
```
) to toggle between
```
Preview
```
and
```
Edit
```
.
Subcomponents: If a component (especially Manager) becomes complex, split it into
```
subcomponents/
```
folder to improve maintenance.
Shared Components: If a component is used in multiple places, move it to
```
src/components/shared
```
. These are candidates for the Link Loom SDK.
Navigation: MUST use Lazy Loading. No hard redirects. Use
```
useNavigate
```
and standard routing.

标准组件集：每个功能通常需要以下组件：
- ```
manager/
```
  （编排视图/编辑模式）
- ```
list/
```
  （表格/网格视图）
- ```
edit/
```
  （表单）
- ```
preview/
```
  （只读详情）
- ```
quick-actions/
```
  （可选）
入口函数：必须实现
```
initializeComponent
```
函数来加载数据。
事件处理：必须实现
```
itemOnAction(action, entity)
```
用于事件处理（例如
```
edit
```
、
```
delete
```
、
```
quick-view
```
）。
Manager模式：
```
*Manager
```
组件控制状态（
```
isEditMode
```
）来切换
```
Preview
```
和
```
Edit
```
模式。
子组件拆分：如果组件（尤其是Manager）过于复杂，将其拆分为
```
subcomponents/
```
文件夹以提升可维护性。
通用组件复用：如果组件在多个地方使用，将其移至
```
src/components/shared
```
目录。这类组件是Link Loom SDK的候选组件。
导航：必须使用懒加载。禁止硬跳转。使用
```
useNavigate
```
和标准路由。

Services

服务层

Base Class: MUST extend
```
BaseApi
```
from
```
@services/base/api.service
```
.
No Axios: NEVER use
```
axios
```
directly in components.

Adapters: Use

fetchEntityCollection

fetchMultipleEntities

createEntityRecord

updateEntityRecord

from

@services/utils/entityServiceAdapter

for data fetching in components.

javascript

// Example: initializeComponent with adapter
const initializeComponent = async () => {
  const [providers] = await fetchMultipleEntities([
    { service: MyService, payload: { queryselector: "all" } },
  ]);
  setEntities(providers?.result?.items || []);
};

基类要求：必须继承自
```
@services/base/api.service
```
中的
```
BaseApi
```
。
禁止直接使用Axios：绝对不能在组件中直接使用
```
axios
```
。

适配器使用：在组件中使用

@services/utils/entityServiceAdapter

中的

fetchEntityCollection

、

fetchMultipleEntities

、

createEntityRecord

、

updateEntityRecord

来获取数据。

javascript

// 示例：使用适配器实现initializeComponent
const initializeComponent = async () => {
  const [providers] = await fetchMultipleEntities([
    { service: MyService, payload: { queryselector: "all" } },
  ]);
  setEntities(providers?.result?.items || []);
};

6. General Best Practices

6. 通用最佳实践

Language: English ONLY for code and static text, unless explicitly requested otherwise by the user.
Documentation: Avoid excessive comments. Document only complex algorithms. Code should be self-documenting.
KISS Principle: keep it simple, stupid. Avoid overengineering. If a process is simple, keep the code simple.
Naming: Use semantic variable names. NEVER use single-letter names like
```
x
```
,
```
ac
```
,
```
t
```
. Names must indicate intent.
Clean Code: Remove unused imports, dependencies, and functions. No dead code.
Git: Use Conventional Commits if asked to generate commit messages.
Design Patterns: Act as an experienced architect. Use patterns (Factory, Singleton, Proxy, etc) only when necessary to solve a specific problem. Do not force patterns where simple logic suffices.
Context: Do not infer if unsure. Always ask the user for clarification if requirements are not clear. Challenge user requests that lead to "garbage code" or antipatterns.
Strictness: Since you are the expert, do not let the user start to write bad code patterns, warn him.
Linting: MANDATORY. Code must be written adhering to the project's linter configuration (e.g.,
```
.prettierrc
```
,
```
.eslintrc.js
```
).

语言要求：代码和静态文本必须全部使用英文，除非用户明确要求使用其他语言。
文档规范：避免过多注释。仅对复杂算法添加注释。代码应具备自解释性。
KISS原则：保持简单。避免过度设计。如果流程简单，代码也应保持简洁。
命名规范：使用语义化变量名。绝对不能使用单字母名称如
```
x
```
、
```
ac
```
、
```
t
```
。名称必须能表达其用途。
代码整洁：移除未使用的导入、依赖和函数。禁止存在死代码。
Git提交：如果需要生成提交信息，使用Conventional Commits规范。
设计模式：以资深架构师的视角行事。仅在需要解决特定问题时使用设计模式（工厂、单例、代理等）。不要在简单逻辑中强行使用模式。
需求确认：如果不确定，不要自行推断。如果需求不明确，务必向用户确认。对会导致“垃圾代码”或反模式的用户请求提出质疑。
严格性：作为专家，不要让用户养成编写不良代码模式的习惯，要及时警告。
代码检查：必须强制执行。代码必须符合项目的检查器配置（例如
```
.prettierrc
```
、
```
.eslintrc.js
```
）。

7. Resources & Documentation

7. 资源与文档

CRITICAL: Do not reinvent UI components. Check the Link Loom React SDK first.

Component Index:

link-loom/github/link-loom-react-sdk/src/index.js

Contains exports for
```
Alert
```
,
```
DataGrid
```
,
```
TextEditor
```
,
```
OnPageLoaded
```
, etc.

Component Source:

link-loom/github/link-loom-react-sdk/src/components/

Use

view_file

on the index to see available components before creating new ones.

关键提示：不要重复造轮子。先查看Link Loom React SDK。

组件索引：

link-loom/github/link-loom-react-sdk/src/index.js

包含
```
Alert
```
、
```
DataGrid
```
、
```
TextEditor
```
、
```
OnPageLoaded
```
等组件的导出。

组件源码：

link-loom/github/link-loom-react-sdk/src/components/

在创建新组件前，先查看索引文件中的可用组件。

8. Examples

8. 示例

Page Component

页面组件

See

assets/page.jsx

查看

assets/page.jsx

。

Manager Component

Manager组件

See

assets/manager.jsx

查看

assets/manager.jsx

。

Component Implementation

组件实现

See

assets/component.jsx

查看

assets/component.jsx

。

Service Wrapper

服务层封装

See

assets/service.js

查看

assets/service.js

。

9. Edge Cases

9. 边缘情况

Mobile Responsiveness: Always test layout with
```
col-12
```
for mobile and
```
col-md-*
```
for desktop.
Missing Aliases: If
```
@components
```
or
```
@services
```
fail, check
```
vite.config.js
```
. Use relative paths temporarily if aliases are broken, but flag for fix. Do not import directly from
```
src
```
except if it is a subcomponent of the current component.
Async Errors: Always wrap async operations in
```
try-catch
```
inside
```
useEffect
```
or event handlers to prevent unhandled promise rejections.

移动端响应式：务必测试移动端
```
col-12
```
和桌面端
```
col-md-*
```
的布局效果。
别名失效：如果
```
@components
```
或
```
@services
```
别名失效，检查
```
vite.config.js
```
。如果别名损坏，可以临时使用相对路径，但要标记需要修复。除非是当前组件的子组件，否则不要直接从
```
src
```
导入。
异步错误处理：在
```
useEffect
```
或事件处理函数中，必须将异步操作包裹在
```
try-catch
```
中，以防止未处理的Promise拒绝错误。

loom-react

Original

Translation

Link Loom React Development Skill

Link Loom React开发技能规范

Table of Contents

目录

1. Coding Standards

1. 编码规范

Flat-Style & Defensive Coding

扁平化风格与防御式编码

2. Naming Conventions

2. 命名约定

3. Directory Structure

3. 目录结构

4. Styling Guidelines

4. 样式指南

5. Component Guidelines

5. 组件开发指南

Domain Driven Design (DDD) & Parity

领域驱动设计（DDD）与结构一致性

Pages

页面组件

Components

通用组件

Services

服务层

6. General Best Practices

6. 通用最佳实践

7. Resources & Documentation

7. 资源与文档

8. Examples

8. 示例

Page Component

页面组件

Manager Component

Manager组件

Component Implementation

组件实现

Service Wrapper

服务层封装

9. Edge Cases

9. 边缘情况