@alanwang-merit/meritdata-platform-skill-package 1.0.10 → 1.0.11

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

@@ -1,330 +0,0 @@
-# 单元测试（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/references/business-wrappers.md

@@ -1,233 +0,0 @@
-# 业务组件封装（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)