React + TypeScript 前端项目代码规范文档

project/
├── docs/                  # 设计文档、PRD、代码规范
│   ├── design/            #   页面/模块设计文档
│   ├── code-style/        #   代码规范（本文件）
│   └── components/        #   公共组件文档
├── src/
│   ├── main.tsx           # 应用入口
│   ├── main.less          # 基础样式（font/box-sizing/body）
│   ├── api/               # 全局 API 请求层
│   │   ├── request.ts     #   请求客户端（axios 封装）
│   │   └── user.ts        #   按模块拆分
│   ├── components/        # 跨页面公共组件（条件：≥2 个页面复用）
│   │   └── <comp>/
│   │       ├── index.tsx
│   │       ├── index.less
│   │       └── models.ts
│   ├── pages/             # 页面模块
│   │   └── <page>/
│   │       ├── index.tsx          # 页面入口：装配主流程
│   │       ├── index.module.less  # 页面样式
│   │       ├── api.ts             # 页面专属接口
│   │       ├── components/        # 页面内部组件
│   │       ├── hooks/             # 页面 hook
│   │       └── view.ts            # 表格列/表单 schema 等展示结构
│   ├── services/           # 业务流程层（多接口流程、跨页面用例）
│   ├── stores/             # 全局状态
│   ├── models/             # 跨页面共享数据模型
│   ├── lib/                # 纯工具函数（无 React 依赖）
│   ├── styles/             # 全局样式 token / 主题变量
│   └── router/             # 路由配置
├── __tests__/              # 单元测试（镜像 src 结构）
└── mock/                   # 接口 mock

// ✅ 好的页面入口：装配主流程，不堆细节
function IncidentDetailPage() {
  const detail = useIncidentDetail(id);
  const { canEdit, isClosed } = detail.state;

  return (
    <div className={styles.page}>
      <IncidentHeader event={detail.event} canEdit={canEdit} />
      <IncidentTimeline entries={detail.timeline} />
      <IncidentEditModal open={editing} onSubmit={detail.save} />
    </div>
  );
}

// ❌ 不好的页面入口：堆大段 JSX、表格列、内联逻辑
function IncidentDetailPage() {
  return (
    <div>
      <Table columns={[
        { title: '状态', dataIndex: 'status', render: (v) => {
          if (v === 'open') return <Tag color="red">...</Tag>
          // ... 80 行 JSX 堆在入口
        }}
      ]}/>
    </div>
  );
}

// ✅ 分组 props
type IncidentHeaderProps = {
  event: IncidentView;
  actions: {
    onEdit: () => void;
    onClose: () => void;
    onReopen: () => void;
  };
};

// ❌ 透传完整 store
type IncidentHeaderProps = {
  store: IncidentStore;  // 组件不需要整个 store
};

请求层 (api/)    → 只做 HTTP 调用，返回 DTO
  ↓
服务层 (services/) → 组合多接口、业务编排
  ↓
状态层 (stores/)   → 全局/页面状态管理
  ↓
Hook 层 (hooks/)   → 临时状态、副作用编排
  ↓
视图层 (pages/components/) → 纯展示和交互入口

// ✅ 线性可读
async function saveIncident(input: SaveInput) {
  const validation = validateSaveInput(input);
  if (!validation.ok) return showError(validation);

  const payload = buildSavePayload(input);
  const result = await requestSave(payload);
  return handleSaveResult(result);
}

// ❌ 分支嵌套 + 内联副作用
async function saveIncident(input: SaveInput) {
  if (input.name) {
    const x = await api.post('/save', { name: input.name }).then(r => {
      if (r.data.status === 0) {
        message.success('ok');
        router.push('/list');
      } else {
        if (r.data.msg) message.error(r.data.msg);
      }
    });
  }
}

npm run typecheck   # tsc --noEmit
npm run lint        # eslint
npm test            # 至少覆盖修改文件