initial commit

2026-02-16 12:46:37 +08:00
commit e10747feac
190 changed files with 49119 additions and 0 deletions
--- a/.agent/skills/business/content-management/SKILL.md
+++ b/.agent/skills/business/content-management/SKILL.md
@@ -0,0 +1,139 @@
+---
+name: content-management
+description: 内容管理（CMS）模块的业务规则，包含文章发布流程、富文本编辑规范与 SEO 要求。当涉及文章、资讯、公告等内容管理功能时必须参考此 Skill。
+---
+
+# 内容管理 (CMS) 业务 Skill
+
+## 适用范围
+
+当任务涉及以下场景时，必须加载并遵循此 Skill：
+
+- 文章/资讯列表、编辑、发布
+- 内容分类与标签管理
+- 富文本/Markdown 编辑器集成
+- SEO 字段管理
+
+## 业务规则
+
+### 1. 文章发布流程
+
+```
+草稿 (draft) → 待审核 (pending_review) → 已发布 (published) → 已归档 (archived)
+                    ↓
+                  驳回 (rejected) → 草稿 (draft) [修改后重新提交]
+```
+
+**关键约束**:
+
+- 普通编辑: 只能提交审核，不能直接发布
+- 管理员/主编: 可以跳过审核直接发布
+- 已发布文章: 编辑后生成新版本，需重新审核
+- 定时发布: 支持设置 `publishAt` 时间，到达时间后系统自动从「待发布」改为「已发布」
+
+### 2. 内容模型
+
+- **标题** (title): 必填，2-100 字符
+- **摘要** (summary): 选填，≤ 200 字符。若未填写，自动截取正文前 200 字
+- **正文** (content): 必填，支持 Markdown 格式
+- **封面图** (coverImage): 推荐尺寸 16:9（如 1200×675），支持裁剪
+- **分类** (categoryId): 必填，单选
+- **标签** (tags): 选填，多选，最多 5 个
+- **SEO 字段**:
+  - `seoTitle`: 选填，≤ 60 字符
+  - `seoDescription`: 选填，≤ 160 字符
+  - `seoKeywords`: 选填，逗号分隔
+
+### 3. 排序规则
+
+- 默认按发布时间倒序
+- 支持「置顶」功能（`isTop: boolean`），置顶文章优先展示
+- 置顶文章之间按置顶时间倒序
+
+## 数据模型
+
+### 核心接口
+
+```typescript
+// src/services/article.ts
+export async function getArticleList(
+  params: ArticleQueryParams,
+): Promise<API.PageResult<ArticleItem>> {}
+export async function getArticleDetail(id: string): Promise<ArticleDetail> {}
+export async function createArticle(
+  data: ArticleFormData,
+): Promise<ArticleItem> {}
+export async function updateArticle(
+  id: string,
+  data: Partial<ArticleFormData>,
+): Promise<ArticleItem> {}
+export async function updateArticleStatus(
+  id: string,
+  status: ArticleStatus,
+): Promise<void> {}
+export async function deleteArticle(id: string): Promise<void> {}
+export async function toggleTop(id: string, isTop: boolean): Promise<void> {}
+```
+
+### 关键类型
+
+```typescript
+// src/pages/Article/data.d.ts
+type ArticleStatus =
+  | 'draft'
+  | 'pending_review'
+  | 'published'
+  | 'archived'
+  | 'rejected';
+
+interface ArticleItem {
+  id: string;
+  title: string;
+  summary?: string;
+  content: string;
+  coverImage?: string;
+  categoryId: string;
+  categoryName: string;
+  tags: string[];
+  status: ArticleStatus;
+  author: string;
+  isTop: boolean;
+  viewCount: number;
+  publishAt?: string;
+  createdAt: string;
+  updatedAt: string;
+  seoTitle?: string;
+  seoDescription?: string;
+  seoKeywords?: string;
+}
+```
+
+## UI 交互规范
+
+### 1. 文章列表页
+
+- **组件**: `ProTable`（搜索字段 < 4，使用内置 search）
+- **必须包含列**: 标题（可点击预览）、分类、状态、作者、发布时间、阅读量、操作
+- **操作逻辑**: 根据状态动态展示按钮
+  - 草稿: 编辑 / 提交审核 / 删除
+  - 已发布: 编辑 / 下架（归档）/ 置顶/取消置顶
+- **置顶标识**: 在标题前显示 📌 图标
+
+### 2. 文章编辑页
+
+- **组件**: `ProForm`（非分步）
+- **编辑器**: 使用项目中已有的 `MarkdownEditor` 组件（`src/components/MarkdownEditor`）
+- **布局**: 左侧大区域放编辑器，右侧抽屉或区域放 SEO/分类/标签
+- **自动保存**: 每 30 秒自动保存草稿（使用 `useRequest` 配合 `debounce`）
+
+### 3. 预览
+
+- 支持在弹窗中预览 Markdown 渲染结果
+- 预览模式使用 `Modal` + Markdown 渲染组件
+
+## i18n Key 规范
+
+- 菜单: `menu.content.*` 或 `menu.article.*`
+- 页面: `pages.article.*`
+- 表单: `article.form.*`
+- 状态: `article.status.*`
--- a/.agent/skills/business/order-management/SKILL.md
+++ b/.agent/skills/business/order-management/SKILL.md
@@ -0,0 +1,151 @@
+---
+name: order-management
+description: 订单管理模块的业务规则、订单流转状态机、支付与退款逻辑。当涉及订单相关功能开发时必须参考此 Skill。
+---
+
+# 订单管理 (Order Management) 业务 Skill
+
+## 适用范围
+
+当任务涉及以下场景时，必须加载并遵循此 Skill：
+
+- 订单列表、订单详情、订单创建
+- 支付流程、退款流程
+- 发货与物流跟踪
+- 订单统计与报表
+
+## 业务规则
+
+### 1. 订单状态机
+
+```
+待支付 (pending_payment)
+  ├─ 支付成功 → 待发货 (pending_shipment)
+  │                ├─ 发货 → 运输中 (shipping)
+  │                │            ├─ 签收 → 已完成 (completed)
+  │                │            └─ 拒收 → 退回中 (returning)
+  │                └─ 申请退款 → 退款中 (refunding)
+  ├─ 超时未付 → 已取消 (cancelled) [系统自动, 30分钟]
+  └─ 用户取消 → 已取消 (cancelled)
+```
+
+**关键约束**:
+
+- 超时取消: 下单后 **30 分钟**未支付自动取消，释放库存
+- 退款窗口: 仅在「待发货」状态可申请全额退款
+- 已发货订单: 需走退货退款流程（用户寄回 → 确认收货 → 退款）
+- 已完成订单: 签收后 **7 天**内可申请售后
+
+### 2. 金额计算规则
+
+- **订单总额** = Σ(商品售价 × 数量) - 优惠金额 + 运费
+- **金额精度**: 所有金额计算统一使用 **分 (cent)** 为单位（整数运算），前端展示时 ÷ 100 并保留 2 位小数
+- **⚠️ 严禁浮点运算**: 禁止使用 `0.1 + 0.2` 等浮点计算，必须转换为整数
+
+### 3. 订单号规则
+
+- 格式: `ORD{YYYYMMDD}{6位序号}`
+- 示例: `ORD2026021600001`
+- 订单号由后端生成，前端仅用于展示
+
+## 数据模型
+
+### 核心接口
+
+```typescript
+// src/services/order.ts
+export async function getOrderList(
+  params: OrderQueryParams,
+): Promise<API.PageResult<OrderItem>> {}
+export async function getOrderDetail(orderId: string): Promise<OrderDetail> {}
+export async function cancelOrder(
+  orderId: string,
+  reason: string,
+): Promise<void> {}
+export async function shipOrder(
+  orderId: string,
+  logistics: LogisticsInfo,
+): Promise<void> {}
+export async function refundOrder(
+  orderId: string,
+  refundData: RefundRequest,
+): Promise<void> {}
+```
+
+### 关键类型
+
+```typescript
+// src/pages/Order/data.d.ts
+type OrderStatus =
+  | 'pending_payment'
+  | 'pending_shipment'
+  | 'shipping'
+  | 'completed'
+  | 'cancelled'
+  | 'refunding'
+  | 'returning';
+
+interface OrderItem {
+  orderId: string;
+  orderNo: string;
+  userId: string;
+  userName: string;
+  items: OrderProduct[];
+  totalAmount: number; // 单位: 分
+  discountAmount: number; // 单位: 分
+  shippingFee: number; // 单位: 分
+  payableAmount: number; // 单位: 分 (实付)
+  status: OrderStatus;
+  paymentMethod?: string;
+  paidAt?: string;
+  shippedAt?: string;
+  completedAt?: string;
+  createdAt: string;
+  remark?: string;
+}
+
+interface OrderProduct {
+  productId: string;
+  productName: string;
+  skuId: string;
+  price: number; // 单位: 分
+  quantity: number;
+  subtotal: number; // 单位: 分
+}
+```
+
+## UI 交互规范
+
+### 1. 订单列表页
+
+- **组件**: 独立 `QueryFilter` + `ProTable`（字段 ≥ 4）
+- **必须筛选项**: 订单号、订单状态、下单时间范围、用户名
+- **状态标签颜色**:
+  - pending_payment → 橙色 (warning)
+  - pending_shipment → 蓝色 (processing)
+  - shipping → 青色 (cyan)
+  - completed → 绿色 (success)
+  - cancelled → 灰色 (default)
+  - refunding → 红色 (error)
+- **金额展示**: 使用 `valueType: 'money'`，需自定义 render 将分转换为元
+
+### 2. 订单详情页
+
+- **组件**: `ProDescriptions` + `Steps`（状态流转进度条）
+- **布局**: 顶部状态进度条 + 基本信息 + 商品清单 + 操作按钮
+- **操作按钮**: 根据当前状态动态显示（如待发货显示「发货」按钮，待支付显示「取消」按钮）
+
+### 3. 金额格式化工具函数
+
+```typescript
+// src/utils/currency.ts
+export const centToYuan = (cent: number): string => (cent / 100).toFixed(2);
+export const yuanToCent = (yuan: number): number => Math.round(yuan * 100);
+```
+
+## i18n Key 规范
+
+- 菜单: `menu.order.*`
+- 页面: `pages.order.*`
+- 表单: `order.form.*`
+- 状态: `order.status.*`
--- a/.agent/skills/business/product-management/SKILL.md
+++ b/.agent/skills/business/product-management/SKILL.md
@@ -0,0 +1,132 @@
+---
+name: product-management
+description: 商品管理模块的业务规则、数据模型、状态机与 UI 交互规范。当涉及商品相关功能开发时必须参考此 Skill。
+---
+
+# 商品管理 (Product Management) 业务 Skill
+
+## 适用范围
+
+当任务涉及以下场景时，必须加载并遵循此 Skill：
+
+- 商品列表、商品详情、商品创建/编辑
+- SKU 管理、库存管理、价格体系
+- 商品分类与属性管理
+
+## 业务规则
+
+### 1. 商品状态机
+
+```
+草稿 (draft) → 待审核 (pending_review) → 已上架 (online) → 已下架 (offline)
+                    ↓                                           ↑
+                  驳回 (rejected) ────────────────────────────→ ┘
+```
+
+**关键约束**:
+
+- 草稿状态可直接删除
+- 已上架商品必须先下架才能编辑核心字段（名称、价格、SKU）
+- 已上架商品的**非核心字段**（描述、图片）允许直接编辑
+- 删除操作仅限于「草稿」和「已下架」状态
+
+### 2. 价格体系
+
+- `originalPrice`: 原价（必填，> 0）
+- `salePrice`: 售价（必填，> 0，且 ≤ 原价）
+- `costPrice`: 成本价（选填，仅管理员可见）
+- 价格精度: 统一保留 **2 位小数**，使用 `number` 类型，前端展示时通过 `valueType: 'money'` 格式化
+
+### 3. 库存规则
+
+- 库存低于 `safetyStock`（安全库存）时在列表显示 ⚠️ 警告标识
+- 库存为 0 时自动标记为「缺货」状态（不影响上下架状态）
+- 库存变更必须记录变更日志（调拨、入库、出库、盘点）
+
+## 数据模型
+
+### 核心接口
+
+```typescript
+// src/services/product.ts
+export async function getProductList(
+  params: ProductQueryParams,
+): Promise<API.PageResult<ProductItem>> {}
+export async function getProductDetail(id: string): Promise<ProductItem> {}
+export async function createProduct(
+  data: ProductFormData,
+): Promise<ProductItem> {}
+export async function updateProduct(
+  id: string,
+  data: Partial<ProductFormData>,
+): Promise<ProductItem> {}
+export async function updateProductStatus(
+  id: string,
+  status: ProductStatus,
+): Promise<void> {}
+export async function deleteProduct(id: string): Promise<void> {}
+```
+
+### 关键类型
+
+```typescript
+// src/pages/ProductList/data.d.ts
+type ProductStatus =
+  | 'draft'
+  | 'pending_review'
+  | 'online'
+  | 'offline'
+  | 'rejected';
+
+interface ProductItem {
+  id: string;
+  name: string;
+  categoryId: string;
+  categoryName: string;
+  originalPrice: number;
+  salePrice: number;
+  costPrice?: number;
+  stock: number;
+  safetyStock: number;
+  status: ProductStatus;
+  images: string[];
+  description: string;
+  attributes: Record<string, string>;
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+## UI 交互规范
+
+### 1. 商品列表页
+
+- **组件**: `ProTable`
+- **必须包含列**: 商品名称、分类、售价、库存、状态、操作
+- **状态筛选**: 使用 `valueEnum` 映射状态标签颜色
+  - draft → 灰色
+  - pending_review → 橙色
+  - online → 绿色
+  - offline → 默认
+  - rejected → 红色
+- **批量操作**: 支持批量上架/下架
+
+### 2. 商品编辑
+
+- **组件**: `ProForm` + `StepsForm`（分步表单）
+- **步骤**: 基本信息 → SKU/价格 → 图片/描述 → 确认提交
+- **价格输入**: 使用 `ProFormMoney` 或 `ProFormDigit` 并配置 `precision={2}`
+
+### 3. 库存警告
+
+- 库存 < 安全库存: 单元格显示橙色 + ⚠️
+- 库存 = 0: 单元格显示红色 + "缺货" 标签
+
+## i18n Key 规范
+
+菜单和页面文案 Key 前缀:
+
+- 菜单: `menu.product.*`
+- 页面: `pages.product.*`
+- 表单: `product.form.*`
+- 状态: `product.status.*`
--- a/.agent/skills/engineering/code-quality/SKILL.md
+++ b/.agent/skills/engineering/code-quality/SKILL.md
@@ -0,0 +1,63 @@
+---
+name: code-quality
+description: 通用编码质量规范。适用于所有前端项目，与具体技术栈无关。当涉及任何代码实施、审计任务时，PM 必须参考此 Skill 并将要点注入子 Agent。
+---
+
+# 通用编码质量规范
+
+## 1. TypeScript 严格模式
+
+- **禁止** `any` 类型。所有变量、参数、返回值必须有明确类型。
+- props 和 state 必须严格类型化，使用 `interface` 或 `type` 定义。
+- 接口定义统一放在 `data.d.ts` 文件中，便于服务层和组件层共享。
+- 无隐式 `any`，无未使用变量，确保通过所有 lint 规则。
+
+## 2. 组件规模红线
+
+- **严禁**单个 React 组件文件（`.tsx`）超过 **500 行**。
+- 超过必须进行拆分：
+  - **UI 子组件化**: 将可复用的 UI 片段提取为独立组件。
+  - **逻辑 Hooks 化**: 将复杂业务逻辑抽离到自定义 Hooks 中。
+  - **Utils 分离**: 纯计算函数抽离到 `utils/` 目录。
+- 原则：保持 UI 组件简洁、逻辑模块化。
+
+## 3. 安全规范
+
+### 3.1 金额/货币精度
+
+- **绝不**使用原始浮点运算处理金额。
+- 使用精度安全库（如 `big.js`、`decimal.js`）或将金额作为**整数（分）**处理。
+- UI 层展示时再进行格式化转换。
+
+### 3.2 XSS 防护
+
+- **禁止** `dangerouslySetInnerHTML` 或绕过 React 转义的直接 DOM 操作。
+- 任何动态内容都必须经过清理（sanitize）。
+
+### 3.3 权限控制
+
+- 敏感操作、路由或 UI 元素必须受权限系统保护。
+- 检查"基于 ID"的未授权访问风险。
+
+## 4. 数据交互规范
+
+### 4.1 服务层隔离
+
+- **所有**页面数据交互必须通过 `src/services/` 层封装的函数。
+- **禁止**在组件（JSX）中内联 mock 数据或直接发起请求。
+- Mock 数据统一放在项目约定的 `mock/` 目录。
+
+### 4.2 加载状态
+
+- 所有异步操作（请求、提交、删除等）**必须**显示加载状态（按钮 spinner 或骨架屏）。
+
+### 4.3 防重复点击
+
+- 所有操作按钮在执行期间必须被禁用（通过 loading + disabled 联动）。
+- 防止用户双击导致重复提交。
+
+## 5. 代码卫生
+
+- **零 Lint 策略**: 代码必须通过所有 linting 规则。
+- 无隐式 `any`，无未使用变量，hooks 中无缺失依赖数组。
+- 保持 import 整洁，无未使用的导入。
--- a/.agent/skills/tech-stack/umijs-procomponents/SKILL.md
+++ b/.agent/skills/tech-stack/umijs-procomponents/SKILL.md
@@ -0,0 +1,148 @@
+---
+name: umijs-procomponents
+description: UmiJS 4 + Ant Design 5 + ProComponents 全栈开发规范。涵盖技术栈约束、组件用法、样式系统、服务层架构、国际化和图标管理。当项目使用 UmiJS + ProComponents 技术栈时，PM 必须将本 Skill 的要点注入给所有子 Agent。
+---
+
+# UmiJS + ProComponents 开发规范
+
+## 1. 技术栈
+
+- **框架**: UmiJS 4 + React 18 + TypeScript（严格模式）
+- **UI 库**: Ant Design 5 + ProComponents（ProTable, ProForm, ProLayout 等）
+- **数据流**: `useRequest`（ahooks / Umi 内置）、Umi Models
+- **路由/权限**: Umi Max 内置插件 — `access`、`initialState`、`request`、`model`、`locale`
+
+## 2. ProComponents 使用规范
+
+### 2.1 组件选型原则
+
+- **配置优于代码**: 始终优先使用 ProComponents 的 `request` 属性处理数据加载。
+- 利用 `valueType` 进行字段自动格式化。
+- 只有在 ProComponents 无法满足极度复杂需求时才使用原生 Antd 或手动实现。
+
+### 2.2 组件映射
+
+| 场景      | 组件                                   |
+| :-------- | :------------------------------------- |
+| 列表/表格 | `ProTable`                             |
+| 表单      | `ProForm` / `ModalForm` / `DrawerForm` |
+| 搜索/筛选 | `QueryFilter` / `LightFilter`          |
+| 布局      | `ProLayout` / `PageContainer`          |
+| 详情      | `ProDescriptions`                      |
+
+### 2.3 ⚠️ 禁止双内边距
+
+- **严禁**在 `ProTable`、`QueryFilter`、`ProForm` 外层包裹 `Card` 组件。
+- **原因**: ProComponents 自带卡片样式，额外包裹导致双内边距问题。
+- **错误示例**: `<Card><ProTable /></Card>` ❌
+- **正确示例**: `<ProTable style={{ marginBottom: token.marginLG }} />` ✅
+
+## 3. 搜索区域规范（Separated Card 模式）
+
+### 3.1 复杂度规则
+
+- **< 4 个搜索字段**: 使用 `ProTable` 内置 `search` 属性。
+- **>= 4 个搜索字段**: 使用独立 `QueryFilter` 组件，配置 `layout="vertical"`。
+
+### 3.2 视觉结构
+
+- 搜索区域: 直接使用 `QueryFilter`（自带白色背景和内边距）。
+- 背景色: `QueryFilter` **必须**设置白色背景（`token.colorBgContainer`）。
+- 表格区域: 直接使用 `ProTable`（自带卡片样式）。
+- 间距: `QueryFilter` 使用 `style={{ marginBottom: token.marginLG }}`。
+- **⚠️ 避免双内边距**: 不要在 `QueryFilter` 或 `ProTable` 外层再包裹 `div` 或 `Card` 添加 padding。
+
+## 4. 样式系统
+
+### 4.1 零 CSS 文件
+
+- **严格**使用 Ant Design Design Tokens 内联样式。
+- 使用 `const { token } = theme.useToken()` 获取 token。
+- 间距调整: 使用 `style={{ marginBottom: token.marginLG }}` 而非外层容器。
+- **禁止**导入 `.module.css` 或外部样式表。
+
+### 4.2 图标
+
+- **统一**使用 `@ant-design/icons`。
+- 除非明确要求或用于特定品牌标志，否则不使用外部图标库、SVG 或 emoji。
+
+### 4.3 UI 框架
+
+- **严格**使用原生 Ant Design ProComponents。禁止自定义 UI/UX 设计工具。
+- 表单布局: 输入标签放在输入框上方（`layout="vertical"`）。
+
+## 5. 服务层架构
+
+### 5.1 真实服务层
+
+- 所有页面逻辑必须调用 `src/services/`。禁止在 JSX 中内联 mock 数据或逻辑。
+- **强制使用 useRequest**: 所有数据交互（包括查询、提交、删除）**必须**通过 `useRequest` hook 发起。
+- **禁止直接 request**: 严禁在组件内直接手动调用 `request` 方法（除非在极特殊的底层封装中）。`useRequest` 提供了标准化的 loading、error 和 data 状态管理，手动 `request` 会导致状态管理不一致。
+
+### 5.2 统一 Mocking
+
+- 使用 UmiJS `mock/` 目录存放所有 mock 数据。禁止在组件中硬编码对象。
+
+### 5.3 类型定义
+
+- TypeScript 接口统一在 `data.d.ts` 中定义。
+
+### 5.4 菜单配置
+
+- 菜单图标必须在 `src/app.ts` 中配置渲染逻辑（确保图标显示为图形而非文本）。
+- 菜单文案必须配置在 `src/locales/` 中，Key 以 `menu.` 开头（如 `menu.system.user`）。
+
+## 6. 国际化 (i18n)
+
+### 6.1 强制规则
+
+- 所有面向用户的字符串**必须**使用 `intl.formatMessage` 或 `<FormattedMessage>`。
+- **每个** `formatMessage` 或 `FormattedMessage` 调用**必须**包含 `defaultMessage` 作为后备。
+  - 示例: `intl.formatMessage({ id: 'key', defaultMessage: '默认文案' })`
+- 在 `src/locales/` 中维护翻译。
+
+### 6.2 双语同步
+
+- **必须**同时在 `src/locales/zh-CN.ts` 和 `en-US.ts` 中定义所有使用的 Key。
+- **严禁**仅添加中文而忽略英文，或仅添加英文而忽略中文。
+
+### 6.3 QA 验证
+
+- 测试时必须在两种语言环境下验证页面显示。
+- 浏览器控制台不得出现 `[React Intl] Missing message` 警告。
+
+## 7. Figma 图标导出规范
+
+当 Figma 设计稿中包含图标元素时：
+
+### 7.1 优先级原则
+
+1. **优先匹配 Ant Design Icons**: 检查设计稿中的图标是否可用 `@ant-design/icons` 替代。如果视觉上高度一致，**必须使用 Ant Design 图标**。
+2. **自定义图标导出**: 仅当 Ant Design Icons 中**没有匹配或视觉差异明显**时，才从 Figma 导出。
+
+### 7.2 导出流程
+
+1. 使用 Figma MCP 获取图标设计详情。
+2. 导出为 **SVG 格式**，保存到 `src/assets/icons/`。
+3. 文件命名: `icon-{功能名称}.svg`（全小写，中划线分隔）。
+4. 封装为 React 组件存放 `src/components/Icons/`。
+5. 在 `src/components/Icons/index.ts` 中统一导出。
+
+### 7.3 目录结构
+
+```
+src/
+├── assets/icons/
+│   ├── icon-custom-chart.svg
+│   └── icon-data-flow.svg
+└── components/Icons/
+    ├── index.ts
+    ├── CustomChartIcon.tsx
+    └── DataFlowIcon.tsx
+```
+
+## 8. Ant Design 5 兼容性
+
+- 使用 `open` 而非 `visible`。
+- 使用 `onOpenChange` 而非 `onVisibleChange`。
+- 对 Ant Design 5 更新极为警惕，避免使用废弃 API。