moon-web-pages-conventions

React + TS + Ant Design v6 页面规范

1) 组件与数据流

• 页面组件使用函数式组件 + hooks；避免把副作用写在 render 中。
• 派生状态优先用 useMemo（例如过滤/排序后数据、列定义），避免每次 render 都重建大对象。
• 事件处理函数优先用 useCallback，并保证依赖项正确且完整。
• 页面业务请求只调用 src/api/** 的封装；禁止在页面内直接使用底层 http。

2) 数据获取与副作用（必做）

• 进行异步请求时，必须处理 loading（至少是页面级 loading 或局部 actionLoading）。
• 需要在卸载后避免 setState：使用 mountedRef/取消逻辑（与当前项目一致的写法优先）。
• try/catch/finally 必须闭环：成功给用户反馈，失败记录并给出降级 UI（例如空表/空状态）。
• 不要在异常里吞掉错误；至少 console.error（或项目约定的 logger）。

示例（结构要求，非强制实现）：

setLoading(true)
try {
  const res = await apiCall()
  setData(res.items ?? [])
} catch (e) {
  console.error('xxx失败', e)
  setData([])
} finally {
  setLoading(false)
}

3) i18n（必做）

• 所有 UI 文案必须走 i18n：使用 const { t } = useLocale() + t('xxx')。
• message/Modal/Table/placeholder/Tooltip/Button 的文本都必须来自 t(...)。
• 规则：页面里不允许出现业务文案的硬编码（表格列名、弹窗标题、按钮文本、空状态文案等）。

4) Ant Design v6 用法（必做）

Table

• Table 必须设置 rowKey，且 rowKey 应为业务稳定字段（如 uid）。
• 分页/滚动使用受控 props：pagination.current/pageSize/total 与 onChange 联动。
• 列渲染函数使用类型约束（ColumnsType<T>），渲染内避免出现未处理的 undefined（使用 emptyPlaceholder 或兜底 '-'）。

Modal

• 使用 open（v6）而非 visible。
• onCancel 必须回收/重置本地 state（关闭弹窗时把 record 清空、把输入值清空）。
• footer：
  • 详情弹窗优先 footer={null} 并只读展示
  • 有确认逻辑的弹窗使用 onOk + confirmLoading

Form

• 表单使用 Form.useForm() 管理实例，校验通过用 form.validateFields()。
• 处理 validateFields 的异常：仅当是 errorFields（校验失败）时直接 return；其它异常要记录并提示。

Dropdown

• Dropdown 使用 menu={{ items: ... }}（v6），并避免在 render 中创建会变化但不必要的 handler（可在上层 memo/回调中稳定）。
• 删除/危险操作前使用 MENU_DIVIDER（@/utils/menu）与常规菜单项分隔。

代码格式

• 使用项目根目录 prettier.config.js（单引号、无分号、trailingComma: all 等）；提交前执行 pnpm format 或依赖编辑器保存时格式化。
• ESLint 与 Prettier 分工：样式由 Prettier 处理，逻辑由 ESLint；勿在 ESLint 中重复配置与 Prettier 冲突的规则。

5) 编辑器悬停文档（JSDoc）

• TypeScript / Cursor 悬停提示只识别 /** JSDoc */，普通 // 行注释不会出现在悬停里。
• 需要悬停展示说明的函数、变量、接口字段、类型，请写在紧邻声明上方的 JSDoc 中。
• 第三方库（如 antd）的类型说明来自 node_modules 中的 .d.ts，需保证工作区使用项目内 TypeScript（见 .vscode/settings.json 中 typescript.tsdk）。