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

package/skills/meritdata-platform-ui-components/references/guide.md

@@ -0,0 +1,199 @@
+# 平台 UI 组件基础指南（ui-components）
+
+> 平台 UI 组件基于 antd 封装，统一了人员、组织、字典、上传等通用场景。
+
+---
+
+## 1. 引入
+
+```bash
+npm install @meritdata/platform-ui-components
+```
+
+```typescript
+import { UserPicker, OrgTreeSelect, LookupSelect, Upload } from '@meritdata/platform-ui-components';
+```
+
+## 2. 组件清单
+
+| 组件 | 用途 | 替代自实现 |
+|------|------|-----------|
+| UserPicker | 人员选择（单/多）| ✅ |
+| OrgTreeSelect | 组织树下拉 | ✅ |
+| LookupSelect | 字典下拉 | ✅ |
+| LookupCascader | 字典级联 | ✅ |
+| Upload | 文件上传 | ✅ |
+| BpmnDesigner | 流程设计器 | ✅ |
+| RichTextEditor | 富文本编辑器 | ✅ |
+| DateRangePicker | 日期范围 | 部分 |
+| DataTable | 业务表格（含权限列）| ✅ |
+| AuthButton | 按钮（带权限）| ✅ |
+
+## 3. UserPicker
+
+### 3.1 基本用法
+
+```tsx
+import { UserPicker } from '@meritdata/platform-ui-components';
+
+<Form.Item label="负责人" name="ownerId">
+  <UserPicker
+    multiple={false}
+    orgId={currentOrgId}
+    placeholder="选择负责人"
+  />
+</Form.Item>
+```
+
+### 3.2 Props
+
+| Prop | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| multiple | boolean | false | 是否多选 |
+| orgId | string | - | 限定组织范围 |
+| roleCode | string | - | 限定角色范围 |
+| disabled | boolean | false | 禁用 |
+| excludeUserIds | string[] | - | 排除某些用户 |
+
+### 3.3 返回值
+
+```typescript
+{
+  userId: '10001',
+  realName: '张三',
+  username: 'zhangsan',
+  orgName: '研发部'
+}
+```
+
+## 4. OrgTreeSelect
+
+```tsx
+import { OrgTreeSelect } from '@meritdata/platform-ui-components';
+
+<Form.Item label="所属部门" name="orgId">
+  <OrgTreeSelect
+    multiple={false}
+    showLeafOnly={false}
+    placeholder="选择部门"
+  />
+</Form.Item>
+```
+
+Props：
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| multiple | boolean | 多选 |
+| showLeafOnly | boolean | 只显示叶子节点 |
+| rootOrgId | string | 根节点（限制范围）|
+
+## 6. LookupSelect
+
+```tsx
+import { LookupSelect } from '@meritdata/platform-ui-components';
+
+<Form.Item label="订单状态" name="status">
+  <LookupSelect typeCode="ORDER_STATUS" placeholder="选择状态" />
+</Form.Item>
+```
+
+Props：
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| typeCode | string | 字典类型编码 |
+| multiple | boolean | 多选 |
+| showCode | boolean | 是否显示 code |
+
+## 7. Upload
+
+### 7.1 基本用法
+
+```tsx
+import { Upload } from '@meritdata/platform-ui-components';
+
+<Upload
+  bizType="ORDER_ATTACHMENT"
+  bizId={orderId}
+  accept=".pdf,.doc,.docx"
+  maxSize={50}              // 50 MB
+  onChange={(files) => console.log(files)}
+/>
+```
+
+### 7.2 平台上传组件特性
+
+- 自动关联业务（bizType + bizId）
+- 集成平台存储（OSS / 本地）
+- 自动生成缩略图（图片类型）
+- 病毒扫描（可选）
+
+## 8. AuthButton（带权限）
+
+```tsx
+import { AuthButton } from '@meritdata/platform-ui-components';
+
+<AuthButton permission="order:approve" type="primary" onClick={handleApprove}>
+  审批
+</AuthButton>
+```
+
+无权限 → 按钮不显示。
+
+## 9. DataTable
+
+### 9.1 用法
+
+```tsx
+import { DataTable } from '@meritdata/platform-ui-components';
+
+<DataTable
+  columns={[
+    { title: '订单号', dataIndex: 'orderNo' },
+    {
+      title: '金额',
+      dataIndex: 'amount',
+      sensitive: true,           // 自动脱敏
+      permission: 'order:cost:view'  // 仅财务可见
+    }
+  ]}
+  dataSource={orders}
+  pageSize={20}
+/>
+```
+
+## 10. ❌ 反模式
+
+### 10.1 ❌ 自实现人员选择器
+
+```tsx
+// ❌ 错：自己写人员选择 + 接口调用
+const <Select onClick="fetchUsers" />
+```
+
+✅ 用 `UserPicker`。
+
+### 10.2 ❌ 自实现权限按钮
+
+```tsx
+// ❌ 错
+{permissions.includes('order:approve') && <Button>审批</Button>}
+```
+
+✅ 用 `AuthButton`。
+
+### 10.3 ❌ 自实现上传
+
+```tsx
+// ❌ 错：自己写 upload + 调 OSS
+const <input type="file" onClick="handleUpload" />
+```
+
+✅ 用 `Upload`（关联 bizType + 病毒扫描）。
+
+## 11. 关联阅读
+
+- [business-wrappers.md](business-wrappers.md) — 业务组件封装
+- [theme-and-i18n.md](theme-and-i18n.md) — 主题定制 + 国际化
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-ui-components/references/theme-and-i18n.md

