知识库文档，部分组件文档内容调整，部分文档优化文案

Tevin

2025-03-20 b1e987944d36275906373fcd24705f37e1909f11

知识库文档，部分组件文档内容调整，部分文档优化文案

 _cursor.ai/plugins.doc/echarts.doc/CECharts.doc.md

@@ -1,61 +1,32 @@
# ECharts图表组件
# CECharts 图表组件

## 组件名称
## 功能说明

`CECharts` - 用于在小程序环境中渲染ECharts图表的组件
该组件是对百度ECharts的封装，用于在小程序环境中渲染各类图表，支持触摸交互和数据更新。支持柱状图、折线图、饼图等各种ECharts支持的图表类型，组件内部已优化tooltip显示和触摸事件处理。

## 组件说明

该组件是对百度ECharts的封装，用于在小程序环境中渲染各类图表，支持触摸交互和数据更新。支持柱状图、折线图、饼图等各种ECharts支持的图表类型。

## 使用方法

```html
<CECharts
  :canvasId="'chart-' + Math.random()"
  :onReady="handleChartReady"
/>
```
## 引用方式

```js
// 图表初始化回调
handleChartReady(chart) {
  chart.setOption({
    title: {
      text: '销售统计'
    },
    tooltip: {},
    xAxis: {
      data: ['1月', '2月', '3月', '4月', '5月', '6月']
    },
    yAxis: {},
    series: [{
      name: '销量',
      type: 'bar',
      data: [5, 20, 36, 10, 10, 20]
    }]
  });
}
import { CECharts } from '@components/plugins/echarts';
```

## 属性说明
## 组件参数

| 属性名       | 类型     | 默认值   | 说明                                    |
| ------------ | -------- | -------- | --------------------------------------- |
| canvasId     | String   | 随机生成 | 画布ID，用于标识图表实例                |
| disableTouch | Boolean  | false    | 是否禁用触摸交互                        |
| onReady      | Function | -        | 图表准备就绪的回调函数，参数为chart实例 |
- `canvasId` (String，默认值：随机生成)：画布ID，用于标识图表实例
- `disableTouch` (Boolean，默认值：false)：是否禁用触摸交互
- `onReady` (Function，可选)：图表准备就绪的回调函数
  - 参数：`chart` (Object) ECharts实例对象，可通过此对象设置图表配置和数据

## 方法说明
## 实例方法

组件内部对外暴露的方法：

| 方法名               | 参数     | 说明                   |
| -------------------- | -------- | ---------------------- |
| init                 | callback | 初始化图表方法         |
| canvasToTempFilePath | opt      | 将图表转为临时文件路径 |
- `init`：初始化图表方法
  - `callback` (Function，必填)：初始化完成的回调函数，参数为 `(canvas, width, height, dpr)`
- `canvasToTempFilePath`：将图表转为临时文件路径
  - `opt` (Object，必填)：微信小程序 canvasToTempFilePath 的参数对象

## 使用示例

### 基础用法

```html
<template>
@@ -139,18 +110,29 @@
</script>
```

## 默认配置说明
### 保存图表为图片

组件已经内置了一些默认配置：

1. 禁用了渐进式渲染（progressive: 0）
2. 配置了默认的 tooltip 样式
3. 优化了 tooltip 的定位逻辑
```js
// 保存图表为图片
saveChartAsImage() {
  const _this = this;
  this.$refs.salesChart.canvasToTempFilePath({
    success(res) {
      console.log('保存成功:', res.tempFilePath);
      // 可以进一步使用 wx.saveImageToPhotosAlbum 保存到相册
    },
    fail(err) {
      console.error('保存失败:', err);
    }
  });
}
```

## 注意事项

1. 该组件暂时仅适用于小程序环境，文件名为 `CECharts.weapp.vue`
2. 在小程序端使用需要确保 canvas 的 type 属性设置为 "2d"
3. 小程序对 canvas 的性能有一定限制，复杂图表可能会有性能问题
4. 组件自动会处理触摸事件，支持图表交互
5. 如需保存图表为图片，可使用 canvasToTempFilePath 方法 
- 该组件暂时仅适用于小程序环境，文件名为 `CECharts.weapp.vue`
- 在小程序端使用需要确保 canvas 的 type 属性设置为 "2d"
- 小程序对 canvas 的性能有一定限制，复杂图表可能会有性能问题
- 组件自动会处理触摸事件，支持图表交互
- 组件已禁用了渐进式渲染（progressive: 0）以提高兼容性
- 组件内置了默认的 tooltip 样式和位置优化逻辑 

 _cursor.ai/plugins.doc/filter.doc/CFilter.doc.md

