diff --git a/AGENTS.md b/AGENTS.md index 6464117..58b921c 100644 --- a/AGENTS.md +++ b/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. **原生高性能视图组件复用**: + - **长列表/无线加载**:一律复用 `` 与 `` 原生组件,严禁在常规 `` 中 v-for 渲染长列表,保证原生内存回收与 60fps 滚动。 + - **便当盒滑动/卡片轮播**:复用官方 ``,禁止用 touch 手势监听手写轮播。 + - **滚动容器**:复用 ``,充分利用其原生回弹与滚动事件。 +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 提交与干净代码**: