coreeb-fullstack

COREEB — 技能

优先级

简洁性 > 可读性 > 可维护性 > 可复用性 > 一致性。 最简单的解决方案几乎总是正确的。

---

最高指令

• 前端： Next.js (App Router)。
• 架构： 采用 4 层模块化结构（路由、模块、全局 UI、基础设施）。
• UI： 仅使用 coreeb 库。创建任何组件前，始终先在 coreeb 中查找。该库已在内部包含 Tailwind CSS。
• 包管理器： 仅使用 pnpm。绝不使用 npm 或 yarn。
• 预先验证依赖： 在开始编写任何代码文件之前，Agent 必须检查根目录中的 package.json 文件。如果缺少必需的依赖项（coreeb、sonner、tw-animate-css、axios），Agent 必须先通过 pnpm add 自动安装这些依赖项，再执行其他任务。
• 页面样式要求： 每个页面、视图、表单和子组件都必须使用 coreeb 组件构建。不得使用其他 UI 库或内联样式。

重要

UI 规则：

1. coreeb 优先且唯一 — 如果 coreeb 中存在满足需求的组件，就必须使用。该库已包含 Tailwind CSS。
2. 仅在最后手段下使用自定义 CSS — 只能用于 coreeb 无法满足的特殊情况（例如 .custom-scrollbar）。

---

开发规则

架构

• 严格遵循现有项目结构。
• 不要创建新的文件夹，也不要更改项目组织结构。
• 不要引入当前未使用的设计模式。
• 创建新内容之前，先确认是否已有可复用的内容。

组件

• 组件只负责渲染。组件内部不得包含任何业务逻辑。
• 组件应当小巧、易读且易于维护。
• 如果组件开始包含越来越多的逻辑，应立即将逻辑移至对应的 Hook。

Hooks

• 每个组件都应有专属的 Hook。
• 所有逻辑都放在 Hook 中：状态、处理函数、副作用、计算、派生值、服务调用。
• Hook 应保持简单。如果 Hook 变得过于庞大，应拆分其职责。
• 所有 Hook 都必须做好与真实后端集成的准备。

服务

• 所有数据都必须通过服务获取（模块中的 lib/api/ 或全局的 src/lib/api/）。
• 绝不从组件或 Hook 直接发起 HTTP 请求。
• 服务负责调用 API、获取或发送数据，以及转换响应。
• 即使初期使用模拟数据，结构也必须做好接入真实后端的准备。

类型

• 每种类型都应放在 types/ 文件夹中的 index.ts 文件内。
• 模块本地类型放在 src/modules/[module]/[action]/lib/types/index.ts。
• 全局共享类型放在 src/lib/types/index.ts。

代码

• 明确胜于“聪明”。
• 函数要小、文件要小、名称要有描述性。
• 不要使用过于通用的函数，不要进行不必要的抽象，也不要过早优化。

复用

创建任何新内容之前，先确认是否已有可复用的内容，尤其是： 按钮、表格、输入框、选择框、模态框、卡片、徽章、分页、对话框、空状态、加载器、警告提示、共享组件。 始终先复用，再创建。

模块隔离

• 不要修改请求范围之外的任何模块。
• 只在请求指定的模块内操作。
• 不要进行超出任务范围的重构。

后端就绪

• 服务应当能够轻松地将模拟数据替换为真实 API 调用。
• UI 绝不能依赖硬编码数据。

库

• 使用现有库：Axios（通过 apiClient.ts）、date-fns。
• 除非确有必要且获得授权，否则不要安装新依赖。
• 始终使用 pnpm 管理软件包。

语言

所有代码都必须使用英语编写：变量、函数、接口、类型、枚举、组件、hooks、服务、文件夹、文件。 面向用户显示的文本可以使用项目所用的语言。

注释

不要编写注释。 应通过良好的命名和组织使代码能够自我说明。

---

✅ 生成代码前的检查清单