@@ -1,98 +1,37 @@
# 筛选组件
# CFilter 筛选组件

## 组件名称

`CFilter` - 用于页面筛选条件的组件

## 组件说明
## 功能说明

该组件用于实现页面筛选功能，包含顶部筛选条和展开的更多筛选抽屉，支持多种筛选控件类型，包括选择器、日期范围、单选和输入框等。

## 使用方法

```html
<CFilter
  :filterData="filterData"
  :bar="barConfig"
  :items="itemsConfig"
  :selectOptions="selectOptions"
  :onChange="handleFilterChange"
/>
```

## 属性说明

| 属性名        | 类型     | 默认值 | 说明                   |
| ------------- | -------- | ------ | ---------------------- |
| filterData    | Object   | {}     | 筛选数据对象           |
| bar           | Object   | {}     | 筛选横条项目配置       |
| items         | Array    | []     | 筛选展开层项目列表配置 |
| selectOptions | Object   | {}     | 各个项目的选项列表     |
| onChange      | Function | -      | 筛选变化时的回调函数   |

## 子组件说明

CFilter组件包含以下子组件：

1. `CFilterSelect` - 下拉选择组件
2. `CFilterDateRange` - 日期范围选择组件
3. `CFilterRadio` - 单选组件
4. `CFilterInput` - 输入框组件

## 配置项说明

### bar 配置项

顶部筛选条配置，支持类型：
## 引用方式

```js
{
  type: 'select', // 类型：select/dateRange/input
  label: '状态', // 显示的标签
  name: 'status', // 字段名称
  cancelable: true // 是否可取消选择
}
import { CFilter } from '@components/plugins/filter';
```

### items 配置项
## 组件参数

更多筛选项配置数组：
- `filterData` (Object，默认值：{})：筛选数据对象
- `bar` (Object，默认值：{})：筛选横条项目配置
  - `type` (String)：控件类型，可选值有 'select'、'dateRange'、'input'
  - `label` (String)：显示的标签
  - `name` (String)：字段名称
  - `cancelable` (Boolean)：是否可取消选择，仅对select类型有效
- `items` (Array，默认值：[])：筛选展开层项目列表配置
  - 每项格式同bar，但type可选值多一个'radio'
- `selectOptions` (Object，默认值：{})：各个项目的选项列表
  - 格式为 `{ 字段名: [{label: '显示文本', value: '值'}] }`
- `onChange` (Function，必填)：筛选变化时的回调函数
  - 参数：`filterData` (Object) 变更后的筛选数据对象

```js
[
  {
    type: 'select', // 类型：select/dateRange/radio/input
    label: '会员类型', // 显示的标签
    name: 'memberType', // 字段名称
  },
  {
    type: 'dateRange',
    label: '日期范围',
    name: 'dateRange'
  }
]
```
## 实例方法

### selectOptions 配置项

选项数据配置：

```js
{
  status: [
    { label: '全部', value: '' },
    { label: '正常', value: 1 },
    { label: '停用', value: 0 }
  ],
  memberType: [
    { label: '全部', value: '' },
    { label: '普通会员', value: 'normal' },
    { label: 'VIP会员', value: 'vip' }
  ]
}
```
组件没有对外暴露的实例方法

## 使用示例

### 基础用法

```html
<template>
@@ -187,7 +126,7 @@

## 注意事项

1. 筛选条（bar）只能配置一个筛选项
2. 抽屉式筛选（items）可以配置多个筛选项
3. 每个筛选项的类型（type）必须与组件类型匹配
4. select和radio类型的选项必须在selectOptions中配置对应的选项数据 
- 筛选条（bar）只能配置一个筛选项
- 抽屉式筛选（items）可以配置多个筛选项
- 每个筛选项的类型（type）必须与组件类型匹配
- select和radio类型的选项必须在selectOptions中配置对应的选项数据 

 _cursor.ai/plugins.doc/infiniteScroll.doc/CInfiniteScroll.doc.md

@@ -1,69 +1,34 @@
# 无限滚动组件
# CInfiniteScroll 无限滚动组件

## 组件名称
## 功能说明

`CInfiniteScroll` - 用于实现下拉刷新和上拉加载更多功能的滚动容器组件
该组件实现了移动端常见的下拉刷新和上拉加载更多功能，支持自动加载第一页和手动触发加载，适用于列表展示场景。内置了加载状态、空数据状态和加载完成状态的显示，使用简单便捷。

## 组件说明

该组件实现了移动端常见的下拉刷新和上拉加载更多功能，支持自动加载第一页和手动触发加载，适用于列表展示场景。

## 使用方法

```html
<CInfiniteScroll
  :autoInit="true"
  :onLoadMore="handleLoadMore"
