@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-platform-test-case/references/unit-test.md

@@ -0,0 +1,330 @@
+# 单元测试（test-case）
+
+> Service / Util 的单元测试模板。
+
+---
+
+## 1. Service 单元测试
+
+### 1.1 基本结构
+
+```java
+@ExtendWith(MockitoExtension.class)
+class OrderServiceImplTest {
+
+    @Mock
+    private OrderRepository orderRepository;
+
+    @Mock
+    private IUserClient userClient;
+
+    @InjectMocks
+    private OrderServiceImpl orderService;
+
+    @Test
+    void createOrder_success() {
+        // Arrange
+        OrderRequest req = new OrderRequest("ORD001", new BigDecimal("1000"), "10001");
+        when(orderRepository.save(any(Order.class))).thenAnswer(inv -> {
+            Order o = inv.getArgument(0);
+            o.setId("OID001");
+            return o;
+        });
+
+        // Act
+        OrderDTO result = orderService.create(req);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals("ORD001", result.getOrderNo());
+        assertEquals("PENDING", result.getStatus());
+        verify(orderRepository, times(1)).save(any(Order.class));
+    }
+}
+```
+
+### 1.2 异常路径
+
+```java
+@Test
+void createOrder_negativeAmount_throwsException() {
+    OrderRequest req = new OrderRequest("ORD001", new BigDecimal("-100"), "10001");
+
+    BizException ex = assertThrows(BizException.class, () -> {
+        orderService.create(req);
+    });
+    assertEquals("金额不能为负", ex.getMessage());
+
+    verify(orderRepository, never()).save(any(Order.class));
+}
+
+@Test
+void createOrder_userNotFound_throwsException() {
+    OrderRequest req = new OrderRequest("ORD001", new BigDecimal("1000"), "99999");
+    when(userClient.getById("99999")).thenReturn(null);
+
+    assertThrows(BizException.class, () -> orderService.create(req));
+}
+```
+
+### 1.3 参数化测试
+
+```java
+@ParameterizedTest
+@ValueSource(strings = {"", " ", "\t", "\n"})
+void createOrder_blankOrderNo_throwsException(String blank) {
+    OrderRequest req = new OrderRequest(blank, new BigDecimal("1000"), "10001");
+
+    assertThrows(BizException.class, () -> orderService.create(req));
+}
+
+@ParameterizedTest
+@CsvSource({
+    "-100, 金额不能为负",
+    "0, 金额必须大于 0",
+    "999999999999, 金额超出范围"
+})
+void createOrder_invalidAmount_throwsException(String amount, String expectedMsg) {
+    OrderRequest req = new OrderRequest("ORD001", new BigDecimal(amount), "10001");
+
+    BizException ex = assertThrows(BizException.class, () -> orderService.create(req));
+    assertEquals(expectedMsg, ex.getMessage());
+}
+```
+
+## 2. Util 单元测试
+
+```java
+@ExtendWith(MockitoExtension.class)
+class OrderNoGeneratorTest {
+
+    private OrderNoGenerator generator;
+
+    @BeforeEach
+    void setUp() {
+        generator = new OrderNoGenerator();
+    }
+
+    @Test
+    void generate_normal() {
+        String no = generator.generate("PURCHASE");
+        assertTrue(no.matches("^PO\\d{8}\\d{4}$"));
+    }
+
+    @Test
+    void generate_emptyPrefix_throws() {
+        assertThrows(IllegalArgumentException.class, () -> generator.generate(""));
+    }
+}
+```
+
+## 3. 静态方法测试（PowerMock 或重构）
+
+### 3.1 重构优先
+
+```java
+// ❌ 难测试：静态方法
+public class DateUtils {
+    public static LocalDate today() { return LocalDate.now(); }
+}
+
+// ✅ 重构为可注入
+@Component
+public class Clock {
+    public LocalDate today() { return LocalDate.now(); }
+}
+```
+
+### 3.2 注入测试
+
+```java
+@ExtendWith(MockitoExtension.class)
+class OrderServiceTest {
+    @Mock private Clock clock;
+
+    @BeforeEach
+    void setUp() {
+        when(clock.today()).thenReturn(LocalDate.of(2026, 9, 7));
+    }
+
+    @Test
+    void testWithFixedClock() {
+        LocalDate today = clock.today();
+        assertEquals(LocalDate.of(2026, 9, 7), today);
+    }
+}
+```
+
+## 4. AssertJ 链式断言（推荐）
+
+```java
+import static org.assertj.core.api.Assertions.*;
+
+@Test
+void createOrder_success() {
+    OrderDTO result = orderService.create(req);
+
+    assertThat(result)
+        .isNotNull()
+        .extracting(OrderDTO::getOrderNo, OrderDTO::getStatus, OrderDTO::getAmount)
+        .containsExactly("ORD001", "PENDING", new BigDecimal("1000"));
+
+    assertThat(result.getCreateTime())
+        .isAfter(LocalDateTime.now().minusMinutes(1));
+}
+```
+
+## 5. Given-When-Then 风格
+
+```java
+@Test
+void createOrder_success() {
+    // Given
+    OrderRequest req = new OrderRequest("ORD001", new BigDecimal("1000"), "10001");
+    given(orderRepository.save(any(Order.class))).willReturn(savedOrder);
+
+    // When
+    OrderDTO result = orderService.create(req);
+
+    // Then
+    assertThat(result.getOrderNo()).isEqualTo("ORD001");
+    then(orderRepository).should().save(any(Order.class));
+}
+```
+
+需 `BDDStyle`：
+
+```java
+import static org.mockito.BDDMockito.*;
+```
+
+## 6. 软删除实体特殊测试
+
+### 6.1 GEN-SOFT-DELETE
+
+```java
+@DataJpaTest
+class ProjectNoGeneratorTest {
+
+    @Autowired
+    private ProjectRepository projectRepo;
+
+    @Autowired
+    private ProjectNoGenerator generator;
+
+    @Test
+    @Transactional
+    void generateNo_skipSoftDeleted() {
+        // 准备：插入软删除的项目
+        Project soft = new Project();
+        soft.setProjectNo("P001");
+        soft.setDeleted(true);
+        projectRepo.save(soft);
+
+        // 验证：生成器跳过软删除编号
+        String next = generator.generateNext("P");
+
+        assertThat(next).isEqualTo("P002");
+    }
+
+    @Test
+    @Transactional
+    void generateNo_skipAllSoftDeleted() {
+        // 准备：P001, P002, P003 都是软删除
+        for (int i = 1; i <= 3; i++) {
+            Project p = new Project();
+            p.setProjectNo("P00" + i);
+            p.setDeleted(true);
+            projectRepo.save(p);
+        }
+
+        String next = generator.generateNext("P");
+
+        assertThat(next).isEqualTo("P004");
+    }
+}
+```
+
+### 6.2 DUP-SOFT-DELETE
+
+```java
+@SpringBootTest
+class ProjectServiceTest {
+
+    @Autowired
+    private ProjectService service;
+
+    @Autowired
+    private ProjectRepository projectRepo;
+
+    @Test
+    @Transactional
+    void validateProjectNo_softDeleted_throwsDuplicate() {
+        // 准备：软删除的项目 P001
+        Project soft = new Project();
+        soft.setProjectNo("P001");
+        soft.setDeleted(true);
+        projectRepo.save(soft);
+
+        // 验证：创建 P001 被拒
+        ProjectDTO dto = new ProjectDTO();
+        dto.setProjectNo("P001");
+
+        assertThatThrownBy(() -> service.create(dto))
+            .isInstanceOf(ProjectNoDuplicateException.class);
+    }
+}
+```
+
+## 7. ❌ 反模式
+
+### 7.1 ❌ 私有方法测试
+
+```java
+// ❌ 错：用反射测私有方法
+Method method = OrderService.class.getDeclaredMethod("validateAmount");
+method.setAccessible(true);
+method.invoke(orderService, ...);
+
+// ✅ 正确：通过公开方法测
+@Test void createOrder_invalidAmount() { ... }  // 触发 validateAmount
+```
+
+### 7.2 ❌ 不清理测试数据
+
+```java
+@Test void testA() {
+    userRepository.save(user);  // 没清理
+}
+
+@Test void testB() {
+    // 测试数据残留影响
+}
+```
+
+✅ `@AfterEach` 清理或 `@Transactional` 回滚。
+
+### 7.3 ❌ 时间相关测试不稳定
+
+```java
+// ❌ 错：依赖当前时间
+@Test void isExpire() {
+    Order order = new Order();
+    order.setCreateTime(LocalDateTime.now().minusDays(1));
+    assertTrue(orderService.isExpire(order));  // 跨天可能失败
+}
+
+// ✅ 正确：注入 Clock
+@Test void isExpire() {
+    when(clock.now()).thenReturn(LocalDateTime.of(2026, 9, 8, 0, 0));
+    Order order = new Order();
+    order.setCreateTime(LocalDateTime.of(2026, 9, 7, 0, 0));
+    assertTrue(orderService.isExpire(order));
+}
+```
+
+## 8. 关联阅读
+
+- [guide.md](guide.md) — 测试用例基础
+- [integration-test.md](integration-test.md) — 集成测试
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-ui-components/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: meritdata-platform-ui-components
+description: |
+  平台 UI 组件库。人员选择器 / 组织树 / 字典下拉 / 上传组件 / 富文本 / 流程设计器。
+  触发场景：二开页面需要"选择人员" / "组织树" / "下拉字典项" / "文件上传" 等平台通用组件。
+  何时不用：纯通用组件（antd/element）→ 直接用 antd；纯业务组件（自定义表格）→ 业务自己封装。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: low
+  layer: L3
+  sub-layer: L3-F
+  stack: frontend
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 平台 UI 组件（ui-components）
+
+## 触发
+- 业务页面需要"选择人员" → UserPicker
+- 业务页面需要"组织树" → OrgTreeSelect
+- 业务页面需要"字典下拉" → LookupSelect
+- 业务页面需要"文件上传" → Upload
+- 业务页面需要"流程设计器" → BpmnDesigner
+
+## 不触发
+- 通用 UI 组件（Button/Table/Form）→ 直接用 antd
+- 业务特定组件（自定义表格）→ 业务自己封装
+- 前端部署 → 用 `meritdata-platform-frontend-deploy`
+
+## 前置约束
+- 平台组件基于 antd，二开**必须**复用平台组件而非自实现
+- 组件 props 必须与平台 API 一致（人员选择器接 userClient）
+- 组件主题样式遵循平台 design token
+
+## 路由
+- 组件清单 + 基础用法 → [references/guide.md](references/guide.md)
+- 业务组件封装示例 → [references/business-wrappers.md](references/business-wrappers.md)
+- 主题定制 + 国际化 → [references/theme-and-i18n.md](references/theme-and-i18n.md)
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-ui-components/references/business-wrappers.md

