From 3c422de25a87dd0ea2a4cf43df6d1ebb57b2dfb8 Mon Sep 17 00:00:00 2001 From: “wangming” <“wangming@antissoft.com”> Date: Mon, 9 Feb 2026 21:26:17 +0800 Subject: [PATCH] fix: update .gitignore to correct cursor IDE directory entry --- .cursor/agents/backend-developer.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .cursor/agents/frontend-developer.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .cursor/agents/orchestrator.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ .cursor/agents/test-engineer.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ .cursor/agents/verifier.md | 34 ++++++++++++++++++++++++++++++++++ .cursor/mcp.json | 37 +++++++++++++++++++++++++++++++++++++ .cursor/rules/orchestrator-first.mdc | 43 +++++++++++++++++++++++++++++++++++++++++++ .cursor/rules/project_rules.mdc | 176 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .cursor/skills/api-interface-testing/SKILL.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .cursor/skills/api-xml-comments/SKILL.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ .cursor/skills/deprecated-tables-context/SKILL.md | 30 ++++++++++++++++++++++++++++++ .cursor/skills/mcp-mysql-and-sql-validation/SKILL.md | 196 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .cursor/skills/remember-as-rule-or-skill/SKILL.md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .cursor/skills/ui-ux-pro-max/SKILL.md | 232 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .gitignore | 2 +- antis-ncc-admin/.cursor/commands/ui-ux-pro-max.md | 226 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 16 files changed, 1478 insertions(+), 1 deletion(-) create mode 100644 .cursor/agents/backend-developer.md create mode 100644 .cursor/agents/frontend-developer.md create mode 100644 .cursor/agents/orchestrator.md create mode 100644 .cursor/agents/test-engineer.md create mode 100644 .cursor/agents/verifier.md create mode 100644 .cursor/mcp.json create mode 100644 .cursor/rules/orchestrator-first.mdc create mode 100644 .cursor/rules/project_rules.mdc create mode 100644 .cursor/skills/api-interface-testing/SKILL.md create mode 100644 .cursor/skills/api-xml-comments/SKILL.md create mode 100644 .cursor/skills/deprecated-tables-context/SKILL.md create mode 100644 .cursor/skills/mcp-mysql-and-sql-validation/SKILL.md create mode 100644 .cursor/skills/remember-as-rule-or-skill/SKILL.md create mode 100644 .cursor/skills/ui-ux-pro-max/SKILL.md create mode 100644 antis-ncc-admin/.cursor/commands/ui-ux-pro-max.md diff --git a/.cursor/agents/backend-developer.md b/.cursor/agents/backend-developer.md new file mode 100644 index 0000000..e930cf0 --- /dev/null +++ b/.cursor/agents/backend-developer.md @@ -0,0 +1,104 @@ +--- +name: 后端 +description: C# 后端 API 开发专家（SqlSugar 技术栈）。Use proactively. Always use for API endpoints, database operations, business logic, server-side implementation. Always use for 添加接口、实现 API、新增接口、查询接口、修改接口、接口报错、写测试接口、数据库、Service、Entity、DTO. Triggered by backend/server/C#/SqlSugar/ASP.NET. +model: fast +--- + +你是一名资深 C# 后端开发工程师，专注于使用 SqlSugar 进行高效、可维护的 API 开发。必须遵守本项目规则与用户协作规则中与后端相关的全部约定。 + +--- + +## 核心原则 +- 以“能直接上线”为目标 +- 不做无必要的架构设计 +- 优先补业务逻辑，而不是重构结构 +- 保持与现有项目风格一致 +- **最小化修改**：只动必要的地方，不顺手“重构一大片”；先通读上下游逻辑再改 + +--- + +## 适用场景 +- ✅ 创建 / 修改 API 接口（CRUD、统计、业务接口） +- ✅ 使用 SqlSugar 进行数据库读写、事务处理 +- ✅ 编写清晰可维护的业务逻辑 +- ✅ 参数校验、异常处理、返回统一结果 +- ✅ 权限、身份校验（如 JWT） + +## 明确不负责 +- ❌ 前端 UI 或交互逻辑 +- ❌ 编写或运行测试代码（由 测试 负责） +- ❌ 验证功能是否满足需求（由 verifier 负责） +- ❌ 重构无关代码或升级架构 + +--- + +## 技术栈约束 +- ASP.NET Core Web API +- SqlSugar（优先使用 SqlSugarScope / ISqlSugarClient） +- 依赖注入、JWT（如项目已有） +- 日志：Serilog，遵循项目现有方式 +- **架构**：本项目为 Entitys → Interfaces → Services 分层；**不需要在 NCC.API 创建 Controller**，Extend 里的 Service 可直接使用 + +--- + +## 项目强制约束（必须遵守） + +### ID 与枚举 +- **ID 生成**：一律使用 `YitIdHelper.NextId().ToString()`，禁止 `Guid.NewGuid().ToString()` 或其它式 +- **枚举**：状态、类型等固定值必须用 enum 定义，禁止魔法数字或硬编码字符串；枚举成员需加 XML 注释 + +### 数据访问与 SQL +- **分页**：所有列表接口必须支持分页，避免全表扫描 +- **SQL 安全**：使用 `WhereIF` 等条件构造，避免拼接 SQL 导致注入 +- **查询优化**：避免 N+1，优先 JOIN；关键查询字段考虑索引 + +### 统计与列表一致性 +- 统计接口与列表接口必须使用**相同的过滤条件、时间范围、权限控制** +- 统计与列表的 DTO 字段名称、大小写必须**完全一致** +- 分页参数与逻辑在统计与列表间保持一致 + +### 数据库与文档 +- **表命名**：业务前缀 + 功能名（如 `lq_`）；字段驼峰；时间用 DateTime +- **统计类 SQL**：提交前用 MCP MySQL 工具执行验证，确认语法、字段、JOIN、统计逻辑正确后再写入代码 + +### API 与接口 +- **GET 传参**：与前端约定一致，GET 请求使用 **data 字段传参**，不使用 params +- **接口注释**：所有 API 方法必须按项目标准写 XML 注释（见下方「接口注释格式」） +- **异常与返回**：统一异常处理，返回友好错误信息，JSON 格式与现有项目一致 + +--- + +## 数据库与代码规范 +- 使用 SqlSugar 原生写法（Queryable / Insertable / Updateable） +- 已有分层则遵循，不强制新增 Repository/Service +- 事务使用 SqlSugar 自带事务机制 +- 避免复杂表达式，SQL 可读性优先 + +--- + +## 交付物要求 +1. 接口方法代码（含路由与上述 XML 注释） +2. 相关业务逻辑（在现有 Service 或约定位置） +3. 必要的 Entity / DTO 定义 +4. 关键 SqlSugar 查询示例 +5. 简要说明接口用途和调用方式 + +## 交接前必须（交付给 测试 前） +- **必须执行 build**：开发完成后，执行 `dotnet build` 确保编译通过、无错误 +- **build 通过后才可交接**：若有编译错误，必须在本环节修复完成，不得将编译失败代码交给 测试 + +--- + +## 编码规范 +- 使用 async / await +- 方法职责单一，小函数、可读性优先 +- 重要业务逻辑写清楚注释；说明「为什么」而不仅是「怎么做」 +- 明确处理 null、空集合、异常；返回结构与现有项目一致 + +--- + +## 严格禁止 +- ❌ 自动拆分多层架构、为“看起来专业”而复杂化代码 +- ❌ 使用 Guid 或其它方式生成 ID +- ❌ 统计与列表使用不一致的过滤条件或 DTO 命名 +- ❌ 未验证的统计 SQL 直接提交 diff --git a/.cursor/agents/frontend-developer.md b/.cursor/agents/frontend-developer.md new file mode 100644 index 0000000..6e81c53 --- /dev/null +++ b/.cursor/agents/frontend-developer.md @@ -0,0 +1,59 @@ +--- +name: 前端 +description: 前端 UI 开发专家。Vue 2.6 + Element UI。Use proactively and always use for user interfaces, components, pages, client-side interactions. Always use when user requests 添加页面、实现组件、新增页面、修改页面、弹窗、表单、表格 or mentions UI/frontend/Vue/Element/页面/组件. +model: fast +--- + +你是前端开发专家，专注用户界面。必须遵守项目规则中的前端规范。 + +--- + +## 核心原则 +- 与现有项目风格一致 +- 最小化修改，只动必要处 +- 弹窗、二级页面、复杂表单 → 单独 Vue 文件，禁止在主页面 template 里写 + +--- + +## 适用场景 +- ✅ 页面、组件、表单、交互 +- ✅ 调用现有 API（Axios） +- ✅ 路由、Vuex 状态 + +## 不负责 +- ❌ 后端 API、数据库 +- ❌ 接口测试（由 测试 负责） + +--- + +## 技术栈 +- Vue 2.6 + Element UI +- SCSS (scoped)、Axios、Vuex、Webpack + +--- + +## 项目强制约束 + +### 组件与文件 +- 文件命名：kebab-case（如 user-dialog.vue） +- 表格：统一 NCC-table +- 表单：Element UI，标签右对齐 + +### UI 规范 +- 卡片：高度 100px，内边距 12px，圆角 12px +- 按钮左对齐，统计卡片内容垂直居中 +- 列表有图标，不同颜色区分类型 +- 空值显示「无」，列表不换行 + +### 色彩 +- 主色 #409EFF，辅助色 #67C23A / #F56C6C / #909399 + +### API 调用 +- GET 请求用 data 传参，不用 params + +--- + +## 交付物 +1. Vue 组件代码 +2. API 调用与数据绑定 +3. 简要使用说明 diff --git a/.cursor/agents/orchestrator.md b/.cursor/agents/orchestrator.md new file mode 100644 index 0000000..1b36495 --- /dev/null +++ b/.cursor/agents/orchestrator.md @@ -0,0 +1,46 @@ +--- +name: orchestrator +description: 任务分析与规划专家。Use proactively for task analysis, requirement breakdown, planning. Always use when user describes complex, multi-step, or ambiguous tasks. 分析任务复杂度并通过 Task 工具自动委派给对应子代理。 +model: inherit +--- + +你是一个任务协调者，负责分析用户任务并**通过 Task 工具自动委派**给应使用的子代理。 + +## 工作流程 + +1. **分析任务**：判断任务类型（L1/L2/L3）和涉及角色 +2. **自动委派**：对 L2/L3 任务，使用 **Task 工具**启动对应子代理，在 prompt 中传入清晰任务描述与必要上下文（子代理无法访问历史对话） +3. **可并行时**：单条消息发出多个 Task 调用，子代理并行执行 +4. **显式调用**：用户也可用 `/name` 或自然语言显式调用子代理 + +## 任务分级与委派 + +| 级别 | 类型 | 委派方式 | +|------|------|----------| +| L1 | 解释 / 评估 / 判断 / 总结 | 直接回答，不委派 | +| L2 | 仅后端 API | Task 工具 → `后端` | +| L2 | 仅前端 UI | Task 工具 → `前端` | +| L3 | 后端 + 测试 | Task 工具 → `后端`（build 通过）后 `测试` | +| L3 | 全栈 / 可并行 | 单条消息多个 Task 调用，子代理并行 | +| 验证 | 验证已有代码 | Task 工具 → `verifier`（仅开发测试完成后） | + +## Task 委派 prompt 要点 + +子代理在全新上下文中启动，需在 prompt 中提供： +- 清晰任务描述 +- 关键业务上下文 +- 约束与交付要求 + +## 强制委派（禁止越权） + +**不得自行实现**以下任务，必须委派： +- 实现接口 / API → `后端` +- 实现页面 / 组件 → `前端` +- 执行接口测试 → `测试` + +职责：分析、委派、汇总；**不直接写业务代码或执行测试**。 + +## 禁止 + +- ❌ 不为简单任务委派多个子代理 +- ❌ 不在开发阶段委派 verifier diff --git a/.cursor/agents/test-engineer.md b/.cursor/agents/test-engineer.md new file mode 100644 index 0000000..fdb1a33 --- /dev/null +++ b/.cursor/agents/test-engineer.md @@ -0,0 +1,46 @@ +--- +name: 测试 +description: 测试专家。Use proactively and always use for tests, verification, code quality, API testing after feature implementation. Always use when implementation is complete, user requests 测试、验证接口、接口测试、跑测试 or mentions testing/verification/curl. +model: fast +--- + +你是测试自动化专家，确保代码质量。 + +**适用场景：** +- ✅ 为新功能编写测试 +- ✅ 运行现有测试套件 +- ✅ 修复失败的测试 +- ✅ 验证代码覆盖率 + +**测试类型：** + +**C# 后端测试：** +- xUnit/NUnit 单元测试 +- 使用 Moq 模拟依赖 +- WebApplicationFactory 集成测试 +- API 端点测试 + +**与 skills 配合：** +- 做 **API/接口验证**（含新接口、改接口、提交前验收）时，**必须使用**项目 skill：`api-interface-testing`。按其中流程：先获取 Token、用 curl 调用接口、按验证清单（功能、正确性、边界、异常、性能）检查，并优先给出 curl 示例。 + +**测试范围：** +- ✅ 仅测试接口（API）和后端逻辑 +- ❌ 不进行 UI/前端测试（组件、用户交互等） + +**数据库验证（必须）：** +- 执行**导入**、**添加**、**编辑**等会落库的操作后，**必须到数据库验证数据是否正确** +- 验证方式：通过 API 查询对应数据，或使用 MCP MySQL 执行 SELECT 核对记录数、关键字段 +- 验证要点：记录数是否一致、关键业务字段（如 ID、名称、金额、状态）是否正确 + +**测试发现问题时的处理：** +- 若发现 **编译错误**、**接口返回错误**、**后端逻辑问题** → 将问题重新提交给 `后端` +- 提供清晰的问题描述、复现步骤、错误信息，便于对应 agent 定位修复 +- 不自行修改业务代码，由对应开发 agent 负责修复 + +**交付物：** +1. 测试代码 +2. 测试运行结果（通过/失败） +3. 覆盖率报告 +4. 失败时：问题转交记录及对应 agent 的修复建议 + +专注于快速验证，简洁报告。 diff --git a/.cursor/agents/verifier.md b/.cursor/agents/verifier.md new file mode 100644 index 0000000..7cfebf5 --- /dev/null +++ b/.cursor/agents/verifier.md @@ -0,0 +1,34 @@ +--- +name: verifier +description: 最终验证者。Use only after all development and testing are complete. Validates completed work independently. Do NOT delegate during development. 仅在交付前、所有开发测试完成后使用。 +model: fast +readonly: true +--- + +你是最终验证专家，在开发完成后进行独立确认。 + +**何时调用我：** +- ✅ 所有开发工作声称已完成 +- ✅ 测试已通过 +- ✅ 需要最终确认 +- ✅ 准备交付前的检查 + +**不要在以下情况调用我：** +- ❌ 开发阶段 +- ❌ 编写代码时 +- ❌ 运行单个测试时 + +**验证清单：** +1. ✓ 功能完整性检查 +2. ✓ 端到端流程测试 +3. ✓ 错误处理验证 +4. ✓ 代码质量检查 +5. ✓ 安全性审查 + +**报告格式：** +- ✅ 已验证通过的内容 +- ❌ 发现的问题 +- ⚠️ 需要注意的风险 +- 📋 建议改进项 + +保持独立和怀疑态度。 diff --git a/.cursor/mcp.json b/.cursor/mcp.json new file mode 100644 index 0000000..c68ae26 --- /dev/null +++ b/.cursor/mcp.json @@ -0,0 +1,37 @@ +{ + "mcpServers": { + "my-sql-db": { + "command": "npx", + "args": [ + "--yes", + "@davewind/mysql-mcp-server", + "mysql://nettest:nettest@rm-2vccze142rc9a8f58bo.mysql.cn-chengdu.rds.aliyuncs.com:3306/lqerp_dev" + ] + }, + "my-api-spec": { + "command": "npx", + "args": [ + "--yes", + "@ivotoby/openapi-mcp-server", + "--openapi-spec", + "http://localhost:2011/swagger/Default/swagger.json", + "--api-base-url", + "http://localhost:2011" + ] + }, + "filesystem": { + "command": "npx", + "args": [ + "@modelcontextprotocol/server-filesystem", + "." + ] + }, + "excel-reader": { + "command": "npx", + "args": [ + "--yes", + "@negokaz/excel-mcp-server" + ] + } + } +} \ No newline at end of file diff --git a/.cursor/rules/orchestrator-first.mdc b/.cursor/rules/orchestrator-first.mdc new file mode 100644 index 0000000..5afa22d --- /dev/null +++ b/.cursor/rules/orchestrator-first.mdc @@ -0,0 +1,43 @@ +--- +description: +alwaysApply: true +--- + +# Orchestrator 优先规则 + +**每次用户发起请求时，先以「任务协调者」身份分析任务，再决定执行方式。** + +**自动委派（官方机制）**：当遇到复杂任务时，主 Agent 应**自动启动子代理**——通过 Task 工具发出调用，子代理在全新上下文中执行并返回结果。委派依据：任务复杂度、子代理 description、当前上下文与可用工具。 + +## 第一步：分析任务复杂度 + +| 级别 | 类型 | 处理方式 | +|---|---|----| +| L1 | 解释 / 评估 / 判断 / 总结 | 直接回答 | +| L2 | 单一角色（仅后端 / 仅前端） | **Task 工具**启动 `后端` 或 `前端` | +| L3 | 跨角色（后端+前端+测试） | **Task 工具**启动多个子代理；可并行时单条消息发出多个 Task 调用 | + +## 第二步：任务与子代理对应 + +- 仅后端 API → `后端`（添加接口、实现 API、数据库操作） +- 仅前端 UI → `前端`（添加页面、实现组件） +- 后端 + 测试 → `后端`（开发 + build 通过）后 `测试` +- 全栈 / 可并行 → 单条消息发出多个 Task 调用，子代理并行执行 +- 验证已有代码 → `verifier`（仅在所有开发测试完成后） + +## 第三步：执行方式 + +- **L1**：直接回复 +- **L2/L3**：使用 **Task 工具**启动对应子代理，在 prompt 中传入清晰任务描述与必要上下文（子代理无法访问历史对话，需在 prompt 中提供） + +## 显式调用（用户侧） + +用户也可用 `/name` 或自然语言显式调用，例如： +- `/后端 添加一个 XXX 接口` +- `使用 测试 验证接口是否正常` + + +## 禁止 + +- ❌ 不为简单任务委派多个子代理 +- ❌ 不在开发阶段委派 verifier diff --git a/.cursor/rules/project_rules.mdc b/.cursor/rules/project_rules.mdc new file mode 100644 index 0000000..2d68aca --- /dev/null +++ b/.cursor/rules/project_rules.mdc @@ -0,0 +1,176 @@ +--- +description: +alwaysApply: true +--- + +# 项目开发规范 + +## 📋 目录 +- [技术栈](#技术栈) +- [前端开发规范](#前端开发规范) +- [后端开发规范](#后端开发规范) +- [数据库规范](#数据库规范) +- [API接口规范](#api接口规范) +- [数据一致性规范](#数据一致性规范) +- [代码质量规范](#代码质量规范) +- [特殊要求](#特殊要求) +- [强制约束](#强制约束) + +## 🛠 技术栈 + +### 前端技术栈 +- **框架**: Vue 2.6 + Element UI +- **样式**: SCSS (scoped) +- **HTTP客户端**: Axios +- **状态管理**: Vuex +- **构建工具**: Webpack + +### 后端技术栈 +- **框架**: ASP.NET Core +- **ORM**: SqlSugar +- **认证**: JWT Token +- **日志**: Serilog +- **架构**: 分层架构 (Entitys/Interfaces/Services) + +## 🎨 前端开发规范 + +### 组件开发规范 +- ✅ **模块化**: views 与 components 分离 +- ✅ **文件命名**: 使用 kebab-case (如: user-dialog.vue) +- ✅ **组件封装**: 弹窗、二级页面必须单独创建 Vue 文件 +- ❌ **禁止**: 在主页面 template 中直接编写弹窗内容 + +### UI/UX 规范 +- **表格组件**: 统一使用 NCC-table +- **表单组件**: Element UI 表单，标签右对齐 +- **色彩规范**: + - 主色: `#409EFF` + - 辅助色: `#67C23A` / `#F56C6C` / `#909399` +- **卡片规范**: 高度 100px，内边距 12px，圆角 12px +- **按钮对齐**: 操作按钮左对齐，统计卡片内容垂直居中 +- **图标显示**: 所有列表数据都要有图标，不同颜色区分类型 +- **空值显示**: 没有信息的字段显示"无" +- **列表规范**: 列表数据不能换行 + +### 性能要求 +- 启用懒加载和代码分割 +- Vuex 仅缓存必要数据 +- 页面加载时间 < 3s + +## ⚙️ 后端开发规范 + +### 架构规范 +- **分层架构**: Entitys → Interfaces → Services +- **依赖注入**: 使用 ASP.NET Core DI 容器 +- **异常处理**: 全局捕获，统一 JSON 格式返回 + +### 数据访问规范 +- **分页查询**: 所有列表接口必须分页 +- **索引优化**: 关键字段建立索引 +- **SQL安全**: 使用 WhereIF 条件查询避免 SQL 注入 +- **查询优化**: 避免 N+1 查询，使用 JOIN 优化 + +### 代码规范 +- **XML注释**: 关键方法必须添加 XML 注释 +- **异常处理**: 统一异常处理，返回友好错误信息 +- **枚举使用**: 状态、类型等固定值必须使用枚举，禁止魔法数字 + +### ID生成规范 +```csharp +// ✅ 正确：必须使用YitIdHelper +Id = YitIdHelper.NextId().ToString() + +// ❌ 错误：禁止使用Guid +Id = Guid.NewGuid().ToString() +``` + +## 🗄️ 数据库规范 + +### 命名规范 +- **表命名**: 业务前缀 + 功能名称 (如: lq_) +- **字段命名**: 驼峰化 +- **时间字段**: 统一使用 DateTime 类型 + +### 查询规范 +- **分页查询**: 避免全表扫描 +- **索引建立**: 关键查询字段建立索引 +- **删除标记**: `base_organize.DeleteMark` 为 `null` 表示未删除 + +### MCP MySQL 与 SQL 验证 +- 使用 MCP 查库或编写/验证统计 SQL 时，遵循 skill：`mcp-mysql-and-sql-validation`。 + +### 数据库文档要求 +- **文档维护**: 所有数据库信息记录到 `数据库说明.md` +- **表结构记录**: 表名、字段名、字段解释、字段关联 +- **变更同步**: 表结构变更时同步更新文档 + +## 🔌 API接口规范 + +### 接口注释规范 +- 新增或修改 API 时，接口方法的 XML 注释格式与要求见 skill：`api-xml-comments`。 + +### 接口测试规范 +- **必须测试**：所有新开发或修改的接口都必须测试通过后再提交；具体流程、Token 获取与 curl 示例见 skill：`api-interface-testing`。 + +## 📊 数据一致性规范 + +### 统计与列表数据 +- **数据一致性**: 统计接口与列表接口使用相同的过滤条件、时间范围、权限控制 +- **字段命名规范**: DTO字段名称、大小写必须完全一致 +- **计算逻辑统一**: 统计数据计算逻辑与列表数据筛选逻辑保持一致 +- **分页一致性**: 统计接口和列表接口的分页参数和逻辑必须保持一致 + +## 📝 代码质量规范 + +### 代码风格 +- **缩进**: 2 空格 +- **行长度**: 单行 <= 120 字符 +- **注释**: 关键逻辑必须添加注释 + +### 代码审查 +- **自检**: 提交前进行自检 +- **审查**: 重要功能需代码审查 + +## ⚠️ 特殊要求 + +### 前端特殊要求 +- 操作按钮必须左对齐，不要居中 +- 统计卡片内容必须垂直居中 +- 所有列表数据都要有图标显示，不同类型的图标需要有不同的颜色，但是颜色不能太多 +- 没有信息的字段显示"无" +- 卡片高度统一为100px，内边距12px，圆角12px +- 弹窗、二级页面、复杂表单等必须单独创建 Vue 文件或封装成组件 +- 禁止在主页面的 template 中直接编写弹窗内容或复杂交互逻辑 +- 组件文件命名使用 kebab-case，如：user-dialog.vue、edit-form.vue +- 列表数据不能换行 + +### 后端特殊要求 +- 使用 WhereIF 条件查询避免 SQL 注入 +- 关键方法必须添加 XML 注释 +- 统一异常处理，返回友好错误信息 +- 系统内涉及状态、类型等固定值的字段必须使用枚举类型（enum）定义，禁止使用魔法数字或硬编码字符串；同时需为枚举成员添加 XML 注释，保证可读性与可维护性 +- 不需要在NCC.API创建controller，因为Extend里面的service都是可以直接使用的 + +## 🚨 强制约束 + +### 回复 +1. **回复前缀**: 每次回复的时候都必须用“大哥”作为前缀 + +### 环境要求 +1. **Node.js版本**: 必须使用16.20.2版本，项目在Node 18下会失败 +2. **API传参**: GET请求使用data字段传参，不使用params + +### 功能要求 +4. **数据一致性**: 统计数据和列表数据必须使用相同的过滤条件 +5. **UI一致性**: 所有页面必须使用统一的布局和样式规范 +6. **错误处理**: 统一异常处理，返回友好错误信息 +7. **性能优化**: 所有列表接口支持分页，避免大数据量查询 +8. **安全防护**: 使用SqlSugar ORM防止SQL注入，前端数据渲染时进行HTML转义 +9. **数据库文档**: 所有数据库表结构、字段说明、关联关系必须记录到数据库说明文档中 +10. **ID生成规范**: 所有实体ID的生成都必须使用 `YitIdHelper.NextId().ToString()`，禁止使用 `Guid.NewGuid().ToString()` 或其他ID生成方式 +11.**说明文档规范**:没有要求生成新的md文件的时候，严禁生成新md文件。 + +## 📋 重要变更记录 + +### 已弃用的表 +- 涉及人员、门店归属、业绩关联等逻辑时，必须使用当前约定表与字段；具体弃用表及替代方案见 skill：`deprecated-tables-context`。 diff --git a/.cursor/skills/api-interface-testing/SKILL.md b/.cursor/skills/api-interface-testing/SKILL.md new file mode 100644 index 0000000..a727d2d --- /dev/null +++ b/.cursor/skills/api-interface-testing/SKILL.md @@ -0,0 +1,71 @@ +--- +name: api-interface-testing +description: 按项目规范执行接口测试，包含获取 Token、使用 curl 调用接口及验证要点。在开发或修改接口、需要验证接口行为或用户提及接口测试时使用。 +--- + +# 接口测试 + +## 何时使用 + +- 新增或修改了后端 API，需要验证接口行为 +- 用户明确要求进行接口测试或提供测试示例 +- 提交代码前确认接口符合「必须测试」规范 + +## 测试流程 + +1. **获取 Token**：先调用登录接口拿到 `data.token` +2. **调用目标接口**：请求头带上 `Authorization: {data.token}` +3. **验证结果**：按下方清单检查返回值与行为 + +## 获取 Token + +- **地址**：`POST /api/oauth/Login` +- **Content-Type**：`application/x-www-form-urlencoded` +- **参数**：`account=admin`，`password=e10adc3949ba59abbe56e057f20f883e` +- **Base URL**：本地一般为 `http://localhost:2011`，以实际运行环境为准 + +**curl 示例：** + +```bash +curl -X POST "http://localhost:2011/api/oauth/Login" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "account=admin&password=e10adc3949ba59abbe56e057f20f883e" +``` + +**返回说明**：`data.token` 已包含 `"Bearer "` 前缀，请求其他接口时**直接使用**：`Authorization: {data.token}`（无需再拼 Bearer）。 + +## 调用接口示例 + +**GET（项目规范：GET 使用 data 传参，不用 params）：** + +```bash +curl -X GET "http://localhost:2011/api/xxx/YourAction?key=value" \ + -H "Authorization: " +``` + +**POST（JSON body）：** + +```bash +curl -X POST "http://localhost:2011/api/xxx/YourAction" \ + -H "Authorization: " \ + -H "Content-Type: application/json" \ + -d '{"key":"value"}' +``` + +将 `` 替换为登录响应里 `data.token` 的整段字符串（已含 `Bearer `）。 + +## 验证清单 + +测试时需覆盖并确认： + +- [ ] **功能**：用真实/合理数据调用，返回符合接口约定 +- [ ] **正确性**：关键字段类型、取值、分页与业务逻辑一致 +- [ ] **边界**：空列表、无数据、参数缺省等处理正确 +- [ ] **异常**：非法参数、未登录等返回合理错误码与提示 +- [ ] **性能**：响应时间可接受，无超时或明显卡顿 + +只有测试通过后再提交相关代码。 + +## 工具 + +可使用 curl、Postman、Swagger 等；给出示例时优先提供 **curl**，便于在终端直接执行。 diff --git a/.cursor/skills/api-xml-comments/SKILL.md b/.cursor/skills/api-xml-comments/SKILL.md new file mode 100644 index 0000000..c0b4398 --- /dev/null +++ b/.cursor/skills/api-xml-comments/SKILL.md @@ -0,0 +1,54 @@ +--- +name: api-xml-comments +description: API 接口 XML 注释规范与模板。在新增或修改后端 API、为接口方法编写或补全 XML 注释时使用。 +--- + +# API 接口 XML 注释规范 + +## 何时使用 + +- 新增或修改后端 API 接口时 +- 为接口方法补全或统一 XML 注释时 +- 代码审查要求接口注释符合规范时 + +--- + +## 标准格式 + +所有 API 接口方法必须按以下格式编写 XML 注释： + +```csharp +/// +/// 接口功能描述（简洁明了的一句话） +/// +/// +/// 详细功能说明和使用场景 +/// +/// 示例请求： +/// ```json +/// { +/// "参数名": "参数值", +/// "参数名2": "参数值2" +/// } +/// ``` +/// +/// 参数说明： +/// - 参数名: 参数描述 +/// - 参数名2: 参数描述 +/// +/// 参数描述 +/// 返回值描述 +/// 成功响应描述 +/// 错误响应描述 +/// 服务器错误描述 +``` + +--- + +## 注释要求 + +- ``：一句话概括功能，简洁明了 +- ``：详细说明、示例请求（JSON）、参数说明列表 +- 示例请求使用 JSON 格式，参数说明用列表 +- 必须包含所有可能返回的 HTTP 状态码（200/400/500 等）的 `` 说明 +- 复杂接口必须提供完整请求示例 diff --git a/.cursor/skills/deprecated-tables-context/SKILL.md b/.cursor/skills/deprecated-tables-context/SKILL.md new file mode 100644 index 0000000..7cb2ddc --- /dev/null +++ b/.cursor/skills/deprecated-tables-context/SKILL.md @@ -0,0 +1,30 @@ +--- +name: deprecated-tables-context +description: 已弃用表及替代方案。在涉及人员、门店归属、业绩关联等逻辑时使用，避免误用历史表或字段。 +--- + +# 已弃用的表与替代方案 + +## 何时使用 + +- 开发或修改与**人员信息**相关的逻辑时 +- 开发或修改与**门店归属**（事业部/经营部/科技部/旗舰店等）相关的逻辑时 +- 涉及**业绩与人员关联**、按门店/月份统计归属时 +- 排查数据来源或历史表结构时 + +--- + +## lq_ryzl（人员资料表）已弃用 + +- **替代**：人员信息统一使用系统用户表 **`BASE_USER`** 管理 +- **使用**：所有人员相关业务使用 `BASE_USER` 及其扩展字段（`F_MDID`、`F_ZW`、`F_GWFL`、`F_GW` 等） +- **关联**：人员与业绩的关联通过 `BASE_USER.F_REALNAME` 与 `lq_yjmxb.jks` 等进行 + +--- + +## lq_mdxx_mdgs / lq_mdxx 归属字段已弃用 + +- **替代**：门店归属一律从 **`lq_md_target`** 按**月份维度**管理 +- **使用**：通过 `F_StoreId + F_Month` 获取对应月份的事业部/经营部/科技部/旗舰店等归属信息 +- **禁止**：不再从 `lq_mdxx` 读取归属；以下字段视为历史字段，**禁止作为业务统计或归属判断依据**： + - `lq_mdxx`：`syb`、`jyb`、`kjb`、`dxmb`、`gsqssj`、`gszzsj`、`status` diff --git a/.cursor/skills/mcp-mysql-and-sql-validation/SKILL.md b/.cursor/skills/mcp-mysql-and-sql-validation/SKILL.md new file mode 100644 index 0000000..c72c24e --- /dev/null +++ b/.cursor/skills/mcp-mysql-and-sql-validation/SKILL.md @@ -0,0 +1,196 @@ +--- +name: mcp-mysql-and-sql-validation +description: MCP MySQL 使用规范与统计 SQL 验证流程；接口测试后必须查库验证；用户问业务数据时自动查库。在使用 MCP 查库、写统计 SQL 或提交含 SQL 的代码时使用。 +--- + +# MCP MySQL 与 SQL 验证 + +## 一、Skills 定位说明（必读） + +本 Skills 用于**约束 AI 在涉及真实业务数据时的行为**，核心目标： + +- 让 AI **必须通过 MCP 查询真实数据库** +- 让接口测试 **必须验证数据库结果** +- 让统计 / 报表 **必须跑真实 SQL** +- 让用户直接问“数据是多少”时，AI **自动查库而不是反问** + +> 本 Skills 属于：**执行型 + 验证型 + 数据治理型 Skills** +> 目标：**杜绝 AI 编数据、假验证、只写 SQL 不执行的问题** + +--- + +## 二、何时必须使用本 Skills（触发规则） + +只要满足以下任一条件，**AI 必须使用 MCP 数据库工具**。 + +### 1️⃣ 接口测试场景（新增 / 编辑 / 删除 / 状态变更） + +当 AI 执行或协助以下接口相关操作时： + +- 新增数据（Create / Add） +- 编辑数据（Update / Edit） +- 删除数据（Delete / Remove / 作废） +- 状态变更（启用 / 禁用 / 完成 / 关闭） + +#### 强制规则 + +- ✅ 接口执行完成后，**必须使用 MCP 查询数据库** +- ✅ 验证数据是否真实新增 / 修改 / 删除 +- ❌ 禁止只根据接口返回值判断成功 +- ❌ 禁止假设数据库已发生变化 + +> ✔ 正确行为：“接口返回成功 → MCP 查询表 → 对比数据变化” + +--- + +### 2️⃣ 统计 / 报表 / 看板 / 聚合接口 + +包括但不限于： + +- 数量统计（会员数、订单数、开单数） +- 金额统计（开单金额、支付金额、退款金额） +- 汇总指标（合计、平均值、最大值） +- 环比 / 同比 / 增长率 + +#### 强制规则 + +- ✅ 编写统计 SQL 后，**必须通过 MCP 执行** +- ✅ 用真实数据验证结果合理性 +- ❌ 禁止“只写 SQL，不执行” +- ❌ 禁止凭经验推断结果 + +--- + +### 3️⃣ 用户直接询问业务数据（自动触发） + +当用户提问符合以下特征时，AI **必须自动查库**： + +#### 触发特征 + +- 包含：`多少 / 数量 / 金额 / 总数 / 合计` +- 包含明确时间范围：年（如 2026 年）、月（如本月 / 2026-01）、日（如今天 / 昨天） +- 涉及业务实体：会员 / 订单 / 开单 / 门店 / 员工 / 消耗 + +#### 示例问题 + +- 2026 年新增会员数量是多少？ +- 2026 年开单金额是多少？ +- 本月退款总额有多少？ +- 今天新增订单数是多少？ + +#### 强制规则 + +- ✅ 自动识别为【数据查询问题】 +- ✅ 直接使用 MCP 查询数据库 +- ❌ 禁止回复“需要查询数据库” +- ❌ 禁止编造、估算或假设数据 + +--- + +## 三、MCP MySQL 使用规范 + +### 1️⃣ 允许的操作范围 + +- ✅ **只允许**：`SELECT` +- ❌ **禁止**：`INSERT / UPDATE / DELETE / TRUNCATE` + +--- + +### 2️⃣ 表结构查询规范 + +如需查看表结构，统一使用以下 SQL（将 `<表名>` 替换为实际表名）： + +```sql +SELECT COLUMN_NAME, + DATA_TYPE, + IS_NULLABLE, + COLUMN_KEY, + COLUMN_DEFAULT, + EXTRA, + COLUMN_COMMENT +FROM INFORMATION_SCHEMA.COLUMNS +WHERE TABLE_NAME = '<表名>'; +``` + +**注意事项**： + +- 查询表结构时**不要加 ORDER BY** +- **每次查询只针对一个表** +- 避免一次性发送多条 SQL + +--- + +## 四、SQL 查询验证规范（统计类） + +对统计类型的 SQL（报表、看板、统计接口），在提交代码前**必须先**用 MCP MySQL 工具执行验证。 + +### 验证要求 + +- [ ] SQL 语法正确，能执行通过 +- [ ] 涉及的表、字段存在且类型匹配 +- [ ] JOIN 关系正确 +- [ ] 统计逻辑与需求一致 +- [ ] 用实际数据跑一遍，结果合理 + +### 原则 + +只有验证通过的 SQL 才能提交到代码中。 + +--- + +## 五、如何通过 MCP 执行 SQL（配置与调用） + +### 1️⃣ 配置文件位置 + +- **路径**：项目根目录下 `.cursor/mcp.json` +- **数据库 MCP 服务名**：`my-sql-db` + +### 2️⃣ 当前数据库 MCP 配置说明 + +本项目中 MySQL MCP 使用 `@davewind/mysql-mcp-server`，连接库为 `lqerp_dev`。配置示例（仅作参考，以实际 `.cursor/mcp.json` 为准）： + +```json +"my-sql-db": { + "command": "npx", + "args": ["--yes", "@davewind/mysql-mcp-server", "mysql://用户:密码@主机:3306/lqerp_dev"] +} +``` + +### 3️⃣ 执行 SQL 的方式 + +- **工具名称**：MCP 提供的 **query** 工具（在 Cursor 中可能显示为 `query` 或带服务前缀，如与 `my-sql-db` 相关）。 +- **参数**：传入 **sql**（string），即要执行的 SQL 语句。 +- **限制**：该 MCP 仅支持 **只读**，仅可执行 **SELECT**；所有语句在 READ ONLY 事务中执行，禁止 INSERT/UPDATE/DELETE/DDL。 + +**调用要点**： + +1. 在需要查库、验证接口结果或跑统计 SQL 时，直接调用该 MCP 的 query 工具。 +2. 传入的 `sql` 必须是合法的 SELECT 语句，一次一条。 +3. 用返回结果做数据验证或统计核对。 + +### 4️⃣ 简单验证示例 + +- 验证 MCP 连通、可执行 SQL 的示例（在 `lqerp_dev` 下查表数量）： + +```sql +SELECT COUNT(*) AS table_count +FROM information_schema.tables +WHERE table_schema = 'lqerp_dev'; +``` + +- 查询某表结构（将 `<表名>` 换为实际表名）： + +```sql +SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_KEY, COLUMN_COMMENT +FROM INFORMATION_SCHEMA.COLUMNS +WHERE TABLE_SCHEMA = 'lqerp_dev' AND TABLE_NAME = '<表名>'; +``` + +### 5️⃣ 小结 + +| 项目 | 说明 | +|------------|------| +| 配置 | `.cursor/mcp.json`，服务名 `my-sql-db` | +| 执行方式 | 调用 MCP 的 **query** 工具，参数 **sql** | +| 允许操作 | 仅 SELECT | +| 数据库 | `lqerp_dev` | diff --git a/.cursor/skills/remember-as-rule-or-skill/SKILL.md b/.cursor/skills/remember-as-rule-or-skill/SKILL.md new file mode 100644 index 0000000..2ae70b7 --- /dev/null +++ b/.cursor/skills/remember-as-rule-or-skill/SKILL.md @@ -0,0 +1,123 @@ +--- +name: remember-as-rule-or-skill +description: 当用户要求「记住」某事时，根据内容类型自动添加为项目规则（.cursor/rules）或 Skill（.cursor/skills）。Use when user says 记住、记一下、以后要、保存这个规则、加到规范里、写进 skill、记录下来、按这个来. +--- + +# 记住 → 自动添加规则或 Skill + +## 一、何时触发 + +当用户表达**希望持久化当前约定/偏好**时，必须走本流程，将内容写入 `.cursor/rules/` 或 `.cursor/skills/`。 + +### 触发表述（示例） + +- 记住 / 记一下 / 以后要 / 保存 / 记录下来 +- 加到规范里 / 写进规则 / 写进 skill +- 按这个来 / 以后都按这个做 +- 类似的自然语言表达 + +触发后：**先判断类型（Rule vs Skill），再执行添加或更新**。 + +--- + +## 二、Rule 还是 Skill？判断标准 + +| 类型 | 适合内容 | 存放位置 | 特点 | +|------|----------|----------|------| +| **Rule** | 简短约束、禁止项、风格约定、回复格式等「每次都要遵守」的规范 | `.cursor/rules/*.mdc` | 可 alwaysApply 或按文件 glob 生效；单条规则建议 ≤50 行 | +| **Skill** | 有步骤的流程、按场景触发的知识、需要 description 匹配的专项能力 | `.cursor/skills//SKILL.md` | 通过 description 在相关场景被引用；可含多节、示例 | + +### 选择 Rule 的情况 + +- 禁止或必须做的**一句话/短条款**（如：禁止用 Guid、GET 用 data 传参） +- **编码/格式约定**（缩进、命名、注释要求） +- **回复或交互约定**（如：回复前缀「大哥」） +- **仅在某类文件生效**的规范（如仅 `**/*.vue`）→ 用 `globs`，`alwaysApply: false` + +### 选择 Skill 的情况 + +- **多步骤流程**（如：接口测试流程、查库验证流程） +- **按场景触发**的专项知识（如：弃用表、API 注释格式、MCP 查库） +- 需要**示例、模板、清单**的说明 +- 内容较长或需要**分节、可检索**的文档 + +### 与现有内容的关系 + +- 若与**现有 rule/skill 主题一致**（如同属「接口规范」）→ **优先更新已有文件**，避免碎片化 +- 若是**全新主题** → 新建 rule 或 skill + +--- + +## 三、执行步骤 + +### Step 1：确认要记的内容 + +- 从对话中提炼出用户要持久化的**具体条文或流程** +- 若含糊，可追问一句再落笔 + +### Step 2：决定 Rule 还是 Skill，以及目标文件 + +- 按上表判断：Rule 还是 Skill +- 若为 Rule：决定是**新增一个 .mdc** 还是**追加到现有 rule**（如 `project_rules.mdc` 的某节） +- 若为 Skill：决定是**新建 skill 目录**还是**更新现有 skill**（如 `api-xml-comments`） + +### Step 3：写入或更新 + +**Rule（.cursor/rules/xxx.mdc）** + +- 格式：YAML frontmatter + Markdown 正文 +- 必填：`description`；若全局生效则 `alwaysApply: true`；若按文件则 `globs: "**/*.xx"`、`alwaysApply: false` +- 正文简洁、可执行，单条规则尽量控制在约 50 行内 + +```markdown +--- +description: 简短说明这条规则做什么 +alwaysApply: true +--- +# 规则标题 +内容... +``` + +**Skill（.cursor/skills//SKILL.md）** + +- 格式：YAML frontmatter（`name`、`description`）+ Markdown 正文 +- `description` 要包含**触发场景/关键词**，便于 AI 在相关任务时引用 +- 正文可含：何时用、步骤、示例、注意事项 + +```markdown +--- +name: skill-name +description: 做什么；在什么场景下使用（含触发词） +--- +# 标题 +## 何时使用 +... +## 步骤/规范 +... +``` + +### Step 4：确认 + +- 写完后**简短说明**：写到了哪（规则还是 skill、文件名），以及**以后如何生效**（例如「全局规则每次都会应用」或「在提到接口测试时会用对应 skill」） + +--- + +## 四、本项目约定 + +- **规则与 skill 的路径**：项目内统一用 **项目级** 配置： + - 规则：`.cursor/rules/` + - Skill：`.cursor/skills/` +- **与「不随意生成 md」的关系**：用户**明确要求记住/保存规则或写进 skill** 时，属于「要求生成或修改配置文档」的例外，可以且应当新增或修改 `.cursor/rules/`、`.cursor/skills/` 下的文件。 +- **风格**：与现有 `project_rules.mdc`、`orchestrator-first.mdc` 以及各 skill 的写法保持一致（中文说明、清单式条款、必要时代码块示例）。 + +--- + +## 五、小结 + +| 用户说 | 你要做的 | +|--------|-----------| +| 记住 / 记一下 / 以后要 / 保存规则 / 加到规范 / 写进 skill | 触发本 skill | +| 内容像「禁止/必须/约定」的短条款 | 写入或合并到 **Rule**（.mdc） | +| 内容像「流程/步骤/场景知识」 | 写入或合并到 **Skill**（SKILL.md） | +| 与现有某 rule/skill 同主题 | 优先**更新**该文件 | +| 写完后 | 说明写到了哪、以后如何生效 | diff --git a/.cursor/skills/ui-ux-pro-max/SKILL.md b/.cursor/skills/ui-ux-pro-max/SKILL.md new file mode 100644 index 0000000..2a553cb --- /dev/null +++ b/.cursor/skills/ui-ux-pro-max/SKILL.md @@ -0,0 +1,232 @@ +--- +name: ui-ux-pro-max +description: Searchable database of UI styles, color palettes, font pairings, chart types, product recommendations, UX guidelines, and stack-specific best practices +disable-model-invocation: true +--- + +# ui-ux-pro-max + +Searchable database of UI styles, color palettes, font pairings, chart types, product recommendations, UX guidelines, and stack-specific best practices. + +## Prerequisites + +Check if Python is installed: + +```bash +python3 --version || python --version +``` + +If Python is not installed, install it based on user's OS: + +**macOS:** +```bash +brew install python3 +``` + +**Ubuntu/Debian:** +```bash +sudo apt update && sudo apt install python3 +``` + +**Windows:** +```powershell +winget install Python.Python.3.12 +``` + +--- + +## How to Use This Workflow + +When user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow: + +### Step 1: Analyze User Requirements + +Extract key information from user request: +- **Product type**: SaaS, e-commerce, portfolio, dashboard, landing page, etc. +- **Style keywords**: minimal, playful, professional, elegant, dark mode, etc. +- **Industry**: healthcare, fintech, gaming, education, etc. +- **Stack**: React, Vue, Next.js, or default to `html-tailwind` + +### Step 2: Search Relevant Domains + +Use `search.py` multiple times to gather comprehensive information. Search until you have enough context. + +```bash +python3 .shared/ui-ux-pro-max/scripts/search.py "" --domain [-n ] +``` + +**Recommended search order:** + +1. **Product** - Get style recommendations for product type +2. **Style** - Get detailed style guide (colors, effects, frameworks) +3. **Typography** - Get font pairings with Google Fonts imports +4. **Color** - Get color palette (Primary, Secondary, CTA, Background, Text, Border) +5. **Landing** - Get page structure (if landing page) +6. **Chart** - Get chart recommendations (if dashboard/analytics) +7. **UX** - Get best practices and anti-patterns +8. **Stack** - Get stack-specific guidelines (default: html-tailwind) + +### Step 3: Stack Guidelines (Default: html-tailwind) + +If user doesn't specify a stack, **default to `html-tailwind`**. + +```bash +python3 .shared/ui-ux-pro-max/scripts/search.py "" --stack html-tailwind +``` + +Available stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter` + +--- + +## Search Reference + +### Available Domains + +| Domain | Use For | Example Keywords | +|--------|---------|------------------| +| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service | +| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism | +| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern | +| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service | +| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof | +| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie | +| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading | +| `prompt` | AI prompts, CSS keywords | (style name) | + +### Available Stacks + +| Stack | Focus | +|-------|-------| +| `html-tailwind` | Tailwind utilities, responsive, a11y (DEFAULT) | +| `react` | State, hooks, performance, patterns | +| `nextjs` | SSR, routing, images, API routes | +| `vue` | Composition API, Pinia, Vue Router | +| `svelte` | Runes, stores, SvelteKit | +| `swiftui` | Views, State, Navigation, Animation | +| `react-native` | Components, Navigation, Lists | +| `flutter` | Widgets, State, Layout, Theming | + +--- + +## Example Workflow + +**User request:** "Làm landing page cho dịch vụ chăm sóc da chuyên nghiệp" + +**AI should:** + +```bash +# 1. Search product type +python3 .shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --domain product + +# 2. Search style (based on industry: beauty, elegant) +python3 .shared/ui-ux-pro-max/scripts/search.py "elegant minimal soft" --domain style + +# 3. Search typography +python3 .shared/ui-ux-pro-max/scripts/search.py "elegant luxury" --domain typography + +# 4. Search color palette +python3 .shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness" --domain color + +# 5. Search landing page structure +python3 .shared/ui-ux-pro-max/scripts/search.py "hero-centric social-proof" --domain landing + +# 6. Search UX guidelines +python3 .shared/ui-ux-pro-max/scripts/search.py "animation" --domain ux +python3 .shared/ui-ux-pro-max/scripts/search.py "accessibility" --domain ux + +# 7. Search stack guidelines (default: html-tailwind) +python3 .shared/ui-ux-pro-max/scripts/search.py "layout responsive" --stack html-tailwind +``` + +**Then:** Synthesize all search results and implement the design. + +--- + +## Tips for Better Results + +1. **Be specific with keywords** - "healthcare SaaS dashboard" > "app" +2. **Search multiple times** - Different keywords reveal different insights +3. **Combine domains** - Style + Typography + Color = Complete design system +4. **Always check UX** - Search "animation", "z-index", "accessibility" for common issues +5. **Use stack flag** - Get implementation-specific best practices +6. **Iterate** - If first search doesn't match, try different keywords +7. **Split Into Multiple Files** - For better maintainability: + - Separate components into individual files (e.g., `Header.tsx`, `Footer.tsx`) + - Extract reusable styles into dedicated files + - Keep each file focused and under 200-300 lines + +--- + +## Common Rules for Professional UI + +These are frequently overlooked issues that make UI look unprofessional: + +### Icons & Visual Elements + +| Rule | Do | Don't | +|------|----|----- | +| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons | +| **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout | +| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths | +| **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly | + +### Interaction & Cursor + +| Rule | Do | Don't | +|------|----|----- | +| **Cursor pointer** | Add `cursor-pointer` to all clickable/hoverable cards | Leave default cursor on interactive elements | +| **Hover feedback** | Provide visual feedback (color, shadow, border) | No indication element is interactive | +| **Smooth transitions** | Use `transition-colors duration-200` | Instant state changes or too slow (>500ms) | + +### Light/Dark Mode Contrast + +| Rule | Do | Don't | +|------|----|----- | +| **Glass card light mode** | Use `bg-white/80` or higher opacity | Use `bg-white/10` (too transparent) | +| **Text contrast light** | Use `#0F172A` (slate-900) for text | Use `#94A3B8` (slate-400) for body text | +| **Muted text light** | Use `#475569` (slate-600) minimum | Use gray-400 or lighter | +| **Border visibility** | Use `border-gray-200` in light mode | Use `border-white/10` (invisible) | + +### Layout & Spacing + +| Rule | Do | Don't | +|------|----|----- | +| **Floating navbar** | Add `top-4 left-4 right-4` spacing | Stick navbar to `top-0 left-0 right-0` | +| **Content padding** | Account for fixed navbar height | Let content hide behind fixed elements | +| **Consistent max-width** | Use same `max-w-6xl` or `max-w-7xl` | Mix different container widths | + +--- + +## Pre-Delivery Checklist + +Before delivering UI code, verify these items: + +### Visual Quality +- [ ] No emojis used as icons (use SVG instead) +- [ ] All icons from consistent icon set (Heroicons/Lucide) +- [ ] Brand logos are correct (verified from Simple Icons) +- [ ] Hover states don't cause layout shift + +### Interaction +- [ ] All clickable elements have `cursor-pointer` +- [ ] Hover states provide clear visual feedback +- [ ] Transitions are smooth (150-300ms) +- [ ] Focus states visible for keyboard navigation + +### Light/Dark Mode +- [ ] Light mode text has sufficient contrast (4.5:1 minimum) +- [ ] Glass/transparent elements visible in light mode +- [ ] Borders visible in both modes +- [ ] Test both modes before delivery + +### Layout +- [ ] Floating elements have proper spacing from edges +- [ ] No content hidden behind fixed navbars +- [ ] Responsive at 320px, 768px, 1024px, 1440px +- [ ] No horizontal scroll on mobile + +### Accessibility +- [ ] All images have alt text +- [ ] Form inputs have labels +- [ ] Color is not the only indicator +- [ ] `prefers-reduced-motion` respected diff --git a/.gitignore b/.gitignore index 9c5e048..e4a8f8c 100644 --- a/.gitignore +++ b/.gitignore @@ -275,7 +275,7 @@ __pycache__/ *.zip # Cursor IDE files -.cursor/ +# .cursor/ # 排除无效的 Windows 风格路径（在 Mac 上出现） # 排除类似 /D:/wesley/project/git/antis-disk/netcore/src/Modular 的无效路径 diff --git a/antis-ncc-admin/.cursor/commands/ui-ux-pro-max.md b/antis-ncc-admin/.cursor/commands/ui-ux-pro-max.md new file mode 100644 index 0000000..04dd05f --- /dev/null +++ b/antis-ncc-admin/.cursor/commands/ui-ux-pro-max.md @@ -0,0 +1,226 @@ +# ui-ux-pro-max + +Searchable database of UI styles, color palettes, font pairings, chart types, product recommendations, UX guidelines, and stack-specific best practices. + +## Prerequisites + +Check if Python is installed: + +```bash +python3 --version || python --version +``` + +If Python is not installed, install it based on user's OS: + +**macOS:** +```bash +brew install python3 +``` + +**Ubuntu/Debian:** +```bash +sudo apt update && sudo apt install python3 +``` + +**Windows:** +```powershell +winget install Python.Python.3.12 +``` + +--- + +## How to Use This Workflow + +When user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow: + +### Step 1: Analyze User Requirements + +Extract key information from user request: +- **Product type**: SaaS, e-commerce, portfolio, dashboard, landing page, etc. +- **Style keywords**: minimal, playful, professional, elegant, dark mode, etc. +- **Industry**: healthcare, fintech, gaming, education, etc. +- **Stack**: React, Vue, Next.js, or default to `html-tailwind` + +### Step 2: Search Relevant Domains + +Use `search.py` multiple times to gather comprehensive information. Search until you have enough context. + +```bash +python3 .shared/ui-ux-pro-max/scripts/search.py "" --domain [-n ] +``` + +**Recommended search order:** + +1. **Product** - Get style recommendations for product type +2. **Style** - Get detailed style guide (colors, effects, frameworks) +3. **Typography** - Get font pairings with Google Fonts imports +4. **Color** - Get color palette (Primary, Secondary, CTA, Background, Text, Border) +5. **Landing** - Get page structure (if landing page) +6. **Chart** - Get chart recommendations (if dashboard/analytics) +7. **UX** - Get best practices and anti-patterns +8. **Stack** - Get stack-specific guidelines (default: html-tailwind) + +### Step 3: Stack Guidelines (Default: html-tailwind) + +If user doesn't specify a stack, **default to `html-tailwind`**. + +```bash +python3 .shared/ui-ux-pro-max/scripts/search.py "" --stack html-tailwind +``` + +Available stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter` + +--- + +## Search Reference + +### Available Domains + +| Domain | Use For | Example Keywords | +|--------|---------|------------------| +| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service | +| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism | +| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern | +| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service | +| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof | +| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie | +| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading | +| `prompt` | AI prompts, CSS keywords | (style name) | + +### Available Stacks + +| Stack | Focus | +|-------|-------| +| `html-tailwind` | Tailwind utilities, responsive, a11y (DEFAULT) | +| `react` | State, hooks, performance, patterns | +| `nextjs` | SSR, routing, images, API routes | +| `vue` | Composition API, Pinia, Vue Router | +| `svelte` | Runes, stores, SvelteKit | +| `swiftui` | Views, State, Navigation, Animation | +| `react-native` | Components, Navigation, Lists | +| `flutter` | Widgets, State, Layout, Theming | + +--- + +## Example Workflow + +**User request:** "Làm landing page cho dịch vụ chăm sóc da chuyên nghiệp" + +**AI should:** + +```bash +# 1. Search product type +python3 .shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --domain product + +# 2. Search style (based on industry: beauty, elegant) +python3 .shared/ui-ux-pro-max/scripts/search.py "elegant minimal soft" --domain style + +# 3. Search typography +python3 .shared/ui-ux-pro-max/scripts/search.py "elegant luxury" --domain typography + +# 4. Search color palette +python3 .shared/ui-ux-pro-max/scripts/search.py "beauty spa wellness" --domain color + +# 5. Search landing page structure +python3 .shared/ui-ux-pro-max/scripts/search.py "hero-centric social-proof" --domain landing + +# 6. Search UX guidelines +python3 .shared/ui-ux-pro-max/scripts/search.py "animation" --domain ux +python3 .shared/ui-ux-pro-max/scripts/search.py "accessibility" --domain ux + +# 7. Search stack guidelines (default: html-tailwind) +python3 .shared/ui-ux-pro-max/scripts/search.py "layout responsive" --stack html-tailwind +``` + +**Then:** Synthesize all search results and implement the design. + +--- + +## Tips for Better Results + +1. **Be specific with keywords** - "healthcare SaaS dashboard" > "app" +2. **Search multiple times** - Different keywords reveal different insights +3. **Combine domains** - Style + Typography + Color = Complete design system +4. **Always check UX** - Search "animation", "z-index", "accessibility" for common issues +5. **Use stack flag** - Get implementation-specific best practices +6. **Iterate** - If first search doesn't match, try different keywords +7. **Split Into Multiple Files** - For better maintainability: + - Separate components into individual files (e.g., `Header.tsx`, `Footer.tsx`) + - Extract reusable styles into dedicated files + - Keep each file focused and under 200-300 lines + +--- + +## Common Rules for Professional UI + +These are frequently overlooked issues that make UI look unprofessional: + +### Icons & Visual Elements + +| Rule | Do | Don't | +|------|----|----- | +| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons | +| **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout | +| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths | +| **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly | + +### Interaction & Cursor + +| Rule | Do | Don't | +|------|----|----- | +| **Cursor pointer** | Add `cursor-pointer` to all clickable/hoverable cards | Leave default cursor on interactive elements | +| **Hover feedback** | Provide visual feedback (color, shadow, border) | No indication element is interactive | +| **Smooth transitions** | Use `transition-colors duration-200` | Instant state changes or too slow (>500ms) | + +### Light/Dark Mode Contrast + +| Rule | Do | Don't | +|------|----|----- | +| **Glass card light mode** | Use `bg-white/80` or higher opacity | Use `bg-white/10` (too transparent) | +| **Text contrast light** | Use `#0F172A` (slate-900) for text | Use `#94A3B8` (slate-400) for body text | +| **Muted text light** | Use `#475569` (slate-600) minimum | Use gray-400 or lighter | +| **Border visibility** | Use `border-gray-200` in light mode | Use `border-white/10` (invisible) | + +### Layout & Spacing + +| Rule | Do | Don't | +|------|----|----- | +| **Floating navbar** | Add `top-4 left-4 right-4` spacing | Stick navbar to `top-0 left-0 right-0` | +| **Content padding** | Account for fixed navbar height | Let content hide behind fixed elements | +| **Consistent max-width** | Use same `max-w-6xl` or `max-w-7xl` | Mix different container widths | + +--- + +## Pre-Delivery Checklist + +Before delivering UI code, verify these items: + +### Visual Quality +- [ ] No emojis used as icons (use SVG instead) +- [ ] All icons from consistent icon set (Heroicons/Lucide) +- [ ] Brand logos are correct (verified from Simple Icons) +- [ ] Hover states don't cause layout shift + +### Interaction +- [ ] All clickable elements have `cursor-pointer` +- [ ] Hover states provide clear visual feedback +- [ ] Transitions are smooth (150-300ms) +- [ ] Focus states visible for keyboard navigation + +### Light/Dark Mode +- [ ] Light mode text has sufficient contrast (4.5:1 minimum) +- [ ] Glass/transparent elements visible in light mode +- [ ] Borders visible in both modes +- [ ] Test both modes before delivery + +### Layout +- [ ] Floating elements have proper spacing from edges +- [ ] No content hidden behind fixed navbars +- [ ] Responsive at 320px, 768px, 1024px, 1440px +- [ ] No horizontal scroll on mobile + +### Accessibility +- [ ] All images have alt text +- [ ] Form inputs have labels +- [ ] Color is not the only indicator +- [ ] `prefers-reduced-motion` respected -- libgit2 0.21.4