>
  <!-- 内容插槽 -->
  <view v-for="(item, index) in list" :key="index">
    {{ item.name }}
  </view>
</CInfiniteScroll>
```
## 引用方式

```js
// 数据加载方法
handleLoadMore({ current, next, success, fail }) {
  // 请求后端数据
  $fetch.getList({ page: next }).then(res => {
    // 加载成功
    success({
      pageTotal: res.pageTotal, // 总页数
    });
  }).catch(() => {
    // 加载失败
    fail();
  });
}
import { CInfiniteScroll } from '@components/plugins/infiniteScroll';
```

## 属性说明
## 组件参数

| 属性名     | 类型     | 默认值 | 说明                             |
| ---------- | -------- | ------ | -------------------------------- |
| autoInit   | Boolean  | false  | 是否自动初始化（自动加载第一页） |
| onLoadMore | Function | -      | 发起加载页面数据的回调函数       |
- `autoInit` (Boolean，默认值：false)：是否自动初始化（自动加载第一页）
- `onLoadMore` (Function，必填)：发起加载页面数据的回调函数
  - `current` (Number)：当前页页码
  - `next` (Number)：需要加载的页面页码
  - `success` (Function)：当加载成功后调用
    - 参数：`{ pageTotal: Number }` 总页数
  - `fail` (Function)：加载失败后调用

## 方法说明
## 实例方法

| 方法名      | 参数      | 说明                                        |
| ----------- | --------- | ------------------------------------------- |
| $initScroll | -         | 初始化加载第一页数据                        |
| $refresh    | autoStart | 重置并刷新数据，参数为 'off' 时不会自动加载 |

## 回调参数说明

`onLoadMore` 回调函数参数：

| 参数名  | 类型     | 说明                                           |
| ------- | -------- | ---------------------------------------------- |
| current | Number   | 当前页页码                                     |
| next    | Number   | 需要加载的页面页码                             |
| success | Function | 当加载成功后调用，参数 `{ pageTotal: 总页数 }` |
| fail    | Function | 加载失败后调用                                 |
- `$initScroll`：初始化加载第一页数据
- `$refresh`：重置并刷新数据
  - `autoStart` (String，可选)：当值为 'off' 时不会自动加载，其他值或不传时会立即加载

## 使用示例

### 基础用法

```html
<template>
@@ -120,6 +85,7 @@

## 注意事项

1. 组件通过检测滚动位置自动触发加载更多功能
2. 下拉刷新功能仅在滚动到顶部时可用
3. 加载状态会自动管理，包括"加载中"和"没有更多了"等提示 
- 组件通过检测滚动位置自动触发加载更多功能
- 下拉刷新功能仅在滚动到顶部时可用
- 加载状态会自动管理，包括"加载中"、"没有更多了"和"暂无数据"等提示
- 组件内部对 H5 和小程序环境做了适配，在不同平台上使用相同的 API 即可 

 _cursor.ai/plugins.doc/qrcode.doc/CQRCode.doc.md

@@ -1,53 +1,76 @@
# 二维码组件
# CQRCode 二维码组件

## 组件名称
## 功能说明

`CQRCode` - 用于生成和展示二维码的组件
该组件用于在页面中生成二维码，支持在H5环境下保存二维码图片到本地，界面简洁直观。

## 组件说明
## 引用方式

该组件用于在页面中生成二维码，支持在H5环境下保存二维码图片。

## 使用方法

```html
<CQRCode 
  content="https://example.com" 
  :size="200" 
  :margin="2"
  :downloadable="true"
/>
```js
import { CQRCode } from '@components/plugins/qrcode';
```

## 属性说明
## 组件参数

| 属性名       | 类型    | 默认值                | 说明                      |
| ------------ | ------- | --------------------- | ------------------------- |
| content      | String  | 'http://www.aisim.cn' | 二维码内容，通常为URL地址 |
| size         | Number  | 200                   | 二维码尺寸，单位为像素    |
| margin       | Number  | 2                     | 二维码边距大小            |
| downloadable | Boolean | false                 | 是否显示"保存到手机"按钮  |
- `content` (String，默认值：'http://www.aisim.cn')：二维码内容，通常为URL地址
- `size` (Number，默认值：200)：二维码尺寸，单位为像素
- `margin` (Number，默认值：2)：二维码边距大小
- `downloadable` (Boolean，默认值：false)：是否显示"保存到手机"按钮

## 方法说明
## 实例方法

组件无对外暴露的方法
组件没有对外暴露的实例方法

## 使用示例

```html
<!-- 简单用法 -->
<CQRCode content="https://www.example.com" />
### 基础用法