@@ -0,0 +1,233 @@
+# 业务组件封装（ui-components）
+
+> 在平台组件基础上封装业务组件，统一业务 UI。
+
+---
+
+## 1. 业务组件分层
+
+```
+@meritdata/platform-ui-components      平台组件（基础设施）
+    ↓
+@your-org/business-ui-components       业务组件（基于平台）
+    ↓
+业务页面
+```
+
+## 2. 封装模式
+
+### 2.1 OrderUserPicker
+
+```tsx
+// business-ui-components/OrderUserPicker.tsx
+import { UserPicker } from '@meritdata/platform-ui-components';
+import { AuthUtils } from '@/utils/auth';
+
+export const OrderUserPicker: React.FC<OrderUserPickerProps> = (props) => {
+  const { orderType, ...rest } = props;
+
+  // 业务规则：根据订单类型限定可选人员
+  const config = useMemo(() => {
+    if (orderType === 'BULK') {
+      return { roleCode: 'BULK_ORDER_APPROVER' };
+    }
+    return { roleCode: 'ORDER_APPROVER' };
+  }, [orderType]);
+
+  return <UserPicker {...rest} {...config} />;
+};
+```
+
+### 2.2 OrderStatusSelect
+
+```tsx
+// business-ui-components/OrderStatusSelect.tsx
+import { LookupSelect } from '@meritdata/platform-ui-components';
+
+const STATUS_BY_TYPE = {
+  SALES: 'SALES_ORDER_STATUS',
+  PURCHASE: 'PURCHASE_ORDER_STATUS',
+};
+
+export const OrderStatusSelect: React.FC<Props> = ({ orderType, ...rest }) => {
+  return (
+    <LookupSelect
+      typeCode={STATUS_BY_TYPE[orderType]}
+      {...rest}
+    />
+  );
+};
+```
+
+## 3. 高阶组件
+
+### 3.1 withPermission
+
+```tsx
+export function withPermission<T>(
+  WrappedComponent: React.ComponentType<T>,
+  permission: string
+) {
+  return (props: T) => {
+    const hasPermission = useAuth().hasPermission(permission);
+    return hasPermission ? <WrappedComponent {...props} /> : null;
+  };
+}
+
+// 用法
+const ApproveButton = withPermission(Button, 'order:approve');
+```
+
+### 3.2 withBusinessContext
+
+```tsx
+export function withBusinessContext<T>(
+  WrappedComponent: React.ComponentType<T>
+) {
+  return (props: T) => {
+    const businessContext = useBusinessContext();  // 全局业务上下文
+    return <WrappedComponent {...props} {...businessContext} />;
+  };
+}
+```
+
+## 4. 表单组件
+
+### 4.1 OrderForm
+
+```tsx
+import { Form, Input, InputNumber, DatePicker } from 'antd';
+import { UserPicker, OrgTreeSelect, LookupSelect } from '@meritdata/platform-ui-components';
+
+export const OrderForm: React.FC<OrderFormProps> = ({ initialValues, onSubmit }) => {
+  const [form] = Form.useForm();
+
+  return (
+    <Form form={form} initialValues={initialValues} onFinish={onSubmit}>
+      <Form.Item label="订单号" name="orderNo" rules={[{ required: true }]}>
+        <Input />
+      </Form.Item>
+
+      <Form.Item label="金额" name="amount" rules={[{ required: true }]}>
+        <InputNumber style={{ width: '100%' }} />
+      </Form.Item>
+
+      <Form.Item label="负责人" name="ownerId">
+        <UserPicker />
+      </Form.Item>
+
+      <Form.Item label="部门" name="orgId">
+        <OrgTreeSelect />
+      </Form.Item>
+
+      <Form.Item label="类型" name="type">
+        <LookupSelect typeCode="ORDER_TYPE" />
+      </Form.Item>
+
+      <Form.Item label="下单日期" name="orderDate">
+        <DatePicker style={{ width: '100%' }} />
+      </Form.Item>
+
+      <Button type="primary" htmlType="submit">提交</Button>
+    </Form>
+  );
+};
+```
+
+## 5. 表格组件
+
+### 5.1 OrderTable
+
+```tsx
+import { DataTable } from '@meritdata/platform-ui-components';
+import { OrderStatusSelect } from './OrderStatusSelect';
+
+export const OrderTable: React.FC = () => {
+  return (
+    <DataTable
+      columns={[
+        { title: '订单号', dataIndex: 'orderNo', width: 150 },
+        { title: '金额', dataIndex: 'amount', width: 120 },
+        {
+          title: '状态',
+          dataIndex: 'status',
+          width: 100,
+          render: (status) => <OrderStatusTag status={status} />  // 业务标签组件
+        },
+        { title: '负责人', dataIndex: 'ownerName', width: 100 },
+        { title: '创建时间', dataIndex: 'createTime', width: 180 },
+        {
+          title: '操作',
+          width: 200,
+          render: (_, record) => <OrderActions order={record} />
+        }
+      ]}
+      dataSource={orders}
+    />
+  );
+};
+```
+
+## 6. 详情组件
+
+### 6.1 OrderDetail
+
+```tsx
+import { Descriptions } from 'antd';
+import { UserPicker } from '@meritdata/platform-ui-components';
+
+export const OrderDetail: React.FC<{OrderDetailProps}> = ({ order }) => {
+  return (
+    <Descriptions column={2} bordered>
+      <Descriptions.Item label="订单号">{order.orderNo}</Descriptions.Item>
+      <Descriptions.Item label="金额">{order.amount}</Descriptions.Item>
+      <Descriptions.Item label="状态">
+        <OrderStatusTag status={order.status} />
+      </Descriptions.Item>
+      <Descriptions.Item label="负责人">
+        <UserPicker readonly value={order.ownerId} />
+      </Descriptions.Item>
+      <Descriptions.Item label="创建时间">{order.createTime}</Descriptions.Item>
+      <Descriptions.Item label="备注">{order.remark}</Descriptions.Item>
+    </Descriptions>
+  );
+};
+```
+
+## 7. ❌ 反模式
+
+### 7.1 ❌ 业务组件绕过平台组件
+
+```tsx
+// ❌ 错：业务自己写选择器，不用 UserPicker
+const CustomUserPicker = () => {
+  const [users, setUsers] = useState([]);
+  // 自己调 userClient.listByOrg()...
+  // ...
+};
+```
+
+✅ 用 `UserPicker` + props 覆盖。
+
+### 7.2 ❌ 每个页面重复写表单
+
+```tsx
+// ❌ 错：订单新建页 + 编辑页 + 详情页各自写 Form
+```
+
+✅ 封装 `OrderForm` 复用。
+
+### 7.3 ❌ 业务样式硬编码
+
+```tsx
+// ❌ 错
+<Button style={{ backgroundColor: '#1890ff', fontSize: 14 }}>提交</Button>
+```
+
+✅ 用 design token。
+
+## 8. 关联阅读
+
+- [guide.md](guide.md) — 平台组件基础
+- [theme-and-i18n.md](theme-and-i18n.md) — 主题 + 国际化
+- [SKILL.md](../SKILL.md)