• coreeb 中是否已有满足需求的组件？
• 项目中是否已有可复用组件？
• 是否已有可复用的 hook？
• 是否已有可复用的服务？
• 是否遵循了项目当前的结构？
• 所有逻辑是否都放在 hooks 中？
• 所有 HTTP 调用是否都放在服务中？
• 是否对所有 UI 组件都使用了 coreeb？
• 所有代码是否都使用英语编写？
• 解决方案是否简单？
• 是否避免了过度设计？
• 是否只修改了指定模块？

如果任何一项的回答为“否”——请在生成代码前修正。

---

📦 安装与依赖

pnpm add coreeb@latest

重要

始终使用 pnpm。绝不要使用 npm install 或 yarn add。

---

目录结构（必须遵守）

这是项目的精确结构。不要添加、重命名或重新组织文件夹。

POINT-FRONT-V1/
├── pnpm-workspace.yaml          # pnpm v11 config
├── next.config.ts
├── tsconfig.json                # Path alias @/* → ./src/*
├── postcss.config.mjs
└── src/
    ├── app/                     # ── LEVEL 1: Routing (App Router)
    │   ├── globals.css          # Global styles and design tokens
    │   ├── layout.tsx           # Root HTML shell
    │   ├── page.tsx             # Initial redirect to /dashboard
    │   └── (pages)/             # Authenticated route group
    │       ├── layout.tsx       # Sidebar + Header + <main>
    │       ├── dashboard/page.tsx
    │       ├── campanas/
    │       │   ├── page.tsx
    │       │   ├── create/page.tsx
    │       │   └── [id]/
    │       │       ├── page.tsx
    │       │       └── edit/page.tsx
    │       ├── mi-cuenta/
    │       │   ├── page.tsx
    │       │   ├── create/page.tsx
    │       │   └── [id]/page.tsx
    │       ├── monitoreo-bdd/page.tsx
    │       ├── planner/
    │       │   ├── page.tsx
    │       │   └── create/page.tsx
    │       ├── visual-senalizacion/
    │       │   ├── page.tsx
    │       │   ├── create/page.tsx
    │       │   └── [id]/page.tsx
    │       ├── software-pdv/page.tsx
    │       ├── experiencia-cliente/page.tsx
    │       └── administracion/page.tsx
    │
    ├── modules/                 # ── LEVEL 2: Business Logic per Module
    │   │   # Patrón uniforme en cada acción CRUD (list · create · detail · edit):
    │   │   ├── screens/         # Full view (imported by page.tsx)
    │   │   ├── components/      # Local components of the action
    │   │   ├── hooks/           # Data fetching and local state
    │   │   ├── helpers/         # Pure functions and formatters
    │   │   └── lib/
    │   │       ├── api/         # HTTP client and data requests
    │   │       └── types/       # Domain TypeScript types (index.ts)
    │   │
    │   ├── campanas/{list,create,detail,edit}/
    │   ├── mi-cuenta/{list,create,detail}/
    │   ├── monitoreo-bdd/list/
    │   ├── planner/{list,create}/
    │   ├── visual-senalizacion/{list,create,detail}/
    │   ├── software-pdv/list/
    │   ├── experiencia-cliente/list/
    │   └── administracion/list/
    │
    ├── components/              # ── LEVEL 3: Global Shared UI
    │   ├── Sidebar.tsx          # Side navigation bar
    │   └── Header.tsx           # Top bar (profile, notifications)
    │
    └── lib/                     # ── LEVEL 4: Infrastructure & Utilities
        ├── api/                 # HTTP client and data requests
        └── types/               # Global TypeScript types (index.ts)

不得违反的规则