<!-- 带保存按钮的用法 -->
<CQRCode 
  content="https://www.example.com" 
  :size="300"
  :margin="4"
  :downloadable="true"
/>
```html
<template>
  <view class="page">
    <!-- 简单用法 -->
    <CQRCode content="https://www.example.com" />
  </view>
</template>

<script>
import { CQRCode } from '@components/plugins/qrcode';

export default {
  components: {
    CQRCode
  }
}
</script>
```

### 带保存按钮的用法

```html
<template>
  <view class="page">
    <CQRCode 
      content="https://www.example.com" 
      :size="300"
      :margin="4"
      :downloadable="true"
    />
  </view>
</template>

<script>
import { CQRCode } from '@components/plugins/qrcode';

export default {
  components: {
    CQRCode
  }
}
</script>
```

## 注意事项

1. 目前在H5环境中支持保存二维码图片到本地
2. 小程序环境下的保存功能尚未实现 
- 目前在H5环境中支持保存二维码图片到本地
- 小程序环境下的保存功能尚未实现
- 二维码内容变更时会自动重新渲染 

 _cursor.ai/prompts/更新公共组件文档.prompts.md

@@ -33,15 +33,29 @@

## 第三步，如果文档不存在，创建

依照位置与命名规律，创建对应的 markdown 文档文件

每份组件文档包含：功能说明、引用方式、组件参数、示例方法、使用示例、注意事项
- 组件参数请使用列表形式，例如：- `paramName` (String，可选)：参数说明
- 组件参数如果是可枚举的几个具体值，请以二级列表的形式说明，例如：- `enumValue`：枚举值说明
- 实例方法是指 methods 中，名称以 `$` 符号开头的方法，没有可省略
- 提供使用示例时，如果组件有多种使用模式，请分别提供不同模式的示例
- 如果组件有特殊的技术点或使用场景，请在注意事项中说明
依照位置与命名规律，按照文档格式创建对应的组件文档

## 第四步，如果文档已存在，更新文档

读取文档内容，对比组件与文档，判断文档是否需要修剪已有内容和增加新内容，如果有，更新文档
读取文档内容，将组件功能与文档对比
- 判断文档是否符合文档格式的要求，如果不符合，请按格式修改
- 判断是否需要修剪已有内容和增加新内容，如果有，更新文档

## 文档格式

文档格式为markdown，每份组件需要包含一下项目：
- 由组件文件名+组件中文名组成大标题
- 功能说明
- 引用方式
- 组件参数
    - 请使用列表形式，例如：- `paramName` (String，可选)：参数说明
    - 如果是可枚举的几个具体值，请以二级列表的形式说明每个值，例如：- `enumValue`：枚举值说明
    - 如果是回调函数，请以二级列表的形式说明函数的参数和返回值，例如：- 参数 `paramName` (String，可选)：参数说明
- 实例方法
    - 是指 methods 中，名称仅以 `$` 符号开头的方法，没有 `$` 可省略
    - 如果方法有参数，请以二级列表形式说明方法的参数和返回值，例如：- 参数 `paramName` (String，可选)：参数说明
- 使用示例
    - 如果组件有多种使用模式，请分别提供不同模式的示例
- 注意事项
    - 重要或需要注意的问题
    - 特殊的技术点或使用场景

 _cursor.ai/工作共识.md

@@ -2,7 +2,7 @@

尽管我们来自五湖四海，有着各自不同的编码习惯，但现在我们聚集在一起组成了一个团队。为了使团队合作更加流畅，减少沟通成本和内耗，我们需要在以下几个方面达成共识。

## 1 代码首先是给人读的，其次才是给机器运行
## 1. 代码首先是给人读的，其次才是给机器运行

团队开发与个人开发最大的区别在于：你身处一个团队中，大家需要相互配合。因此，**让代码容易阅读是你应尽的责任**。

@@ -23,7 +23,7 @@
1. 做无关模块开发时可以快速跳过不相关代码
2. 做相关模块开发时一眼就能确定要查看的代码

同时，让实体名词承担功能表述的作用，能让代码维护更依赖阅读而不是记忆，极大减轻记忆负担。
同时，让实体名词承担功能表述的作用，能让代码维护更依赖阅读而不是记忆，**极大减轻记忆负担**

