OmniCard AI (CRMmp) - Agent & 开发者核心开发规范指引

本文档为 OmniCard AI 项目（全球智能数字名片 & 移动微官网 SaaS）的全局技术选型指南、架构规范与智能体 (Agent) 协作准则。所有开发协作与代码产出必须严格遵守本文档所列标准。

1. 项目基本概况 (Project Overview)

项目名称：OmniCard AI (全球智能数字名片 & 移动微官网 SaaS)
业务定位：面向全球商务出海的下一代 AI 驱动型智能名片 + 移动微官网 + 访客雷达 CRM + NFC 实体卡管理 一体化平台。
业务核心模块：
1. 微官网搭建与展示系统（Bento Grid 便当盒美学、响应式与 RTL 多语言适配）
2. 访客雷达与轻量级出海 CRM（国家定位、停留轨迹、意向度评分、线索跟进）
3. AI 智能中枢与数字人顾问（全天候接待客商、智能留资、多语言地道润色）
4. NFC 实体卡硬件云端生命周期管理（场景切换、远程挂失）
5. 企业团队管理与多租户商业化订阅体系

2. 核心技术选型 (Tech Stack)

项目严格采用以下官方推荐的现代化技术栈，严禁脱离官方语法规范进行非标开发：

端 / 层次	核心技术选型	官方文档与资源	规范要点
后端服务 (Backend API)	Cool-Admin (Node.js)	https://node.cool-admin.com/	基于 Midway.js + TypeScript + TypeORM。严格遵循 Cool-Admin 模块化规范（Entity / Controller / Service / Middleware），充分利用其权限、定时任务与插件生态。
管理后台前端 (Admin Web)	React + Arco Design	https://arco.design/react/docs/start	字节跳动企业级设计系统。界面严格沿用 Arco Design 官方规范与组件（Table, Form, Card, Modal, Grid 等），杜绝重复造轮子。
用户端 (User Client)	uni-app x (App 端 + H5 端)	https://doc.dcloud.net.cn/uni-app-x/	DCloud 下一代原生强类型跨端框架。统一采用 uts 语言与 Vue 3 规范；一套源码兼顾原生 Android/iOS App 与 Web/H5 版本，优先使用内置原生组件与 uni-ui。

3. 各端开发规范与准则 (Guidelines by Stack)

3.1 后端：Cool-Admin (Node.js) 规范

架构范式：严格遵循 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 规范

组件优先原则：全面使用 Arco Design 官方组件库（@arco-design/web-react），包括表单布局、筛选面板、表格渲染、弹窗抽屉等。严禁自制低质量同类组件。
类型安全：全面采用 TypeScript，严禁滥用 any。严格定义 Props 接口与服务端 API 响应契约。
状态与样式：
- 遵循现代 React 最佳实践（Hooks、函数组件、避免多余状态冗余）。
- 优先复用 Arco 官方样式变量与工具类，保持设计一致性与出海高端商务调性。

3.3 用户端：uni-app x (App + H5) 规范

语法与语言：
- 严格按照 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)

研发准则核心铁律：写任何新代码或组件前，必须执行“三查原则”：

查官方内置：框架与官方生态是否已提供开箱即用能力？

查已有基础：项目中是否已有基类、通用 Hook 或公用工具？

查标准规范：是否已有成熟 RFC 规范或国际通用协议？

凡是已有成熟能力的，坚决杜绝重复造轮子，严禁手写超过 10 行的重复逻辑！

4.1 后端 Cool-Admin 最大化复用清单

标准化 CRUD 一键复用：
- 凡通用后台数据表，一律复用 @CoolController 装饰器，自动获得 page, list, info, add, update, delete 标准 API，禁止手写无差别的增删改查 Controller 和 Service 方法。
底层实体与元数据复用：
- 业务 Entity 必须继承 BaseEntity（具备自动主键、创建时间、更新时间），软删除需求继承软删除基类。
安全鉴权与中间件复用：
- 复用 Cool-Admin 现成的 RBAC 角色权限体系（@CoolTag, @CoolPermission），禁止私自实现未经检验的重复鉴权逻辑。
官方插件市场生态优先复用：
- 文件与多媒体存储：直接复用官方 OSS/COS/Local 插件，严禁手写底层上传流。
- 缓存与任务：复用 Cool-Admin 官方 Redis 缓存装饰器与 Task 定时任务引擎。
- 支付与通讯：涉及第三方支付或短信通知，优先复用官方插件。
- 数据库 crmmpdata

