From 928a8d0cf618bffcb64428c19b8ae6ad0bc69759 Mon Sep 17 00:00:00 2001
From: wikiboss <zacow@163.com>
Date: Sun, 20 Sep 2026 16:17:44 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E7=A1=AE=E7=AB=8B=E7=B3=BB=E7=BB=9F?=
 =?UTF-8?q?=E6=8A=80=E6=9C=AF=E9=80=89=E5=9E=8B=E4=B8=8E=E7=A0=94=E5=8F=91?=
 =?UTF-8?q?=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=A3=20(Cool-Admin=20/=20Arco?=
 =?UTF-8?q?=20Design=20React=20/=20uni-app=20x)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md | 14 ++++++----
 2 files changed, 90 insertions(+), 6 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e69de29..6464117 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,82 @@
+# 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/](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](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/](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. 核心研发铁律与协作原则 (Core Rules)
+
+所有智能体与开发人员均需严格执行以下核心准则：
+
+1. **测试驱动开发 (TDD 模式)**：
+   - 核心业务逻辑与 API 接口必须严格践行 TDD 流程：**编写测试用例 (Red) ➔ 最简代码实现 (Green) ➔ 优化重构 (Refactor)**。
+   - 保证关键路径与业务边界有完备的自动化单元测试/集成测试覆盖。
+2. **极简代码，最少代码实现功能**：
+   - 代码必须保持极简纯粹，坚决拒绝过度设计和防御性冗余，以最精简高效的逻辑满足需求。
+3. **充分复用，拒绝重复造轮子**：
+   - 平台官方、组件库已有功能与生态成熟方案必须直接复用，禁止自行编写已有成熟解决方案的替代品。
+4. **先分析后动，风险最小化**：
+   - 严禁盲目凭空推测或臆想代码。改动前必须深入调研已有代码、官方文档与依赖关系，制定明确方案后再行动，把代码风险降到最低。
+5. **Git 提交与干净代码**：
+   - 提交 Git 时必须包含**清晰规范的中文说明**（采用形如 `feat:`, `fix:`, `docs:`, `refactor:`, `test:` 规范）。
+   - 保证推送到远端的代码干净无杂质（严禁提交临时调试文件、无用日志打印或未验证代码）。
+6. **全局中文交流与文档**：
+   - 团队内部交互、设计文档、代码注释及任务汇报均统一采用中文描述。
diff --git a/README.md b/README.md
index 9e146d9..17bc34f 100644
--- a/README.md
+++ b/README.md
@@ -31,10 +31,12 @@
 
 ---
 
-## 🛠 推荐技术栈选型
+## 🛠 正式技术栈选型与规范
+
+详见核心开发指引：**[AGENTS.md](./AGENTS.md)**
+
+- **后端服务 (Backend)**：[Cool-Admin (Node.js)](https://node.cool-admin.com/)（基于 Midway.js + TypeScript + TypeORM）
+- **管理后台前端 (Admin Web)**：[Arco Design React](https://arco.design/react/docs/start)（字节跳动企业级设计系统）
+- **用户多端应用 (User App & H5)**：[uni-app x](https://doc.dcloud.net.cn/uni-app-x/)（DCloud 原生强类型 uts 跨端引擎，兼顾 App 和 H5）
+- **开发与交付原则**：严格 TDD 测试驱动开发、严格官方语法规范、组件高复用、极简干净代码。
 
-- **微官网渲染层 (Visitor Portal)**：Next.js / SvelteKit (极致 SSR/SSG，边缘计算 CDN，秒开体验)
-- **多端应用管理层 (Admin App)**：React Native / Flutter 或 PWA (iOS / Android / Web 统一响应式)
-- **后端与数据库**：Node.js (NestJS) / Go + PostgreSQL (Supabase) + Redis 缓存
-- **AI 基础设施**：大语言模型 API + 向量数据库 (pgvector) 实现知识库 RAG
-- **国际支付体系**：Stripe Billing (支持多币种与订阅周期)