CRM Admin 项目开发指南（CLAUDE.md）

Vite 6 + React 18 + TypeScript + Ant Design 5 + SCSS 的后台管理平台。
源码位于 src/，使用 BrowserRouter 的 SPA 架构，包含多级路由菜单、登录 / 退出、路由守卫与按钮级权限。

一、常用命令

npm install        # 安装依赖
npm run dev        # 启动开发服务器（http://localhost:5173）
npm run typecheck  # TypeScript 类型检查
npm run build      # 类型检查 + 生产构建
npm run preview    # 预览生产构建

改动代码后至少执行 npm run typecheck；涉及构建配置或样式时再执行 npm run build。

二、技术栈

• 构建：Vite 6
• 框架：React 18 + TypeScript（strict）
• 路由：react-router-dom 6
• UI：Ant Design 5 + @ant-design/icons
• 状态：Zustand 5（登录态持久化到 localStorage）
• 样式：SCSS + Ant Design 主题 token + CSS 变量
• 日期：Day.js（已配置中文 locale）

三、目录结构

src/
├── api/                 # 接口层；当前只有模拟登录 auth.ts
├── components/          # 通用组件：RouteGuard / AuthButton / Permission
├── constants/           # 权限码与中文说明
├── hooks/               # usePermission
├── layouts/             # BasicLayout：侧边栏、头部、内容区、面包屑
├── pages/               # 页面，按业务域分目录
│   ├── login/
│   ├── dashboard/
│   ├── system/
│   │   ├── users/
│   │   ├── roles/
│   │   └── permission/{menu,button}/
│   ├── business/{orders,customers}/
│   └── error/{Forbidden,NotFound}.tsx
├── router/
│   ├── routeConfig.tsx  # 路由 + 菜单唯一数据源（含权限码、页面组件）
│   ├── menu.tsx         # 菜单过滤与 antd Menu 结构生成
│   └── index.tsx        # 配置转 React Router 嵌套路由
├── store/               # Zustand 登录态
├── styles/              # 全局 SCSS、通用页面样式
├── types/               # 全局类型
└── main.tsx             # ConfigProvider + AntdApp + BrowserRouter

四、核心架构

1. 路由与菜单

src/router/routeConfig.tsx 是**唯一数据源**。新增页面只需在这里配置 path、title、icon、permission、element，侧边栏、面包屑、路由守卫会自动读取。

• 支持 2-3 级嵌套，例如：系统管理 → 权限中心 → 菜单权限。
• src/router/index.tsx 把菜单配置转换成 React Router 的嵌套路由。
• 分组路由（无 element）通过 <Outlet /> 渲染子页面，默认跳转到第一个有权限的子页面。
• 菜单项按 permission 过滤；分组下所有子项都无权限时整组隐藏。
• 未匹配路由显示 404，普通页面组件位于 BasicLayout 内。

2. 登录态

• src/store/auth.ts：Zustand store，持久化 token 与 user。
• 登录 / 退出：src/api/auth.ts 提供模拟登录。
• 演示账号：
• admin / admin123：权限为 ['*']，拥有全部权限。
• user / user123：仅有工作台、用户、订单、客户的查看权限。
• 未登录访问受保护页面会跳转 /login，登录成功后返回原地址。

3. 权限体系

• 权限码统一维护在 src/constants/permissions.ts。
• 路由级权限：页面配置中的 permission + src/components/RouteGuard.tsx。
• 未登录 → /login
• 无权限 → /403
• 菜单级权限：buildMenuItems 按权限码过滤。
• 按钮 / UI 级权限：
• <AuthButton permission="system:user:add">：无权限默认隐藏，fallback="disabled" 时禁用。
• <Permission permission="...">：包裹任意 UI。
• usePermission()：页面内自定义判断。
• * 表示全部权限。
• 前端权限只用于界面控制，接入真实后端时必须在服务端再次鉴权。

4. 布局与样式

• 统一使用 BasicLayout，页面只负责内容区域。
• 全局 CSS 变量：--app-primary、--app-bg、--app-border、--app-text、--app-text-secondary 等。
• 通用页面类：.page-header、.page-toolbar、.filter-card、.table-card、.text-muted。
• 页面级样式与页面同目录，使用 BEM 风格类名（如 .user-cell__name）。
• Ant Design 主题在 src/main.tsx 的 ConfigProvider 中统一配置。

五、代码风格（必遵守）

1. 统一使用箭头函数

组件、工具函数、Hook、事件处理函数都使用箭头函数，不新增 function 声明。

// ✅ 组件
const UserList = () => {
  const handleSubmit = async () => {
    // ...
  };

  return <Table />;
};

export default UserList;

// ✅ 工具 / Hook
export const usePermission = () => {
  // ...
};

export const formatAmount = (value: number) => `¥${value.toLocaleString()}`;

// ❌ 不要这样写
export default function UserList() {}
export function formatAmount(value: number) {}

2. 优先使用现成组件