4.2 管理后台前端 Arco Design (React) 最大化复用清单

官方模板与中后台骨架复用：
- 整体架构基于 Arco Pro 标准工程模式，复用其菜单导航、权限路由、浅色/深色主题切换与面包屑系统。
官方高阶数据组件 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。
通用 Hooks 与交互逻辑复用：
- 抽象复用通用逻辑 Hook（例如 useTablePagination、useFormModal、useAsyncState），杜绝各页面重复编写 loading, pagination, visible 等样板代码。

4.3 用户端 uni-app x (App + H5) 最大化复用清单

原生高性能视图组件复用：
- 长列表/无线加载：一律复用 <list-view> 与 <list-item> 原生组件，严禁在常规 <view> 中 v-for 渲染长列表，保证原生内存回收与 60fps 滚动。
- 便当盒滑动/卡片轮播：复用官方 <swiper>，禁止用 touch 手势监听手写轮播。
- 滚动容器：复用 <scroll-view>，充分利用其原生回弹与滚动事件。
官方生态 uni-ui 扩展复用：
- 弹层浮层复用 uni-popup；卡片容器复用 uni-card；搜索栏复用 uni-search-bar；徽标复用 uni-badge，杜绝重复手写跨端差异大的样式组件。
跨平台原生 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)

统一数据模型 (Data Models)：
- 核心数据契约（名片信息 CardProfile、访客轨迹 VisitorTrack、雷达评分 RadarScore、商机状态 LeadStatus 等）保持字段、枚举与类型一致，后端 DTO 与前端/客户端 Type 必须镜像对应。
国际通用标准复用：
- 电子名片导出与导入严格遵循 vCard (RFC 6350) 国际通用标准，复用成熟解析与生成算法，拒绝私有格式。
多语言 (i18n) 字典统一复用：
- 统一全端通用词条 key（如 common.confirm, common.cancel, card.save_contact, radar.online），跨端共用词典映射。

5. 核心研发铁律与协作原则 (Core Rules)

所有智能体与开发人员均需严格执行以下核心准则：

测试驱动开发 (TDD 模式)：
- 核心业务逻辑与 API 接口必须严格践行 TDD 流程：编写测试用例 (Red) ➔ 最简代码实现 (Green) ➔ 优化重构 (Refactor)。
- 保证关键路径与业务边界有完备的自动化单元测试/集成测试覆盖。
极简代码，最少代码实现功能：
- 代码必须保持极简纯粹，坚决拒绝过度设计和防御性冗余，以最精简高效的逻辑满足需求。
充分复用，拒绝重复造轮子：
- 严格执行第 4 节《全局最大化复用实施规范与清单》，平台官方、组件库已有功能与生态成熟方案必须直接复用。
先分析后动，风险最小化：
- 严禁盲目凭空推测或臆想代码。改动前必须深入调研已有代码、官方文档与依赖关系，制定明确方案后再行动，把代码风险降到最低。
Git 提交与干净代码：
- 提交 Git 时必须包含清晰规范的中文说明（采用形如 feat:, fix:, docs:, refactor:, test: 规范）。
- 保证推送到远端的代码干净无杂质（严禁提交临时调试文件、无用日志打印或未验证代码）。
全局中文交流与文档：
- 团队内部交互、设计文档、代码注释及任务汇报均统一采用中文描述。

更新版，已把风格约束一起并入 AI Coding 约束。可直接放入 .cursorrules / CLAUDE.md。

# NexaCard AI — AI Coding 约束

## 风格定位
- 瑞士国际主义 + 现代 SaaS + 编辑感
- 内容优先，留白即品牌，AI 隐形，CRM 无感，NFC 轻量
- 全球商务、中性、可信、克制
- 禁止炫技、拟物、霓虹、玻璃拟态、重装饰
- 一屏只允许 1 个主 CTA

## 技术栈
- Next.js + TypeScript + Tailwind + shadcn/ui
- 移动端：Expo / React Native
- 状态：Zustand + TanStack Query
- 表单：react-hook-form + zod
- 国际化：next-intl
- 测试：Vitest + Playwright

