docs: 在 AGENTS.md 中深度细化各端与跨端最大化复用实施规范清单

AGENTS.md

@@ -62,7 +62,62 @@
 
 ---
 
-## 4. 核心研发铁律与协作原则 (Core Rules)
+## 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 定时任务引擎。
+   - 支付与通讯：涉及第三方支付或短信通知，优先复用官方插件。
+
+### 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)
 
 所有智能体与开发人员均需严格执行以下核心准则：
 
@@ -72,7 +127,7 @@
 2. **极简代码，最少代码实现功能**：
    - 代码必须保持极简纯粹，坚决拒绝过度设计和防御性冗余，以最精简高效的逻辑满足需求。
 3. **充分复用，拒绝重复造轮子**：
-   - 平台官方、组件库已有功能与生态成熟方案必须直接复用，禁止自行编写已有成熟解决方案的替代品。
+   - 严格执行第 4 节《全局最大化复用实施规范与清单》，平台官方、组件库已有功能与生态成熟方案必须直接复用。
 4. **先分析后动，风险最小化**：
    - 严禁盲目凭空推测或臆想代码。改动前必须深入调研已有代码、官方文档与依赖关系，制定明确方案后再行动，把代码风险降到最低。
 5. **Git 提交与干净代码**：