@@ -0,0 +1,226 @@
+# 主题定制与国际化（ui-components）
+
+> 主题令牌（design token）/ 国际化（i18n）/ 暗色模式。
+
+---
+
+## 1. Design Token
+
+### 1.1 平台默认令牌
+
+```typescript
+// @meritdata/platform-ui-components/theme/tokens.ts
+export const tokens = {
+  colorPrimary: '#1890ff',
+  colorSuccess: '#52c41a',
+  colorWarning: '#faad14',
+  colorError: '#ff4d4f',
+  colorInfo: '#1890ff',
+
+  fontSize: 14,
+  borderRadius: 4,
+
+  spacing: {
+    xs: 4,
+    sm: 8,
+    md: 16,
+    lg: 24,
+    xl: 32,
+  },
+};
+```
+
+### 1.2 使用
+
+```tsx
+import { theme } from 'antd';
+import { tokens } from '@meritdata/platform-ui-components/theme';
+
+const { token } = theme.useToken();
+
+<Button style={{ backgroundColor: tokens.colorPrimary }}>
+  主要按钮
+</Button>
+```
+
+### 1.3 业务定制
+
+```typescript
+// business-ui-components/theme.ts
+export const businessTokens = {
+  ...tokens,
+  colorPrimary: '#FF6B35',     // 业务色
+  fontSize: 13,
+  borderRadius: 6,
+};
+
+// 全局覆盖
+import { ConfigProvider } from 'antd';
+
+<ConfigProvider theme={{ token: businessTokens }}>
+  <App />
+</ConfigProvider>
+```
+
+## 2. 暗色模式
+
+### 2.1 平台支持
+
+```tsx
+import { ConfigProvider, theme as antdTheme } from 'antd';
+
+<ConfigProvider
+  theme={{
+    algorithm: isDark ? antdTheme.darkAlgorithm : antdTheme.defaultAlgorithm,
+  }}
+>
+  <App />
+</ConfigProvider>
+```
+
+### 2.2 切换按钮
+
+```tsx
+import { Switch } from 'antd';
+import { useTheme } from '@/hooks/useTheme';
+
+const { isDark, toggleTheme } = useTheme();
+
+<Switch
+  checked={isDark}
+  onChange={toggleTheme}
+  checkedChildren="🌙"
+  unCheckedChildren="☀️"
+/>
+```
+
+### 2.3 业务组件适配
+
+```tsx
+import { theme } from 'antd';
+
+const { token } = theme.useToken();
+
+<Card style={{ backgroundColor: token.colorBgContainer }}>
+  ...
+</Card>
+```
+
+## 3. 国际化（i18n）
+
+### 3.1 平台 i18n 配置
+
+```typescript
+// @meritdata/platform-ui-components/locale/
+import zh_CN from '@meritdata/platform-ui-components/locale/zh_CN';
+import en_US from '@meritdata/platform-ui-components/locale/en_US';
+
+<ConfigProvider locale={currentLocale}>
+  <App />
+</ConfigProvider>
+```
+
+### 3.2 业务 i18n（react-i18next）
+
+```bash
+npm install react-i18next i18next
+```
+
+```typescript
+// i18n/config.ts
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import zh_CN from './locales/zh_CN.json';
+import en_US from './locales/en_US.json';
+
+i18n.use(initReactI18next).init({
+  resources: {
+    'zh-CN': { translation: zh_CN },
+    'en-US': { translation: en_US },
+  },
+  lng: localStorage.getItem('lang') || 'zh-CN',
+  fallbackLng: 'zh-CN',
+});
+```
+
+### 3.3 使用
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+const { t } = useTranslation();
+
+<Button>{t('order.create')}</Button>
+<LookupSelect typeCode="ORDER_STATUS" placeholder={t('order.status.placeholder')} />
+```
+
+### 3.4 字典项多语言
+
+字典项支持多语言（详见 [lookup-api tree-and-i18n](../meritdata-platform-lookup-api/references/tree-and-i18n.md)）：
+
+```typescript
+<LookupSelect
+  typeCode="ORDER_STATUS"
+  lang={currentLang}
+/>
+```
+
+## 4. 主题与 i18n 集成
+
+```tsx
+import { ConfigProvider } from 'antd';
+import { useTranslation } from 'react-i18next';
+import { useTheme } from '@/hooks/useTheme';
+
+const App: React.FC = () => {
+  const { i18n } = useTranslation();
+  const { isDark } = useTheme();
+
+  return (
+    <ConfigProvider
+      locale={getAntdLocale(i18n.language)}
+      theme={{ algorithm: isDark ? darkAlgorithm : defaultAlgorithm }}
+    >
+      <Router />
+    </ConfigProvider>
+  );
+};
+```
+
+## 5. ❌ 反模式
+
+### 5.1 ❌ 硬编码颜色
+
+```tsx
+// ❌ 错
+<Button style={{ backgroundColor: '#1890ff' }}>提交</Button>
+```
+
+✅ 用 design token。
+
+### 5.2 ❌ 硬编码文案
+
+```tsx
+// ❌ 错
+<Button>提交</Button>
+```
+
+✅ 用 i18n：`{t('common.submit')}`。
+
+### 5.3 ❌ 多语言未覆盖所有语言
+
+```json
+// ❌ 错：zh-CN 有 100 条，en-US 只有 50 条
+{
+  "zh-CN": {...100条...},
+  "en-US": {...50条...}
+}
+```
+
+✅ 关键文案双语 100% 覆盖。
+
+## 6. 关联阅读
+
+- [guide.md](guide.md) — 平台组件基础
+- [business-wrappers.md](business-wrappers.md) — 业务组件封装
+- [SKILL.md](../SKILL.md)

package/tools/skill-authoring-workflow/README.md

@@ -0,0 +1,260 @@
+# skill-authoring-workflow
+
+> 新建 skill 的标准工作流：模板 + 校验清单 + 流程。
+
+---
+
+## 1. 新建 skill 流程
+
+```
+1. 选定 layer / sub-layer / stack
+       ↓
+2. 复制模板
+       ↓
+3. 填 SKILL.md frontmatter
+       ↓
+4. 写触发 / 不触发 / 前置约束 / 路由
+       ↓
+5. 编写 references/*.md（详细文档）
+       ↓
+6. 运行 skill-vetter 校验
+       ↓
+7. 提交 PR
+       ↓
+8. 架构组 review
+```
+
+## 2. 模板
+
+### 2.1 SKILL.md 模板
+
+```yaml
+---
+name: meritdata-platform-<topic>
+description: <一句话描述 + 触发关键词>。当用户说"<关键词1> / <关键词2> / <关键词3>"时使用。
+metadata:
+  version: "1.0.0"
+  risk: low|medium|high
+  layer: L1 | L2 | L3 | L4
+  sub-layer: L2-M | L2-C | L2-F | L3-C | L3-F | L4-T
+  stack: methodology | java | frontend | tool
+---
+
+# meritdata-platform-<topic>
+
+## 触发
+
+- 用户说"<关键词1>"
+- 用户说"<关键词2>"
+- <场景 3>
+- <场景 4>
+
+## 不触发
+
+- <场景 A>（→ `<其他 skill>`）
+- <场景 B>（→ `<其他 skill>`）
+- <场景 C>（→ `<其他 skill>`）
+
+## 前置约束
+
+- 必须先读 `<rules 文件 1>`
+- 必须遵守 `<rules 文件 2>` §章节
+- 必须引用 `<rules 文件 3>`
+
+## 路由
+
+- [guide.md](references/guide.md) — <一句话说明>
+- [topic-a.md](references/topic-a.md) — <一句话说明>
+- [topic-b.md](references/topic-b.md) — <一句话说明>
+```
+
+### 2.2 references/*.md 模板
+
+```markdown
+# <标题>
+
+> <一句话说明本文件主题>。
+
+---
+
+## 1. <章节 1>
+
+<内容>
+
+### 1.1 <子章节>
+
+```java
+// 代码示例
+```
+
+### 1.2 <子章节>
+
+<内容>
+
+## 2. <章节 2>
+
+<内容>
+
+---
+
+## ❌ 反模式
+
+### <反模式 1>
+
+```java
+// ❌ 错
+```
+
+```java
+// ✅ 正确
+```
+
+---
+
+## 关联阅读
+
+- [guide.md](guide.md) — <一句话>
+- [SKILL.md](../SKILL.md)
+```
+
+详见 [templates/SKILL-template.md](templates/SKILL-template.md) 和 [templates/references-template.md](templates/references-template.md)。
+
+## 3. 命名规范
+
+### 3.1 Skill 命名
+
+```
+meritdata-platform-<topic>
+```
+
+| 类别 | 命名示例 |
+|------|---------|
+| L1 入口 | `meritdata-platform-playbook` |
+| L2 方法论 | `meritdata-platform-code-spec` |
+| L2 平台能力 | `meritdata-platform-bpm` |
+| L3 单点 API | `meritdata-platform-cache` |
+| L4 工具 | `meritdata-bootstrap-2nd-dev` |
+
+### 3.2 文件命名
+
+| 类型 | 规则 |
+|------|------|
+| SKILL.md | 固定名 |
+| references/ | kebab-case.md |
+| 索引文件 | guide.md / README.md |
+
+## 4. 前置约束写法
+
+**必须**引用 rules 文件，**禁止**重复 rules 正文：
+
+```markdown
+## 前置约束
+
+- 必须遵守 [`rules/code-dev-rules.md`](../../rules/code-dev-rules.md) §八
+- 必须遵守 [`rules/meritdata-platform-data-boundary.md`](../../rules/meritdata-platform-data-boundary.md) §1.1
+- 必须引用 [`rules/naming-conventions-rules.md`](../../rules/naming-conventions-rules.md)
+```
+
+## 5. 路由写法
+
+**必须**指向 `references/*.md`，**禁止**指向 rules：
+
+```markdown
+## 路由
+
+- [guide.md](references/guide.md) — 总览
+- [topic-a.md](references/topic-a.md) — 主题 A
+- [topic-b.md](references/topic-b.md) — 主题 B
+```
+
+## 6. 校验清单
+
+新建 skill 后，跑 [skill-vetter](../skill-vetter/README.md)：
+
+```bash
+bash tools/skill-vetter/run.sh meritdata-platform-new-skill
+```
+
+通过条件：
+
+- [ ] frontmatter 含所有必填字段
+- [ ] 4 大章节齐全（触发 / 不触发 / 前置约束 / 路由）
+- [ ] SKILL.md 行数 ≤ 60
+- [ ] references/ 至少 1 个文件
+- [ ] 前置约束引用 rules（不重复正文）
+- [ ] 路由指向 references/（不指向 rules）
+
+## 7. PR 模板
+
+```markdown
+## 新建 skill: meritdata-platform-<topic>
+
+**Layer**: L2-M / L2-C / L2-F / L3-C / L3-F / L4-T
+**Stack**: methodology / java / frontend / tool
+**Risk**: low / medium / high
+
+### 背景
+
+<为什么需要这个 skill>
+
+### 内容
+
+- SKILL.md（~38 行）：触发 / 不触发 / 前置约束 / 路由
+- references/guide.md：总览
+- references/topic-a.md：主题 A
+- references/topic-b.md：主题 B
+
+### 校验
+
+- [ ] skill-vetter 通过
+- [ ] 引用了正确的 rules
+- [ ] 没有重复 rules 正文
+
+### Reviewer
+
+@架构组
+```
+
+## 8. ❌ 反模式
+
+### 8.1 ❌ SKILL.md 直接写铁律
+
+```markdown
+❌ 错：
+## 数据访问边界
+1. 不映射 PF_ 平台表
+2. 不分页循环 Feign
+...
+
+✅ 正确：
+## 前置约束
+- 必须遵守 `rules/meritdata-platform-data-boundary.md`
+```
+
+### 8.2 ❌ references 写"是什么"
+
+```markdown
+❌ 错：
+# 缓存是什么
+缓存是一种...
+
+✅ 正确：
+# 多级缓存配置指南
+## 1. Caffeine L1 配置
+...
+```
+
+### 8.3 ❌ SKILL.md 行数过长
+
+```markdown
+❌ 错：SKILL.md 100 行（详情都在）
+
+✅ 正确：SKILL.md 38 行（路由），详情在 references/
+```
+
+## 9. 关联阅读
+
+- [templates/SKILL-template.md](templates/SKILL-template.md) — SKILL.md 模板
+- [templates/references-template.md](templates/references-template.md) — references 模板
+- [../skill-vetter/README.md](../skill-vetter/README.md) — 校验
+- [../skill-stocktake/README.md](../skill-stocktake/README.md) — 清单盘点

package/tools/skill-authoring-workflow/templates/SKILL-template.md

@@ -0,0 +1,35 @@
+---
+name: meritdata-platform-<topic>
+description: <一句话描述，包含 3-5 个触发关键词>。当用户说"<kw1> / <kw2> / <kw3>"时使用。
+metadata:
+  version: "1.0.0"
+  risk: low
+  layer: L3
+  sub-layer: L3-C
+  stack: java
+---
+
+# meritdata-platform-<topic>
+
+## 触发
+
+- 用户说"<kw1>"
+- 用户说"<kw2>"
+- <场景 3>
+- <场景 4>
+
+## 不触发
+
+- <场景 A>（→ `meritdata-platform-<other-skill>`）
+- <场景 B>（→ `meritdata-platform-<other-skill>`）
+
+## 前置约束
+
+- 必须遵守 [`rules/code-dev-rules.md`](../../rules/code-dev-rules.md)
+- 必须遵守 [`rules/naming-conventions-rules.md`](../../rules/naming-conventions-rules.md)
+
+## 路由
+
+- [guide.md](references/guide.md) — 总览
+- [topic-a.md](references/topic-a.md) — 主题 A
+- [topic-b.md](references/topic-b.md) — 主题 B