## 设计 Token（必须引用，禁止硬编码）
颜色 Light / Dark：
- primary: #0B5CFF / #4D8DFF
- primary-soft: #EAF1FF / #102A4D
- ai: #7C5CFF / #9B8CFF
- bg: #FFFFFF / #0B0D10
- surface: #F7F8FA / #12151A
- border: #E3E7ED / #262B33
- text: #101828 / #F2F4F7
- text-2: #667085 / #98A2B3
- success: #12B76A / #32D583
- warning: #F79009 / #FDB022
- error: #F04438 / #F97066

间距：4 / 8 / 12 / 16 / 24 / 32 / 48 / 64
圆角：按钮 12px，卡片 16px，模态 20px
阴影：0 1px 2px rgba(16,24,40,0.04)
字体：Inter, Noto Sans SC, Noto Sans Arabic, Noto Sans JP, Noto Sans KR
字号：12 / 14 / 16 / 20 / 24 / 32 / 40
行高：正文 1.6，标题 1.25，阿语 1.7
最大宽度：内容 1200px，文章 720px
行宽：45–75 字符

## 配色规则
- 中性色占 80–90%，品牌色占 10–20%
- 品牌主色只用单一钴蓝
- 语义色只用于状态，不做装饰
- 禁止红、绿、黄作为品牌主色
- AI 渐变只允许小面积，面积 <5%
- NFC 用主色 20% 透明脉冲，一次 400ms，不循环

## 组件规则
- 按钮高 40 / 44 / 48，触控区 ≥44×44
- 输入框高 44，标签在上，错误在下
- 卡片 1px 边框，圆角 16，无重阴影
- 卡片最多两层嵌套，优先用分隔线
- 图标线性 1.5px，20 / 24px
- 焦点环 2px primary，offset 2，必须可见
- 加载优先骨架屏
- 空状态：一句话 + 一个主 CTA
- 悬停仅 2–4% 明暗变化，不放大

## 动效
- 微交互 150ms，抽屉 250ms，页面 400ms
- 缓动：cubic-bezier(0.2, 0.8, 0.2, 1)
- 支持 prefers-reduced-motion
- AI 用微光，不用打字机作为唯一反馈
- NFC 用一次脉冲，不循环

## 代码规范
- 严格 TypeScript，禁止 any
- 组件 PascalCase，函数式
- 样式只用 Tailwind，禁止内联 style
- 所有文案走 i18n key，禁止硬编码
- 颜色 / 间距 / 字体必须用 token，禁止魔法值
- 支持暗色模式，用 CSS 变量
- 支持 RTL，用 logical properties（ms / me / ps / pe）
- 语义化标签 + aria + 键盘可达
- 动效必须支持 reduced-motion

## 国际化
- next-intl，默认 en
- 独立 URL：/en /es /fr
- hreflang + sitemap
- 日期 / 货币 / 时区本地化
- 按钮和标签预留 30% 文本扩展
- 社交适配：WhatsApp、LinkedIn、Telegram、Line、KakaoTalk、微信
- 支付：Stripe、PayPal
- GDPR、CCPA、Cookie 同意、数据导出 / 删除
- WCAG 2.2 AA，正文对比度 ≥ 4.5:1
- 不强制登录看名片，不自动播放声音

## 禁止
- 纯黑 #000
- 超过 3 种字体
- 大面积渐变 / 重阴影 / 霓虹
- 硬编码文案或颜色
- 固定宽度按钮
- 强制登录看名片
- 自动播放声音
- 一屏多个主按钮
- 装饰性插画 / 拟物图标 / 文化特定符号
- 禁止使用emoji

14 KiB 原始文件 Blame 文件历史 Unescape Escape

OmniCard AI (CRMmp) - Agent & 开发者核心开发规范指引

1. 项目基本概况 (Project Overview)

2. 核心技术选型 (Tech Stack)

3. 各端开发规范与准则 (Guidelines by Stack)

3.1 后端：Cool-Admin (Node.js) 规范

3.2 管理后台前端：React + Arco Design 规范

3.3 用户端：uni-app x (App + H5) 规范

4. 全局“能复用的尽可能复用”实施规范与清单 (Maximum Reuse Policy)

4.1 后端 Cool-Admin 最大化复用清单

4.2 管理后台前端 Arco Design (React) 最大化复用清单

4.3 用户端 uni-app x (App + H5) 最大化复用清单

4.4 跨端契约与数据模型复用 (End-to-End Reusability)

5. 核心研发铁律与协作原则 (Core Rules)

14 KiB

原始文件 Blame 文件历史