Cursor rule

1---
2description: 
3globs: Src/CodeSpirit.Web/wwwroot/amis-cards/*.js
4alwaysApply: false
5---
6# CodeSpirit Amis Cards V2.0 基本原则
7 
8## 概述
9 
10本文档定义了 CodeSpirit Amis Cards V2.0 项目的核心原则，确保开发过程保持一致性和高质量。
11 
12## 🎯 核心原则
13 
14### 1. 完全隔离原则
15 
16**原则描述**: 与现有 `cards-sdk` 完全隔离，确保两个系统可以长期并存。
17 
18**执行要求**:
19- ✅ 使用独立的命名空间 `AmisCards`
20- ✅ 所有文件路径使用 `/amis-cards/` 前缀
21- ✅ CSS类名使用 `amis-cards-` 前缀
22- ✅ 全局变量使用 `window.AmisCards` 命名空间
23- ✅ 不引用或依赖现有 `cards-sdk` 的任何文件
24- ❌ 禁止修改现有 `cards-sdk` 的任何代码
25- ❌ 禁止使用与 `cards-sdk` 相同的类名或变量名
26 
27### 2. 配置优先原则
28 
29**原则描述**: 优先使用配置化开发，减少手写代码，提高开发效率。
30 
31**执行要求**:
32- ✅ 所有卡片通过JSON配置定义
33- ✅ 页面布局通过Amis Page配置实现
34- ✅ 主题样式通过CSS变量配置
35- ❌ 禁止硬编码业务逻辑
36- ❌ 禁止在渲染器中写死样式值
37 
38### 3. 渐进增强原则
39 
40**原则描述**: 从基础功能开始，逐步增加高级功能，确保每个阶段都是可用的。
41 
42**执行要求**:
43- ✅ 优先实现核心卡片类型（统计卡片）
44- ✅ 确保基础功能完整可用后再添加高级功能
45- ✅ 每个功能模块独立可测试
46- ❌ 禁止一次性实现所有功能
47- ❌ 禁止跳过基础功能直接实现高级功能
48 
49**实施顺序**:
501. 核心SDK + 统计卡片
512. 图表卡片 + 信息卡片
523. 操作卡片 + 表单卡片
534. 插件系统 + 高级功能
54 
55### 4. 模块化架构原则
56 
57**原则描述**: 采用模块化设计，确保代码可维护、可扩展、可测试。
58 
59**执行要求**:
60- ✅ 每个卡片类型独立的渲染器文件
61- ✅ 样式按功能模块分离
62- ✅ 配置文件按业务域分组
63- ❌ 禁止模块间紧耦合
64- ❌ 禁止在一个文件中混合多个功能
65 
66### 5. 向后兼容原则
67 
68**原则描述**: 确保API和配置的向后兼容性，避免破坏性变更。
69 
70**执行要求**:
71- ✅ API接口保持稳定
72- ✅ 配置格式向后兼容
73- ✅ 提供版本迁移指南
74- ❌ 禁止直接删除已发布的API
75- ❌ 禁止修改已有配置的语义
76 
77## 🔧 技术原则
78 
79### 6. 性能优先原则
80 
81**原则描述**: 确保良好的性能表现，特别是在大数据量和移动端场景。
82 
83**执行要求**:
84- ✅ 初始化时间 < 500ms
85- ✅ 卡片渲染时间 < 300ms
86- ✅ 内存使用 < 50MB
87- ✅ 支持虚拟滚动和分页
88- ✅ 实现防抖和节流
89- ❌ 禁止内存泄漏
90- ❌ 禁止阻塞UI线程
91 
92### 7. 响应式设计原则
93 
94**原则描述**: 采用移动优先的响应式设计，确保在所有设备上都有良好体验。
95 
96**执行要求**:
97- ✅ 移动优先的CSS媒体查询
98- ✅ 流式网格布局系统
99- ✅ 触控友好的交互设计
100- ✅ 自适应的字体和间距
101- ✅ 支持横竖屏切换
102- ❌ 禁止固定像素尺寸
103- ❌ 禁止仅为桌面端优化
104 
105**响应式断点**:
106- `xs`: < 576px (手机)
107- `sm`: 576px - 768px (平板竖屏)
108- `md`: 768px - 992px (平板横屏)
109- `lg`: 992px - 1200px (桌面)
110- `xl`: ≥ 1200px (大屏桌面)
111 
112## 🎨 设计原则
113 
114### 8. 一致性原则
115 
116**原则描述**: 保持视觉和交互的一致性，提供统一的用户体验。
117 
118**执行要求**:
119- ✅ 统一的颜色系统和主题
120- ✅ 一致的组件行为和交互
121- ✅ 统一的图标和字体规范
122- ❌ 禁止随意偏离设计系统
123 
124### 9. 用户体验原则
125 
126**原则描述**: 以用户为中心，提供直观、高效的使用体验。
127 
128**执行要求**:
129- ✅ 统一的设计语言和视觉风格
130- ✅ 一致的交互模式和行为
131- ✅ 标准化的组件和样式
132- ✅ 统一的错误处理和反馈
133- ❌ 禁止不一致的视觉设计
134- ❌ 禁止相同功能的不同交互方式
135 
136**设计系统**:
137```css
138:root {
139    /* 统一的设计令牌 */
140    --amis-cards-primary: #007bff;
141    --amis-cards-border-radius: 6px;
142    --amis-cards-box-shadow: 0 2px 8px rgba(0,0,0,0.1);
143    --amis-cards-transition: all 0.3s ease;
144}
145```
146 
147### 10. 数据安全原则
148 
149**原则描述**: 确保数据传输和存储的安全性，防止安全漏洞。
150 
151**执行要求**:
152- ✅ 直观的界面布局和导航
153- ✅ 及时的反馈和状态提示
154- ✅ 合理的默认值和智能推荐
155- ✅ 流畅的动画和过渡效果
156- ✅ 容错性设计和错误恢复
157- ❌ 禁止复杂难懂的操作流程
158- ❌ 禁止无反馈的用户操作
159 
160**用户体验检查点**:
161- 新用户能否在5分钟内上手？
162- 常用操作是否在3次点击内完成？
163- 错误信息是否清晰可理解？
164- 加载状态是否有适当提示？
165 
166### 11. 权限控制原则
167 
168**原则描述**: 实现细粒度的权限控制，确保用户只能访问授权的功能。
169 
170**执行要求**:
171- ✅ 必须集成现有TokenManager认证系统
172- ✅ 支持基于角色的权限控制
173- ✅ 功能级和数据级权限验证
174- ❌ 禁止绕过权限检查
175 
176## 📋 质量原则
177 
178### 12. 代码质量原则
179 
180**原则描述**: 保持高质量的代码标准，确保可读性和可维护性。
181 
182**执行要求**:
183- ✅ 清晰的命名规范
184- ✅ 完整的代码注释
185- ✅ 合理的函数和类设计
186- ✅ 统一的代码风格
187- ❌ 禁止复杂的嵌套逻辑
188- ❌ 禁止重复代码
189 
190### 13. 测试覆盖原则
191 
192**原则描述**: 确保充分的测试覆盖，保证代码质量和功能稳定性。
193 
194**执行要求**:
195- ✅ 核心功能单元测试
196- ✅ 集成测试覆盖
197- ✅ 浏览器兼容性测试
198- ✅ 性能测试验证
199 
200## 📖 文档原则
201 
202### 14. 文档完整性原则
203 
204**原则描述**: 提供完整、准确、易懂的文档，降低使用和维护成本。
205 
206**执行要求**:
207- ✅ API接口文档完整
208- ✅ 配置选项说明详细
209- ✅ 示例代码可运行
210- ✅ 常见问题解答
211- ❌ 禁止过时的文档内容
212 
213**文档结构**:
214```
215docs/
216├── api.md              # API参考文档
217├── components.md       # 组件使用指南
218├── examples.md         # 完整示例
219├── troubleshooting.md  # 故障排除
220├── theming.md          # 主题定制
221└── migration.md        # 迁移指南
222```
223 
224### 15. 渐进式部署原则
225 
226**原则描述**: 采用渐进式部署策略，降低上线风险。
227 
228**执行要求**:
229- ✅ 分阶段功能发布
230- ✅ 灰度测试验证
231- ✅ 回滚方案准备
232- ❌ 禁止一次性大规模变更
233 
234### 16. 持续改进原则
235 
236**原则描述**: 基于用户反馈和性能监控，持续优化和改进系统。
237 
238**执行要求**:
239- ✅ 用户反馈收集机制
240- ✅ 性能监控和分析
241- ✅ 定期代码审查
242 
243- ✅ 技术债务管理