1. LEVEL 1 — 路由（src/app/）：仅包含 page.tsx 和 layout.tsx。每个 page.tsx 都是一个轻量容器，用于导入并渲染 LEVEL 2 的 Screen。此处不得包含任何逻辑。
2. LEVEL 2 — 模块（src/modules/）：所有业务逻辑、hooks、helpers 和子组件都按模块和操作组织。每个操作都包含 screens/、components/、hooks/、helpers/ 和 lib/{api,types}。
3. LEVEL 3 — 全局 UI（src/components/）：仅包含全局共享 UI 组件（Sidebar.tsx、Header.tsx）。
4. LEVEL 4 — 基础设施（src/lib/）：全局 HTTP 客户端（src/lib/api/）和全局类型（src/lib/types/index.ts）。
5. 仅限已定义的模块： campanas、mi-cuenta、monitoreo-bdd、planner、visual-senalizacion、software-pdv、experiencia-cliente、administracion。不要添加未列出的模块。

该放在哪里？

需要创建的内容	放置位置
新路由/页面	src/app/(pages)/[modulo]/page.tsx
操作的主视图（Screen）	src/modules/[modulo]/[action]/screens/[ScreenName].tsx
操作的本地组件	src/modules/[modulo]/[action]/components/
操作的 hook	src/modules/[modulo]/[action]/hooks/
操作的 helper	src/modules/[modulo]/[action]/helpers/
操作的 HTTP 服务/客户端	src/modules/[modulo]/[action]/lib/api/
操作的本地类型	src/modules/[modulo]/[action]/lib/types/index.ts
全局可复用组件	src/components/
全局 HTTP 客户端	src/lib/api/
全局共享类型	src/lib/types/index.ts

---

1. coreeb 库配置（UI）

A. next.config.ts

const nextConfig = { transpilePackages: ['coreeb'] };
export default nextConfig;

B. postcss.config.mjs

const config = { plugins: { '@tailwindcss/postcss': {} } };
export default config;

C. src/app/globals.css

@import "tailwindcss";
@import "tw-animate-css";
@custom-variant dark (&:is(.dark *));
@import "coreeb/styles.css";

/* Project-specific styles below */

D. src/app/layout.tsx

import './globals.css';
import { Toaster } from 'coreeb';

export const metadata = { title: 'App' };

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="es">
      <head>
        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,[email protected],100..700,0..1,-50..200" />
      </head>
      <body>
        {children}
        <Toaster position="top-right" richColors />
      </body>
    </html>
  );
}

E. coreeb 组件目录

重要

创建任何 UI 组件前，务必先查阅此目录。 如果 coreeb 中已有相应组件，必须使用。

• 通用 / 布局： Icons、Button、Badge、Separator、Skeleton、Spinner、Visually Hidden、Card、Collapsible、Scroll Area、Tabs。
• 表单： Floating Input、Floating Select、Floating Date Picker、Chip Selector、Checkbox、Form、Radio Group、Switch、Textarea、File Dropzone、Date Range Pill。
• 数据展示与反馈： Avatar、Table、Sonner (Toast)（Toaster）、Tooltip。
• 叠加层： Command、Dialog、Dropdown Menu、Popover、Sheet。

界面 100% 使用这些组件构建。面板导航和布局必须严格使用 coreeb 中的 Tabs 和 Sheet。

F. 默认尺寸（必需）

元素	默认尺寸
Input、Select	sm
Button	small
Icons	xs

这些尺寸是项目标准。只有在有明确且合理的视觉需求时，才可更改。

---

2. 项目合规检查清单

• 严格遵循 POINT-FRONT-V1 目录结构。
• 使用 pnpm add 安装依赖。
• 所有 UI 组件均使用 coreeb — 创建前已查阅组件目录。
• src/app/ 中的路由是精简容器，从 src/modules/ 导入 Screen。
• 所有代码均使用英文（变量、函数、文件、文件夹）。
• 组件中不包含任何业务逻辑 — 全部放在 hooks 中。
• 组件或 hooks 中不直接发起任何 HTTP 调用 — 全部放在服务中。
• 未经授权，不安装新依赖。
• 未修改请求范围之外的任何模块。
• 代码中没有注释。