### 1.2 设计良好的模块与分层结构

@@ -51,29 +51,30 @@

这不仅减少了代码冗余，还提高了开发效率和代码质量

## 2 思考先行，开发随后
## 2. 思考先行，开发随后

### 2.1 理解清楚需求再动手

由于我们的需求文档通常由老板和总监编写，没有专职人员完善需求细节，因此某些需求描述可能比较模糊  
这种情况下，如果对业务理解不深，很容易导致开发的功能与实际需求不一致，最终需要重做
这种情况下，如果对业务理解不深，很容易导致开发的功能与实际需求不一致，最终导致需要推倒重来

因此，我们需要在开发过程中不断积累对业务的理解，至少要达到能发现需求歧义的程度  

有歧义是正常的——老板和总监对业务太熟悉了，往往会自然而然地认为某些理解是理所当然的；  
而对业务不熟悉的人，从需求文字字面出发，确实可能产生不同理解
有歧义是正常的，老板和总监对业务太熟悉了，往往会自然而然地认为某些理解是理所当然的    
而对业务不熟悉的人，从需求文字字面出发，从而可能产生不同理解

发现歧义时，请及时咨询我或旭诚，问清楚具体要求，一定要完全理解需求后再开始开发

### 2.2 设计清晰方案再动手

除了业务需求，在开发前我还应该梳理清楚技术形式、模块拆分和实现方式，以最简洁的方案实现需求，切忌盲目开工，为求速度而书写毫无章法的代码
除了业务需求，在开发前还应该梳理清楚技术形式、模块拆分和实现方式，以最简洁的方案实现需求  
切忌盲目开工，为求速度而书写毫无章法的代码

如果不重视工程质量，因为前端代码过于灵活，一段时间后代码混乱到无法维护了，就被迫需要重构，我们应该避免这样的事情发生
如果不重视工程质量，因为前端代码过于灵活，一段时间后代码混乱到无法维护了，就被迫需要重构，我们应该避免这种事情发生

只关注结果产量而不重视工程质量，这种代码是会被要求返工重写的
只关注结果产量而不重视工程质量，这种代码在代码审查中一旦发现，就会被要求返工重写

## 3 用户体验是工作的一部分
## 3. 用户体验是工作的一部分

用户体验是我们前端开发者需要主动思考的问题，这是我们工作的重要组成部分


 _cursor.ai/文档说明.md

@@ -1,10 +1,10 @@
# 文件夹介绍

## rules 文件夹
## 1. rules 文件夹

rules 是指 AI 根据一定条件自动读取的工作环境设定，是我们控制项目代码生成质量的重要手段

### 规则类型：全局使用 `Always` 
### 1.1 规则类型：全局使用 `Always` 

所有的聊天（Agent、Ask、Edit）和 ctrl+k 编辑，都会参考此规则生成代码

@@ -12,7 +12,7 @@
- [项目介绍](/src/components/_cursor.ai/rules/all-project-info.mdc)
- [开发规范](/src/components/_cursor.ai/rules/all-dev-specification.mdc)

### 规则类型：按路径匹配 `Auto-Attached`
### 1.2 规则类型：按路径匹配 `Auto-Attached`

当文件名称或路径匹配上时，会参考此规则生成代码

@@ -21,7 +21,7 @@
- [界面](/src/components/_cursor.ai/rules/type-surface.mdc)
- [子组件&公共组件](/src/components/_cursor.ai/rules/type-component.mdc)

### 规则类型：自主决定 `Agent-Requested`
### 1.3 规则类型：自主决定 `Agent-Requested`

在 Agent 模式下，由 AI 根据 Description 的文字描述，自主决定是否需要参考此规则生成代码  
非 Agent 模式需要我们自己 @ 此规则才能生效
@@ -30,12 +30,12 @@
- [数据控制器基类](/src/components/_cursor.ai/rules/fit-base-pilot.mdc)
- 表单验证规则

## prompts 文件夹
## 2. prompts 文件夹

prompts 存放我们主动提出的指令  
和我们在聊天窗口要求 ai 完成工作一样，就是对需要经常执行的有具体要求的操作，存下来方便反复使用

## 文档文件夹
## 3. 文档文件夹

公共组件库组件对应的文档


 _cursor.ai/组件目录.md

@@ -0,0 +1,10 @@
# 公共组件目录

这是移动端平台的公共组件目录

## 表单类组件


## 排版类组件

## 复杂插件类组件