281 行
19 KiB
Markdown
281 行
19 KiB
Markdown
# OmniCard AI (CRMmp) - Agent & 开发者核心开发规范指引
|
||
|
||
> 本文档为 OmniCard AI 项目（全球智能数字名片 & 移动微官网 SaaS）的全局技术选型指南、架构规范与智能体 (Agent) 协作准则。所有开发协作与代码产出必须严格遵守本文档所列标准。
|
||
|
||
---
|
||
|
||
## 1. 项目基本概况 (Project Overview)
|
||
|
||
- **项目名称**：OmniCard AI (全球智能数字名片 & 移动微官网 SaaS)
|
||
- **远程仓库**：`https://gitcode.gynhc.com/wikiboss/OmniCard.git`
|
||
- **业务定位**：面向全球现代商务、跨国团队与专业顾问的新一代 **AI 驱动型智能名片 + 移动微官网 + 访客雷达 CRM + NFC 实体卡管理** 一体化平台。
|
||
- **业务核心模块**：
|
||
1. 微官网搭建与展示系统（Bento Grid 便当盒美学、响应式与 RTL 多语言适配）
|
||
2. 访客雷达与轻量级商务 CRM（国家定位、停留轨迹、意向度评分、线索跟进）
|
||
3. 智能中枢与在线商务顾问（全天候接待客商、智能留资、多语言地道润色）
|
||
4. NFC 实体卡硬件云端生命周期管理（场景切换、远程挂失）
|
||
5. 企业团队管理与多租户商业化订阅体系
|
||
|
||
---
|
||
|
||
## 2. 核心技术选型与端目录映射 (Tech Stack & Architecture)
|
||
|
||
项目严格采用以下官方推荐的现代化技术栈，根目录下各端工程严格对应独立子目录，严禁脱离官方语法规范进行非标开发：
|
||
|
||
| 端 / 层次 | 核心技术选型 | 项目目录 | 官方文档与资源 | 规范要点 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| **后端服务 (Backend API)** | **Cool-Admin (Node.js Midway 8.x)** | `backend/` | [https://node.cool-admin.com/](https://node.cool-admin.com/) | 基于 Midway.js + TypeScript + TypeORM。严格遵循 Cool-Admin 模块化规范（Entity / Controller / Service / Middleware），充分利用其权限、定时任务与插件生态。默认端口 9000，数据库 `crmmpdata`。 |
|
||
| **管理后台前端 (Admin Web)** | **React + Arco Design (Arco Pro Vite)** | `admin/` | [https://arco.design/react/docs/start](https://arco.design/react/docs/start) | 字节跳动企业级设计系统与 Arco Pro 标准中后台模板。界面严格沿用 Arco Design 官方规范与组件（Table, Form, Card, Modal, Grid 等），杜绝重复造轮子。默认端口 5173，反向代理 `/api` 至后端。 |
|
||
| **用户端应用 (User Client)** | **uni-app x (App 端 + H5 端)** | `mpuniapp/` | [https://doc.dcloud.net.cn/uni-app-x/](https://doc.dcloud.net.cn/uni-app-x/) | DCloud 下一代原生强类型跨端框架。统一采用 uts 语言与 Vue 3 规范；一套源码兼顾原生 Android/iOS App 与 Web/H5 版本，优先使用内置原生组件与 uni-ui。 |
|
||
| **系统设计与规划文档** | **PRD & UI/UX 规范** | `docs/` | - | 包含产品商业定位、6 大业务架构、分级订阅模型、Bento Grid 便当盒美学与设计规范文档。 |
|
||
|
||
### 2.1 物理目录映射与工程骨架 (Directory Tree)
|
||
|
||
```text
|
||
CRMmp/
|
||
├── backend/ # 【后端服务】Cool-Admin (Midway.js + TypeScript + TypeORM)
|
||
│ ├── src/
|
||
│ │ ├── configuration.ts # Midway 生命周期与 Cool-Admin 模块加载
|
||
│ │ ├── config/ # 多环境配置 (config.local.ts 中数据库为 crmmpdata)
|
||
│ │ └── modules/ # 官方模块 (base/dict/plugin/space/task/user) 与业务模块
|
||
│ └── package.json # 后端依赖管理与脚本 (npm run dev / build)
|
||
│
|
||
├── admin/ # 【管理后台前端】Arco Design Pro (React + Vite + TypeScript)
|
||
│ ├── src/
|
||
│ │ ├── layout.tsx # Arco Pro 企业级中后台统一骨架与导航
|
||
│ │ ├── routes.ts # 权限路由与侧边栏配置
|
||
│ │ ├── pages/ # 仪表盘、列表、表单、详情等典型中后台页面
|
||
│ │ └── locale/ # 中英文国际化语言包
|
||
│ ├── vite.config.ts # Vite 配置，端口 5173，代理 /api -> http://127.0.0.1:9000
|
||
│ └── package.json # 前端依赖管理与脚本 (npm run dev / build)
|
||
│
|
||
├── mpuniapp/ # 【用户端应用】uni-app x (App 端 + H5 端)
|
||
│ ├── pages/ # 访客端名片页、Bento Grid 便当盒微官网、AI 咨询浮层
|
||
│ ├── components/ # 跨端通用视图组件与 uni-ui 扩展
|
||
│ ├── App.uvue # 应用入口组件 (uts/uvue)
|
||
│ ├── main.uts # 入口 uts 脚本
|
||
│ ├── pages.json # 页面路由与全局样式配置
|
||
│ ├── manifest.json # 应用多端配置 (Android, iOS, Web/H5)
|
||
│ └── package.json # 客户端工程配置与依赖
|
||
│
|
||
├── docs/ # 【系统设计文档】PRD、UI/UX 规范等
|
||
├── AGENTS.md # 【核心开发规范与 Agent 协作准则】(本文档)
|
||
└── README.md # 【项目简介】
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 各端开发规范与准则 (Guidelines by Stack)
|
||
|
||
### 3.1 后端：Cool-Admin (Node.js) 规范 (目录: backend/)
|
||
- **架构范式**：严格遵循 Midway.js 依赖注入 (IoC) 与模块化结构设计。所有业务按业务域拆分为独立 Module（如 `modules/card`, `modules/crm`, `modules/ai`）。
|
||
- **实体与数据层 (TypeORM)**：
|
||
- 数据表字段使用下划线命名法，实体属性使用驼峰命名法。
|
||
- 合理声明索引（尤其是多租户 `tenant_id`、访客追踪 `visitor_id`）。
|
||
- 通用基类继承 `BaseEntity`，保持字段（创建时间、更新时间等）一致。
|
||
- **服务与控制器**：
|
||
- Controller 保持轻薄，负责入参校验、调用 Service、格式化返回。
|
||
- 复杂业务逻辑、事务处理一律封装在 Service 中。
|
||
- 充分利用 Cool-Admin 的 CRUD 装饰器，精简标准化增删改查。
|
||
|
||
### 3.2 管理后台前端：React + Arco Design 规范 (目录: admin/)
|
||
- **组件优先原则**：全面使用 Arco Design 官方组件库（`@arco-design/web-react`），包括表单布局、筛选面板、表格渲染、弹窗抽屉等。严禁自制低质量同类组件。
|
||
- **类型安全**：全面采用 TypeScript，严禁滥用 `any`。严格定义 Props 接口与服务端 API 响应契约。
|
||
- **状态与样式**：
|
||
- 遵循现代 React 最佳实践（Hooks、函数组件、避免多余状态冗余）。
|
||
- 优先复用 Arco 官方样式变量与工具类，保持设计一致性与国际高端商务调性。
|
||
|
||
### 3.3 用户端：uni-app x (App + H5) 规范 (目录: mpuniapp/)
|
||
- **语法与语言**：
|
||
- 严格按照 uni-app x 官方语法规范进行编码，采用 **uts 语言** (TypeScript 的强类型超集) 编写，遵守 uts 语法约束。
|
||
- 采用 Vue 3 `<script setup lang="uts">` 单文件组件 (SFC) 模式。
|
||
- **多端兼容 (App & H5)**：
|
||
- 确保同一套代码在原生 App 端 (uts 编译为原生 Kotlin/Swift) 与 Web/H5 端 (编译为 Web 标准) 均能稳定无差别运行。
|
||
- 跨平台差异逻辑必须使用条件编译（如 `#ifdef APP-ANDROID`、`#ifdef H5`）进行隔离，避免破坏端侧原生性能。
|
||
- **组件使用**：
|
||
- 尽可能沿用 uni-app x 官方内置组件（`<view>`, `<text>`, `<image>`, `<scroll-view>`, `<list-view>` 等）和 uni-ui 扩展。
|
||
- 页面排版优先采用 Flex 布局，保证不同屏幕比例与折叠屏设备的弹性适应。
|
||
|
||
---
|
||
|
||
## 4. 全局“能复用的尽可能复用”实施规范与清单 (Maximum Reuse Policy)
|
||
|
||
> **研发准则核心铁律**：写任何新代码或组件前，必须执行“三查原则”：
|
||
> 1. **查官方内置**：框架与官方生态是否已提供开箱即用能力？
|
||
> 2. **查已有基础**：项目中是否已有基类、通用 Hook 或公用工具？
|
||
> 3. **查标准规范**：是否已有成熟 RFC 规范或国际通用协议？
|
||
>
|
||
> **凡是已有成熟能力的，坚决杜绝重复造轮子，严禁手写超过 10 行的重复逻辑！**
|
||
|
||
### 4.1 后端 Cool-Admin 最大化复用清单
|
||
1. **标准化 CRUD 一键复用**：
|
||
- 凡通用后台数据表，一律复用 `@CoolController` 装饰器，自动获得 `page`, `list`, `info`, `add`, `update`, `delete` 标准 API，禁止手写无差别的增删改查 Controller 和 Service 方法。
|
||
2. **底层实体与元数据复用**：
|
||
- 业务 Entity 必须继承 `BaseEntity`（具备自动主键、创建时间、更新时间），软删除需求继承软删除基类。
|
||
3. **安全鉴权与中间件复用**：
|
||
- 复用 Cool-Admin 现成的 RBAC 角色权限体系（`@CoolTag`, `@CoolPermission`），禁止私自实现未经检验的重复鉴权逻辑。
|
||
4. **官方插件市场生态优先复用**：
|
||
- 文件与多媒体存储：直接复用官方 OSS/COS/Local 插件，严禁手写底层上传流。
|
||
- 缓存与任务：复用 Cool-Admin 官方 Redis 缓存装饰器与 Task 定时任务引擎。
|
||
- 支付与通讯：涉及第三方支付或短信通知，优先复用官方插件。
|
||
- 数据库 crmmpdata
|
||
|
||
### 4.2 管理后台前端 Arco Design (React) 最大化复用清单
|
||
1. **官方模板与中后台骨架复用**：
|
||
- 整体架构基于 Arco Pro 标准工程模式，复用其菜单导航、权限路由、浅色/深色主题切换与面包屑系统。
|
||
2. **官方高阶数据组件 100% 复用**：
|
||
- **表格 (Table)**：使用 `@arco-design/web-react` 的 `Table` 原生属性配置分页、排序、筛选、树形行和虚拟列表，禁止在外层手写自定义的分页器。
|
||
- **表单 (Form)**：使用 `Form`、`Form.Item` 及自带的校验规则（Rules），搭配 `Select`、`DatePicker`、`Upload`、`Cascader`，严禁使用原生 input/div 拼凑表单。
|
||
- **反馈交互**：所有交互提示统一调用 `Message`、`Notification`、`Modal`、`Drawer`、`Popconfirm`，严禁手写 CSS 蒙层或浮层。
|
||
- **图标库**：统一使用 `@arco-design/web-react/icon` 官方矢量图标库，禁止零散内嵌散乱的 SVG。
|
||
3. **通用 Hooks 与交互逻辑复用**：
|
||
- 抽象复用通用逻辑 Hook（例如 `useTablePagination`、`useFormModal`、`useAsyncState`），杜绝各页面重复编写 `loading`, `pagination`, `visible` 等样板代码。
|
||
|
||
### 4.3 用户端 uni-app x (App + H5) 最大化复用清单
|
||
1. **原生高性能视图组件复用**：
|
||
- **长列表/无线加载**：一律复用 `<list-view>` 与 `<list-item>` 原生组件，严禁在常规 `<view>` 中 v-for 渲染长列表，保证原生内存回收与 60fps 滚动。
|
||
- **便当盒滑动/卡片轮播**：复用官方 `<swiper>`，禁止用 touch 手势监听手写轮播。
|
||
- **滚动容器**：复用 `<scroll-view>`，充分利用其原生回弹与滚动事件。
|
||
2. **官方生态 uni-ui 扩展复用**：
|
||
- 弹层浮层复用 `uni-popup`；卡片容器复用 `uni-card`；搜索栏复用 `uni-search-bar`；徽标复用 `uni-badge`，杜绝重复手写跨端差异大的样式组件。
|
||
3. **跨平台原生 API 复用**：
|
||
- 网络请求复用 `uni.request`（配合全局统一拦截器）。
|
||
- 本地持久化复用 `uni.getStorage` / `uni.setStorage`。
|
||
- 提示与对话框复用 `uni.showToast`、`uni.showModal`、`uni.showLoading`。
|
||
- 设备能力复用 `uni.setClipboardData`、`uni.makePhoneCall`、`uni.scanCode`。
|
||
|
||
### 4.4 跨端契约与数据模型复用 (End-to-End Reusability)
|
||
1. **统一数据模型 (Data Models)**：
|
||
- 核心数据契约（名片信息 `CardProfile`、访客轨迹 `VisitorTrack`、雷达评分 `RadarScore`、商机状态 `LeadStatus` 等）保持字段、枚举与类型一致，后端 DTO 与前端/客户端 Type 必须镜像对应。
|
||
2. **国际通用标准复用**：
|
||
- 电子名片导出与导入严格遵循 **vCard (RFC 6350)** 国际通用标准，复用成熟解析与生成算法，拒绝私有格式。
|
||
3. **多语言 (i18n) 字典统一复用**：
|
||
- 统一全端通用词条 key（如 `common.confirm`, `common.cancel`, `card.save_contact`, `radar.online`），跨端共用词典映射。
|
||
|
||
---
|
||
|
||
## 5. 核心研发铁律与协作原则 (Core Rules)
|
||
|
||
所有智能体与开发人员均需严格执行以下核心准则：
|
||
|
||
1. **测试驱动开发 (TDD 模式)**：
|
||
- 核心业务逻辑与 API 接口必须严格践行 TDD 流程：**编写测试用例 (Red) ➔ 最简代码实现 (Green) ➔ 优化重构 (Refactor)**。
|
||
- 保证关键路径与业务边界有完备的自动化单元测试/集成测试覆盖。
|
||
2. **极简代码，最少代码实现功能**：
|
||
- 代码必须保持极简纯粹，坚决拒绝过度设计和防御性冗余，以最精简高效的逻辑满足需求。
|
||
3. **充分复用，拒绝重复造轮子**：
|
||
- 严格执行第 4 节《全局最大化复用实施规范与清单》，平台官方、组件库已有功能与生态成熟方案必须直接复用。
|
||
4. **先分析后动，风险最小化**：
|
||
- 严禁盲目凭空推测或臆想代码。改动前必须深入调研已有代码、官方文档与依赖关系，制定明确方案后再行动，把代码风险降到最低。
|
||
5. **Git 提交与干净代码**：
|
||
- 提交 Git 时必须包含**清晰规范的中文说明**（采用形如 `feat:`, `fix:`, `docs:`, `refactor:`, `test:` 规范）。
|
||
- 保证推送到远端的代码干净无杂质（严禁提交临时调试文件、无用日志打印或未验证代码）。
|
||
6. **全局中文交流与文档**：
|
||
- 团队内部交互、设计文档、代码注释及任务汇报均统一采用中文描述。
|
||
- md，测试脚本，等归档存储
|
||
|
||
|
||
更新版，已把**风格约束**一起并入 AI Coding 约束。可直接放入 `.cursorrules` / `CLAUDE.md`。
|
||
|
||
```md
|
||
# OmniCard AI — AI Coding & UI/UX 核心设计约束
|
||
|
||
## 1. 风格定位 (Aesthetic & Style)
|
||
- **Bento Grid（便当盒美学）模组化布局 + 现代消费级全球化 SaaS（Consumerized B2B SaaS）**
|
||
- **场景优先（Context-First）**：移动端名片出示场景采用**沉浸式全屏大二维码展台** + **底部大圆角浮层抽屉（Bottom Sheet）**，物理 NFC 实体卡与数字名片具象化联动
|
||
- **极简科技纯净感**：中性冷白底色为主，辅以科技天蓝与局部极光弥散微光晕（Ambient Aurora / Mesh Gradient）
|
||
- **全球现代商务**：可信、现代、通透、高呼吸感与留白，杜绝冰冷传统表单后台感
|
||
- **一屏仅允许 1 个核心主 CTA**（悬浮胶囊式或居中凸起发送快捷按钮）
|
||
|
||
## 2. 设计 Token (Design Tokens - 必须引用，禁止硬编码)
|
||
颜色 Light / Dark：
|
||
- primary: #0088FF / #3894FF（科技天蓝/钴蓝）
|
||
- primary-gradient: linear-gradient(135deg, #00A3FF 0%, #0B63E5 100%)
|
||
- primary-soft: #EBF5FF / #0D2847
|
||
- aurora: linear-gradient(135deg, #00D2FF 0%, #0088FF 50%, #6366F1 100%)（极光弥散）
|
||
- bg: #F5F8FC / #0B0D10（冷白天幕底色）
|
||
- surface: #FFFFFF / #13171F（纯白卡片容器）
|
||
- border: #EBF1F7 / #232936（极浅分割微线）
|
||
- text: #101828 / #F2F4F7（主内容高对比）
|
||
- text-2: #64748B / #94A3B8（次级说明文字）
|
||
- success: #12B76A / #32D583
|
||
- warning: #F79009 / #FDB022
|
||
- error: #F04438 / #F97066
|
||
|
||
间距：4 / 8 / 12 / 16 / 20 / 24 / 32 / 48 / 64
|
||
平滑大圆角 (Squircle)：
|
||
- 按钮与胶囊标签: 14px / 9999px (Pill)
|
||
- Bento 卡片与内容容器: 20px / 24px
|
||
- 移动端底部抽屉与模态面板: 顶角 24px / 28px
|
||
- 二维码展台卡片: 20px
|
||
漫反射环境软阴影 (Ambient Soft Shadow)：
|
||
- shadow-card: 0 8px 30px rgba(0, 0, 0, 0.04), 0 2px 8px rgba(11, 99, 229, 0.03)
|
||
- shadow-cta: 0 8px 20px rgba(0, 136, 255, 0.22)
|
||
- shadow-float: 0 12px 36px rgba(16, 24, 40, 0.08)
|
||
字体：Inter, Noto Sans SC, Noto Sans Arabic, Noto Sans JP, Noto Sans KR, SF Pro Display
|
||
字号：12 / 14 / 16 / 18 / 20 / 24 / 32 / 40
|
||
行高：正文 1.6，标题 1.25，阿语 1.7
|
||
最大宽度：内容 1200px，文章 720px，移动端自适应 480px
|
||
行宽：45–75 字符
|
||
|
||
## 3. 配色与光影规则
|
||
- **比例原则**：纯净冷白与中性色占 85%–90%，品牌科技蓝占 10%–15%
|
||
- **受控弥散光晕**：极光渐变（Aurora）仅限局部高价值区域（沉浸式展示头部、品牌卡、NFC 实体卡演示位、雷达高光），面积 < 8%，禁止全屏杂乱渐变
|
||
- **环境软阴影**：以超大半径、极淡漫反射阴影营造卡片微悬浮感，替代厚重硬边框
|
||
- **语义色只用于状态**：成功绿、警告橙、错误红仅用于雷达意向度、系统状态与验证提示，不做大面积装饰
|
||
- **NFC 反馈**：触碰感应触发主色 20% 透明单次微脉冲动效，时长 400ms，不循环
|
||
|
||
## 4. 核心组件与交互规范
|
||
- **Bento Grid 模组规范**：各卡片高度内聚自洽（趋势折线图、访客雷达通知条、个人 Profile、NFC 硬件状态、隐私时效控制），网格弹性响应
|
||
- **移动端沉浸展台模式 (Showcase Mode)**：
|
||
- 顶部占屏约 45% 的科技蓝/极光底色，大号高清晰二维码居中直出，配 `Scan to share card` 微光引导
|
||
- 底部大圆角抽屉 (Bottom Sheet) 承载：一键复制直链栏（直链 + `COPY` 胶囊）、绿色可持续发展理念文案、实体白卡拟物微轮播
|
||
- 底部悬浮 TabBar：Contacts、Share（主 CTA 胶囊凸起微阴影）、Privacy
|
||
- **访客雷达实时动态通知条**：
|
||
- 采用轻微圆角悬浮条（如 "Alex saved your contact card Just Now"），左侧品牌 Logo/头像，白底轻投影
|
||
- **隐私时效控制控件**：
|
||
- 结构化时效行（Temporary Visibility / Extended Visibility）搭配平滑展开行与单选/滑块
|
||
- **按钮与触控区**：高度 40 / 44 / 48，触控热区 ≥ 44×44，悬停仅 2–4% 明暗微变化，不放大
|
||
- **图标体系**：统一 1.5px 极细线性图标，规格 20 / 24px
|
||
|
||
## 5. 动效规范
|
||
- 微交互 150ms，抽屉滑出/收起 250ms，页面转场 350ms
|
||
- 缓动：cubic-bezier(0.2, 0.8, 0.2, 1)
|
||
- 极光微光晕呼吸缓慢流动，支持 prefers-reduced-motion
|
||
- AI 采用微光晕浮现，不以打字机作为单一阻塞反馈
|
||
|
||
## 6. 代码与工程规范
|
||
- 严格 TypeScript / uts，严禁使用 any
|
||
- 组件 PascalCase，函数式，统一使用设计 Token，严禁内联魔法值
|
||
- 所有文案必须走 i18n key，禁止硬编码文字
|
||
- 支持暗色模式，采用 CSS/UTS 主题变量
|
||
- 支持 RTL，一律采用逻辑属性（ms / me / ps / pe）
|
||
- 语义化标签 + 键盘可达 + 无障碍 aria 规范
|
||
|
||
## 7. 国际化与全球合规标准
|
||
- 国际多语言优先（默认 en，支持多语言独立路由或上下文切换）
|
||
- 国际主流社交一键触达：WhatsApp、LinkedIn、Telegram、Line、KakaoTalk、WeChat
|
||
- 支付与协议：Stripe、PayPal，名片遵循 vCard (RFC 6350)
|
||
- 合规：GDPR、CCPA、Cookie 同意、隐私时效自毁
|
||
- WCAG 2.2 AA 标准，文本对比度 ≥ 4.5:1
|
||
|
||
## 8. 禁止事项 (Strictly Prohibited)
|
||
- 严禁使用纯黑 #000
|
||
- 严禁生硬、灰暗、传统冷冰冰的表单式名片页（禁止将二维码埋入杂乱表单角中）
|
||
- 严禁大面积土味高饱和霓虹渐变、重阴影与过度玻璃拟态
|
||
- 严禁超过 3 种字体
|
||
- 严禁硬编码文案、固定宽度按钮
|
||
- 严禁强制登录才可浏览名片，严禁自动播放声音
|
||
- 严禁一屏出现多个主按钮
|
||
- 严禁装饰性插画、拟物大图标与特定文化敏感符号
|
||
- 严禁在正式生产界面中使用非业务硬编码 emoji
|
||
```
|
||
|
||
### 翻译要求
|
||
你是 App 界面本地化翻译引擎。任务不是逐字翻译，而是把源文案改写为目标语言用户在真实产品界面中会看到的自然表达。
|
||
|
||
总原则：
|
||
- 保义不保形：保留功能、意图、语气、情绪和操作结果，按目标语言习惯重组语序和表达。
|
||
- 像原生文案：读起来像目标语言产品自己写的，不像翻译。
|
||
- 上下文优先：按钮、标题、提示、错误、空状态、通知、设置项等，按场景决定用词和长度。
|
||
|