写功能前先找现成能力，不要重复造轮子：

1. 优先使用 Ant Design 组件：Table、Form、Modal、Select、DatePicker、Card、Tabs、Drawer 等。
2. 优先使用项目已有封装：

• 按钮权限：src/components/AuthButton.tsx
• 任意 UI 权限：src/components/Permission.tsx
• 路由守卫：src/components/RouteGuard.tsx
• 布局：src/layouts/BasicLayout.tsx
• 全局提示 / 确认框：使用 <App> 提供的 AntdApp.useApp() 中的 message、modal，**不要**直接使用 message.success() / Modal.confirm() 静态方法。

1. 不要手写弹窗、Toast、下拉菜单、分页、表格、表单校验等基础交互。
2. 不引入新的 UI 组件库；确需新组件时，先检查 src/components/ 是否已有可复用实现，再考虑新增。
3. 使用 Ant Design 5 的 API，不使用已废弃属性。例如 Card 使用 variant="borderless"，不要使用 bordered={false}。

3. Table columns 必须单独提取

所有表格的 columns 不得内联在 <Table /> 的 JSX 中，也不写在页面组件内部。统一提取到页面目录单独维护。

推荐结构：

src/pages/system/users/
├── index.tsx       # 页面组件
├── columns.tsx     # 表格列定义
└── Users.scss      # 页面样式

// columns.tsx
import type { TableProps } from 'antd';

export const userColumns: TableProps<UserRecord>['columns'] = [
  {
    title: '用户名',
    dataIndex: 'username',
  },
  // ...
];

// 需要事件回调时，导出工厂函数
export const createUserColumns = (options: {
  onEdit: (record: UserRecord) => void;
  onDelete: (record: UserRecord) => void;
}): TableProps<UserRecord>['columns'] => [
  // ...
  {
    title: '操作',
    key: 'action',
    render: (_value, record) => (
      <AuthButton permission={PERMISSION.USER_EDIT} onClick={() => options.onEdit(record)}>
        编辑
      </AuthButton>
    ),
  },
];

// index.tsx
const columns = useMemo(() => createUserColumns({ onEdit, onDelete }), []);

<Table<UserRecord> rowKey="key" columns={columns} dataSource={dataSource} />;

约定：

• columns 只负责展示，数据与业务逻辑留在页面组件。
• 列类型使用 TableProps<T>['columns']，不要使用 any。
• 权限控制可以直接用 AuthButton / Permission（它们自己读取 store），无需把权限状态传进 columns。
• 若列配置依赖页面状态或回调，使用 createColumns(options) 工厂 + useMemo，不要每次渲染重新创建。

说明：存量页面中部分 columns 仍定义在页面组件内部、部分函数使用 function 声明。新增和修改代码一律遵循上述规范，存量代码在后续迭代中逐步迁移。

六、新增页面流程

1. 在 src/pages/<业务域>/<页面>/ 下创建 index.tsx（有表格时增加 columns.tsx，有独立样式时增加同名 .scss）。
2. 如需权限控制，在 src/constants/permissions.ts 新增权限码与中文说明。
3. 在 src/router/routeConfig.tsx 中增加路由配置：

• 使用完整路径（如 /system/users）。
• 配置 title、icon、permission、element。
• 需要分组时使用 children。

1. 在模拟账号（src/api/auth.ts）或真实后端中给角色分配权限码。
2. 页面内需要权限按钮时使用 AuthButton，路由级权限由 RouteGuard 自动处理。
3. 执行 npm run typecheck 验证。

示例：

{
  path: '/business/invoices',
  title: '发票管理',
  icon: <FileTextOutlined />,
  permission: PERMISSION.INVOICE_VIEW,
  element: <Invoices />,
}

七、接口与状态约定

• 所有请求统一放在 src/api/ 下，按业务域拆分文件；不要在页面内直接写请求实现。
• 当前 src/api/auth.ts 是前端模拟接口。接入真实后端时替换为实际请求，并保留登录态写入 store 的流程。
• 全局登录态只放在 src/store/auth.ts；页面局部状态使用 useState / useMemo。
• 不要在前端持久化敏感信息；真实项目的 Token 建议使用 HttpOnly Cookie，并由后端处理过期与刷新。

八、样式与可访问性

• 使用 SCSS，不在 JSX 中堆叠大量内联样式；动态颜色等少量样式可使用 style。
• 颜色、圆角优先使用已有的 CSS 变量或 Ant Design token。
• 交互元素保持可读的 hover / focus 状态；图标按钮补充 aria-label。
• 页面需兼容窄屏：表格使用 scroll={{ x: ... }}，左右布局使用栅格或 flex 换行。

九、部署注意

• 使用 BrowserRouter，生产环境需要配置 SPA fallback：所有前端路由回退到 index.html。
• 构建产物在 dist/。
• 当前主包较大（Ant Design 全量依赖），后续可通过路由懒加载 / 手动分包优化。