From ac7fdfc3161d70464851a134b9d4b7f55c2fa200 Mon Sep 17 00:00:00 2001 From: weishen Date: Sat, 25 Apr 2026 09:55:51 +0800 Subject: [PATCH] Sync: expand ui system components notes --- Project/fonrey/UI_SYSTEM/UI_SYSTEM.md | 79 +- Project/fonrey/UI_SYSTEM/preview.html | 25 + Project/fonrey/UI_SYSTEM/组件规范设计.md | 1992 +++++++++++++++++ wiki/index.md | 6 +- wiki/log.md | 26 + wiki/overview.md | 4 + wiki/sources/compliance-auditor.md | 60 + wiki/sources/specialized-mcp-builder.md | 55 + .../specialized-salesforce-architect.md | 56 + 9 files changed, 2285 insertions(+), 18 deletions(-) create mode 100644 Project/fonrey/UI_SYSTEM/组件规范设计.md create mode 100644 wiki/sources/compliance-auditor.md create mode 100644 wiki/sources/specialized-mcp-builder.md create mode 100644 wiki/sources/specialized-salesforce-architect.md diff --git a/Project/fonrey/UI_SYSTEM/UI_SYSTEM.md b/Project/fonrey/UI_SYSTEM/UI_SYSTEM.md index 8b7e2f44..df997a95 100644 --- a/Project/fonrey/UI_SYSTEM/UI_SYSTEM.md +++ b/Project/fonrey/UI_SYSTEM/UI_SYSTEM.md @@ -1,6 +1,6 @@ # Fonrey UI System 设计规范 -**版本**：v1.0 +**版本**：v1.1 **最后更新**：2026-04-25 **维护者**：UI/UX 架构组 **适用技术栈**：Tailwind CSS + HTMX + Alpine.js + Django 模板 @@ -21,7 +21,7 @@ - **专业、克制、高密度**：表格为王，单屏尽可能多展示数据；色彩只为信息服务，不用于装饰。 - **主色靛青（Teal）**：低饱和、冷静，与状态色（绿/黄/红）形成强区分；与房产行业"稳健/可靠"意象吻合，同时避免与 success 绿产生语义歧义。 - **中等圆角（8px）**：既不像消费端（12px+）过于柔软，也不像传统企业端（0-2px）过于呆板。 -- **紧凑密度**：表格行高 40px、表单字段间距 12px，信息密度优先于呼吸感。 +- **紧凑密度**：表格默认行高 56px（含 40×40 封面缩略图），表单字段间距 12px，信息密度优先于呼吸感。 --- @@ -407,14 +407,24 @@ Fonrey 的核心场景，规范必须严格执行。 | 外壳 | 圆角卡片容器 | `bg-white rounded-lg border border-neutral-200 overflow-hidden` | | 表头 `` | 粘性、小字、中性色底 | `bg-neutral-50 text-xs font-medium text-neutral-500 uppercase tracking-wider sticky top-0 z-10` | | 表头 `` | 高 36px；排序箭头右对齐 | `px-4 py-2 text-left` | -| 数据行 `` | 高 44px；Hover 高亮 | `hover:bg-neutral-50` | -| 数据单元 `` | 正文字号；顶对齐 | `px-4 py-2.5 text-sm text-neutral-700 whitespace-nowrap` | -| 选中行 | 浅主色高亮 | `bg-primary-50` | -| 操作列 | 固定右侧；Ghost 图标按钮 | `sticky right-0 bg-white` | +| 数据行 `` | 密度可切换；Hover 高亮 | `hover:bg-neutral-50` | +| 数据单元 `` | 正文字号；垂直居中 | `px-3 py-3 text-sm text-neutral-700 align-middle whitespace-nowrap` | +| 选中行 | 浅主色高亮 | `bg-primary-50/40` | +| 操作列 | 固定右侧；Ghost 图标按钮，Hover 显形 | `sticky right-0 bg-white opacity-0 group-hover:opacity-100` | | 表格底部（分页栏） | | `px-4 py-3 border-t border-neutral-200 bg-white flex items-center justify-between` | - **斑马纹**：B2B 高密度场景**不启用**（视觉噪音）。Hover 行高亮已足够区分。 -- **密度切换**：工具栏右侧允许用户切换"紧凑（40px）/ 标准（44px）/ 舒适（52px）"三档，通过 Alpine.js + `localStorage` 持久化。 +- **封面缩略图**：房源/楼盘等含图业务表格，第一数据列（通常为"标题"列）内嵌缩略图（`` 或占位 `
`），尺寸随密度档联动（见下表）。缩略图统一 `rounded` (4px)，对象填充 `object-cover`，加载失败占位为 `bg-neutral-100` + 图片占位图标。 +- **三档密度**：工具栏右侧"密度"图标按钮切换，Alpine.js + `localStorage`（key: `fonrey:table:{module}:density`）持久化，默认 `standard`。 + +| 档位 | Key | 行高 | 缩略图尺寸 | 单元内边距 | 使用场景 | +|---|---|---|---|---|---| +| 紧凑 Compact | `compact` | 40px | 无（图片列隐藏） | `px-3 py-2` | 数据核对、大批量浏览、导出前预览 | +| 标准 Standard（默认） | `standard` | 56px | 40×40 | `px-3 py-3` | 日常工作，"一眼认房" | +| 舒适 Comfortable | `comfortable` | 72px | 56×56 | `px-3 py-4` | 含更多副信息（楼层/朝向/装修标签换行展示） | + +> **实现提示**：密度切换仅改 `` 上的 class（如 `table-density-standard`），通过父级 class + 子选择器统一控制行高、内边距、图片显隐，避免逐行改 class。 +> **无图业务**（客源、跟进记录、权限等）表格固定使用 `compact` 40px 行高，不提供密度切换。 #### 3.4.2 标准片段 @@ -1219,19 +1229,58 @@ Flatpickr 自定义样式覆盖见附录 10.3。 --- -## 9. 待确认问题（Open Questions） +## 9. 已决策事项（Resolved Decisions） -| # | 问题 | 负责人 | 截止 | +v1.0 遗留的 6 个问题，已于 v1.1 评审决策如下。 + +| # | 问题 | 决策 | 实施要点 | |---|---|---|---| -| 1 | 需要暗色主题吗？（部分经纪人工作至深夜） | 产品 | v1.1 评估 | -| 2 | 全局搜索（`Ctrl+K` Command Palette）的信息架构：是否跨模块（房源+客源+楼盘+员工） | 产品 / 后端 | v1 首发范围待定 | -| 3 | 表格列是否支持拖拽调整顺序？（SortableJS 可支持，但需确认是否属于 v1 范围） | 产品 | — | -| 4 | 房源状态色：当前将"已成交"归为 primary（Teal）。部分行业习惯用蓝色，需确认是否可视化区分 | 设计 / 产品 | — | -| 5 | 移动端访问降级方案：v1 是否需要 1024px 以下显示"请使用桌面端访问"提示页？ | 前端 | v1 首发前 | -| 6 | 国际化：当前仅中文。如规划英文/繁体，字体栈与行高需调整 | 产品 | v2 | +| 1 | 是否支持暗色主题 | **v1 不做，开发预留接口** | 所有颜色走 Tailwind Token（不硬编码 Hex）；根标签预留 `data-theme="light"` 属性；CSS 变量层接入待 v2 | +| 2 | 全局搜索（⌘K）覆盖范围 | **房源 + 客源 + 楼盘 + 同事 四类** | Command Palette 分组展示；↑↓ 切换、Enter 跳转、ESC 关闭；后端接口 `/api/search/?q=&types=property,customer,building,user` | +| 3 | 表格列是否支持拖拽排序 | **支持：拖拽 + 显隐 + localStorage 记忆** | SortableJS；"列设置"Drawer 右侧打开；状态 key `fonrey:table:{module}:cols`，结构 `[{key, visible, order}]` | +| 4 | 已成交状态色 | **info 蓝（`#2563EB`）** | 仅用于状态 Tag，不扩散到其他元素；与 success 绿（在售）、warning 橙（待核验）、neutral 灰（已下架）形成完整状态色阶 | +| 5 | 屏幕 <1280px 降级 | **显示引导提示页，锁定主内容** | 全屏 Splash：品牌 logo + "Fonrey 为桌面端设计，请放大浏览器窗口或使用 ≥1280px 屏幕"；JS 监听 resize 自动显隐；不做响应式适配 | +| 6 | 国际化 | **v1 仅中文，文案硬编码** | 但 Token 层保持中性（不嵌入"万""㎡"等单位到 Token 名）；字体栈保留 Inter + PingFang SC 双语准备；v2 接入 Django i18n 时无需重构组件 | + +### 9.1 小屏降级提示页（规范） + +```html + +
+
F
+

请使用桌面端访问 Fonrey

+

+ Fonrey 为桌面工作场景设计，建议屏幕宽度 ≥ 1280px。 + 请放大浏览器窗口，或切换到电脑端访问。 +

+

当前窗口： px

+
+``` + +- 触发阈值：`window.innerWidth < 1280` +- 不阻止登录、不阻止 Token 校验，仅遮罩 UI +- 移动端浏览器同样展示此页（不引导下载 App，v1 无 App） + +### 9.2 全局搜索（⌘K）数据结构约定 + +```js +// 返回示例 +{ + "property": [{id, code, title, status, subtitle}], // 房源：F编号 + 标题 + 商圈 + "customer": [{id, name, phone_mask, tag, subtitle}], // 客源：姓名 + 脱敏手机 + 意向 + "building": [{id, name, district, unit_price}], // 楼盘：名称 + 商圈 + 均价 + "user": [{id, name, dept, avatar_char}] // 同事：姓名 + 部门 +} +``` + +- 分组固定顺序：房源 → 客源 → 楼盘 → 同事 +- 每组最多 5 条，更多结果跳对应模块列表页 +- 空查询时展示"最近访问"（前 8 条，不分组） --- + ## 10. 附录（Appendix） ### 10.1 完整 Tailwind 配置文件 diff --git a/Project/fonrey/UI_SYSTEM/preview.html b/Project/fonrey/UI_SYSTEM/preview.html index 6b5ed8f5..74b87ae8 100644 --- a/Project/fonrey/UI_SYSTEM/preview.html +++ b/Project/fonrey/UI_SYSTEM/preview.html @@ -787,4 +787,29 @@
+ diff --git a/Project/fonrey/UI_SYSTEM/组件规范设计.md b/Project/fonrey/UI_SYSTEM/组件规范设计.md new file mode 100644 index 00000000..d0496f51 --- /dev/null +++ b/Project/fonrey/UI_SYSTEM/组件规范设计.md @@ -0,0 +1,1992 @@ +# Fonrey 组件规范设计文档 + +> **版本**：v1.0 · **日期**：2026-04-25 +> **依赖基准**：`UI_SYSTEM.md v1.1` +> **技术栈**：Tailwind CSS + HTMX + Alpine.js + Django 模板（非 JSX） +> **设计语言**：专业克制高密度；主色 Teal `#0F766E`；圆角 `rounded-lg`（8px）；桌面优先 ≥1280px + +--- + +## 目录 + +1. [Data Table — 可排序多选数据表格](#1-data-table) +2. [Pagination — 分页组件](#2-pagination) +3. [Column Visibility Panel — 自定义列显示](#3-column-visibility-panel) +4. [Toolbar — 操作工具栏](#4-toolbar) +5. [Export Button — 导出按钮](#5-export-button) +6. [Smart Sort — 智能排序切换](#6-smart-sort) +7. [Modal Dialog — 模态对话框](#7-modal-dialog) +8. [Tree Select — 树形下拉选择器](#8-tree-select) +9. [Date Range Picker — 日期范围选择器](#9-date-range-picker) +10. [Tab Navigation — 标签页导航](#10-tab-navigation) +11. [Collapsible Card Grid — 可折叠卡片网格](#11-collapsible-card-grid) +12. [Photo Gallery Manager — 相册管理器](#12-photo-gallery-manager) +13. [Image Lightbox Viewer — 全屏图片灯箱](#13-image-lightbox-viewer) +14. [Accordion Progress Panel — 折叠进度检查面板](#14-accordion-progress-panel) +15. [Inline Edit Mode — 页面级读写切换](#15-inline-edit-mode) +16. [Drawer / Slide-over Panel — 右侧抽屉面板](#16-drawer--slide-over-panel) +17. [Multi-select Tag Input — 多选标签选择器](#17-multi-select-tag-input) +18. [Dynamic Form Table — 动态可增删行表格](#18-dynamic-form-table) +19. [Sortable Table with Drag Handle — 带拖拽手柄排序表格](#19-sortable-table-with-drag-handle) +20. [Multi-Table Independent Pagination — 同页多表格独立分页](#20-multi-table-independent-pagination) + +--- + +## 1. Data Table + +**正式名称**：Sortable Data Table with Column Visibility Control + +### 1.1 视觉规格 + +| 属性 | 值 | +|---|---| +| 行高 | 56px（`h-14`） | +| 表头背景 | `bg-neutral-50` | +| 表头文字 | `text-xs font-semibold text-neutral-500 uppercase tracking-wide` | +| 行分割线 | `divide-y divide-neutral-100` | +| 悬停行 | `hover:bg-neutral-50` | +| 选中行高亮 | `bg-primary-50` | +| 圆角容器 | `rounded-lg border border-neutral-200 overflow-hidden` | + +### 1.2 子特性规范 + +| 子特性 | Token / 类名 | 说明 | +|---|---|---| +| 排序箭头（未排序） | `text-neutral-300` chevron-up-down icon | 双向箭头，`w-4 h-4` | +| 排序箭头（升序激活） | `text-primary-600` chevron-up icon | 单向箭头 | +| 排序箭头（降序激活） | `text-primary-600` chevron-down icon | 单向箭头 | +| Checkbox 多选 | `w-4 h-4 rounded accent-primary-600` | Alpine.js 管理 `selected[]` 数组 | +| 状态 Tag（出售） | `bg-primary-50 text-primary-700 text-xs px-2 py-0.5 rounded-full` | | +| 状态 Tag（出租） | `bg-info-50 text-info-600 text-xs px-2 py-0.5 rounded-full` | | +| 状态 Tag（待核验） | `bg-warning-50 text-warning-600 text-xs px-2 py-0.5 rounded-full` | | +| 状态 Tag（已下架） | `bg-neutral-100 text-neutral-500 text-xs px-2 py-0.5 rounded-full` | | +| 价格趋势箭头（上涨） | `text-success-600` arrow-up icon `w-3 h-3` | Alpine.js 条件渲染 | +| 价格趋势箭头（下跌） | `text-danger-600` arrow-down icon `w-3 h-3` | | +| 横向滚动 | `overflow-x-auto` 包裹 `` | 配合列 `min-w-[120px]` | + +### 1.3 HTML 结构 + +```html +
+ + +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + 房源标题 + + + + + 状态 +
+ + + + + + + + + + + + +
+ + +``` + +### 1.4 Alpine.js 数据结构 + +```javascript +function dataTable() { + return { + rows: [], // 由 Django 后端渲染 JSON 或 HTMX 注入 + selected: [], // 选中行 ID 数组 + sortKey: '', + sortDir: 'asc', + + get allSelected() { + return this.rows.length > 0 && this.selected.length === this.rows.length + }, + + toggleAll(checked) { + this.selected = checked ? this.rows.map(r => r.id) : [] + }, + + sort(key) { + if (this.sortKey === key) { + this.sortDir = this.sortDir === 'asc' ? 'desc' : 'asc' + } else { + this.sortKey = key + this.sortDir = 'asc' + } + // 触发 HTMX 请求，携带排序参数 + htmx.trigger('#table-container', 'sort-change', + { key: this.sortKey, dir: this.sortDir }) + } + } +} +``` + +### 1.5 HTMX 排序集成 + +```html + +
+``` + +--- + +## 2. Pagination + +### 2.1 视觉规格 + +| 属性 | 值 | +|---|---| +| 容器布局 | `flex items-center justify-between px-4 py-3 border-t border-neutral-200` | +| 总条数文字 | `text-sm text-neutral-500` | +| 页码按钮尺寸 | `w-8 h-8` `rounded-md` `text-sm` | +| 当前页 | `bg-primary-600 text-white font-medium` | +| 普通页码 | `text-neutral-600 hover:bg-neutral-100` | +| 禁用状态 | `opacity-40 cursor-not-allowed` | +| 省略号 | `text-neutral-400 px-1` | + +### 2.2 HTML 结构 + +```html +
+ + + + 共 {{ paginator.count }} 条 + + + + + + +
+ +
+ +
+ {% for size in [10, 20, 50, 100] %} + + {% endfor %} +
+
+ + +
+ 跳至 + + 页 +
+
+ +
+``` + +### 2.3 Django 后端辅助函数 + +```python +def get_page_range(page_obj, on_each_side=2, on_ends=1): + """生成含省略号的页码列表，供模板渲染""" + paginator = page_obj.paginator + current = page_obj.number + total = paginator.num_pages + result = [] + left = set(range(1, on_ends + 1)) + right = set(range(total - on_ends + 1, total + 1)) + middle = set(range(current - on_each_side, current + on_each_side + 1)) + visible = sorted(left | right | middle) + prev = None + for num in visible: + if 1 <= num <= total: + if prev and num - prev > 1: + result.append('…') + result.append(num) + prev = num + return result +``` + +--- + +## 3. Column Visibility Panel + +### 3.1 视觉规格 + +| 属性 | 值 | +|---|---| +| 触发按钮 | Secondary 按钮，`adjustments-horizontal` 图标 | +| 面板宽度 | `w-64` | +| 面板位置 | 右对齐弹出，`absolute right-0 top-full mt-1` | +| 面板层级 | `z-20` | +| 列项高度 | `h-9` | +| Checkbox 颜色 | `accent-primary-600` | + +### 3.2 HTML 结构 + +```html +
+ + + + + +
+ + +
+ 显示列 + +
+ + +
+ +
+ +
+
+``` + +### 3.3 Alpine.js 数据结构 + +```javascript +function columnVisibility() { + const STORAGE_KEY = 'fonrey:table:property:cols' + + return { + open: false, + columns: [ + { key: 'checkbox', label: '多选', visible: true, locked: true }, + { key: 'code', label: '房源编号', visible: true, locked: true }, + { key: 'title', label: '房源标题', visible: true, locked: false }, + { key: 'status', label: '状态', visible: true, locked: false }, + { key: 'price', label: '价格', visible: true, locked: false }, + { key: 'area', label: '面积', visible: true, locked: false }, + { key: 'district', label: '商圈', visible: false, locked: false }, + { key: 'agent', label: '经纪人', visible: true, locked: false }, + { key: 'created', label: '录入时间', visible: false, locked: false }, + ], + + init() { + const saved = localStorage.getItem(STORAGE_KEY) + if (saved) { + const savedCols = JSON.parse(saved) + this.columns = this.columns.map(col => { + const s = savedCols.find(c => c.key === col.key) + return s ? { ...col, visible: s.visible } : col + }) + } + }, + + savePreferences() { + localStorage.setItem(STORAGE_KEY, + JSON.stringify(this.columns.map(c => ({ key: c.key, visible: c.visible }))) + ) + }, + + resetToDefault() { + localStorage.removeItem(STORAGE_KEY) + this.columns.forEach(col => { if (!col.locked) col.visible = true }) + } + } +} +``` + +--- + +## 4. Toolbar + +### 4.1 视觉规格 + +| 属性 | 值 | +|---|---| +| 容器 | `flex items-center gap-2 py-2` | +| 批量按钮（未选中） | `opacity-50 cursor-not-allowed pointer-events-none` | +| 批量按钮（已选中） | Secondary 按钮正常态 | +| 选中计数 badge | `bg-primary-600 text-white text-xs px-1.5 py-0.5 rounded-full min-w-[20px] text-center` | +| "更多"下拉 | `w-40` Dropdown，`ellipsis-horizontal` 图标 | + +### 4.2 HTML 结构 + +```html +
+ + + + 共 {{ total_count }} 条 + + + + + + + + + + + +
+ +
+ + +
+
+ +
+``` + +--- + +## 5. Export Button + +### 5.1 两种模式 + +| 模式 | 触发条件 | 实现方式 | +|---|---|---| +| 同步导出 | 数据量 ≤5000 条 | Django 视图直接返回 `FileResponse`，浏览器触发下载 | +| 异步导出 | 数据量 >5000 条 | Celery 任务异步生成，完成后推送 Toast 通知（含下载链接） | + +### 5.2 HTML 结构 + +```html + + + + 导出 + + + + +``` + +--- + +## 6. Smart Sort + +### 6.1 视觉规格 + +| 状态 | 样式 | +|---|---| +| 未激活 | `border border-neutral-200 text-neutral-600 bg-white` | +| 激活 | `border border-primary-600 text-primary-600 bg-primary-50` | + +### 6.2 HTML 结构 + +```html +
+ +
+``` + +--- + +## 7. Modal Dialog + +### 7.1 视觉规格 + +| 属性 | 值 | +|---|---| +| 遮罩 | `fixed inset-0 bg-black/50 z-40` | +| 面板宽度 | `w-full max-w-lg`（默认）/ `max-w-2xl`（宽型） | +| 面板圆角 | `rounded-xl` | +| 面板阴影 | `shadow-2xl` | +| Header 高度 | `h-14`，`border-b border-neutral-200` | +| Footer 高度 | `h-16`，`border-t border-neutral-200` | +| 拖拽手柄 | `cursor-grab active:cursor-grabbing text-neutral-300 hover:text-neutral-500` | + +### 7.2 HTML 结构 + +```html +
+ + + + + + + +
+``` + +### 7.3 Alpine.js 数据结构 + +```javascript +function modal() { + return { + isOpen: false, + reason: '', + open() { this.isOpen = true }, + close() { this.isOpen = false; this.reason = '' } + } +} +``` + +--- + +## 8. Tree Select + +### 8.1 视觉规格 + +| 属性 | 值 | +|---|---| +| 触发框 | `h-9 px-3 text-sm border border-neutral-200 rounded-md` | +| 面板宽度 | `w-72` | +| 父节点行高 | `h-9` | +| 子节点行高 | `h-9 pl-8`（左缩进） | +| 展开箭头 | `w-4 h-4 transition-transform`，展开时 `rotate-90` | +| 已选节点 | `bg-primary-50 text-primary-700` | +| 带头像叶节点 | `w-6 h-6 rounded-full bg-primary-100 text-primary-700 text-xs flex items-center justify-center` | +| Badge（关闭状态） | `bg-warning-50 text-warning-600 text-xs px-1.5 py-0.5 rounded-full` | +| 底部操作行 | `sticky bottom-0 border-t border-neutral-100 bg-white px-3 py-2` | + +### 8.2 推荐实现方案 + +**方案一（默认，数据量 ≤200 节点）**：后端一次性返回完整 JSON，Alpine.js 前端递归渲染 + +**方案二（数据量大）**：HTMX 懒加载子节点（点击展开时 `hx-get` 请求子数据） + +### 8.3 HTML 结构（方案一） + +```html +
+ + + + + +
+ + +
+ +
+ + +
+ + + +
+ 暂无匹配结果 +
+
+ + +
+ +
+ +
+
+``` + +### 8.4 Alpine.js 数据结构 + +```javascript +function treeSelect() { + return { + open: false, + query: '', + selected: null, + hideInactive: false, + tree: [], // 从 Django 后端注入：[{ id, label, badge, children: [{id, label, code}] }] + + get filteredTree() { + if (!this.query) return this.tree + const q = this.query.toLowerCase() + return this.tree + .map(group => ({ + ...group, + children: group.children.filter(leaf => + leaf.label.includes(q) || leaf.code?.includes(q) + ) + })) + .filter(group => group.children.length > 0) + }, + + selectLeaf(leaf) { + this.selected = leaf + this.open = false + this.query = '' + } + } +} +``` + +--- + +## 9. Date Range Picker + +### 9.1 技术选型 + +**使用 Flatpickr**（CDN，~16KB，无框架依赖），不手写。 + +```html + + + + +``` + +### 9.2 初始化配置 + +```javascript +flatpickr('#dateRange', { + mode: 'range', + showMonths: 2, + locale: 'zh', + dateFormat: 'Y-m-d', + allowInput: true, + onReady(_sel, _str, fp) { + fp.calendarContainer.classList.add('fonrey-calendar') + } +}) +``` + +### 9.3 样式覆盖（配合主色 Teal） + +```css +/* static/css/flatpickr-overrides.css */ +.flatpickr-day.selected, +.flatpickr-day.startRange, +.flatpickr-day.endRange { + background: #0F766E; + border-color: #0F766E; +} +.flatpickr-day.inRange { + background: #CCFBF1; + border-color: #CCFBF1; + color: #115E59; +} +.flatpickr-day.today { + border-color: #D97706; +} +``` + +### 9.4 HTML 结构 + +```html +
+ +
+ + +
+
+``` + +--- + +## 10. Tab Navigation + +### 10.1 视觉规格 + +| 属性 | 值 | +|---|---| +| Tab 容器 | `border-b border-neutral-200` | +| Tab 按钮（未激活） | `h-10 px-4 text-sm text-neutral-500 hover:text-neutral-700` | +| Tab 按钮（激活） | `h-10 px-4 text-sm text-primary-600 font-medium border-b-2 border-primary-600` | +| 内容区顶部间距 | `mt-4` | + +### 10.2 HTML 结构 + +```html +
+ + +
+ +
+ + +
+ +
+ +
+``` + +### 10.3 Timeline 子组件 + +```html + +
+ +
+ +
+ {% for log in logs %} +
+ +
+ + +
+ {{ log.operator }} + {{ log.action }} + {{ log.created_at }} +
+
{{ log.detail }}
+
+ {% endfor %} +
+ + + {% if has_more %} + + {% endif %} +
+``` + +--- + +## 11. Collapsible Card Grid + +### 11.1 视觉规格 + +| 属性 | 值 | +|---|---| +| 外层卡片 | `bg-white rounded-lg border border-neutral-200` | +| Section Header | `flex items-center justify-between px-4 py-3 border-b border-neutral-100` | +| 网格列数 | `grid grid-cols-3 gap-4` | +| 员工卡片 | `p-3 rounded-lg border border-neutral-100 hover:border-neutral-200` | +| 头像尺寸 | `w-10 h-10 rounded-full` | +| 展开按钮 | `w-full flex items-center justify-center h-9 text-sm text-neutral-500 hover:bg-neutral-50 border-t border-neutral-100` | + +### 11.2 HTML 结构 + +```html +
+ + +
+

相关员工

+ +
+ + +
+
+ + + {% for member in members %} +
+
+ + {{ member.name }} +
+
{{ member.name }}
+
{{ member.store }}
+
{{ member.phone }}
+
+ +
+ +
+ + +
+
+
+ +
{{ member.role }}
+
+ {% endfor %} + + + {% if members|length < 3 %} +
+ 暂未分配 +
+ {% endif %} + +
+
+ + + + +
+``` + +--- + +## 12. Photo Gallery Manager + +### 12.1 组件构成 + +| 子组件 | 实现方式 | +|---|---| +| Scrollable Tab Bar（分类标签） | Tailwind `overflow-x-auto flex` + Alpine.js 激活态 | +| Image Grid with Checkbox | Tailwind `grid grid-cols-6 gap-2` + Alpine.js 多选 | +| Batch Action Toolbar | Alpine.js `:disabled` 状态控制 | +| Drag-and-Drop Upload | **Filepond**（CDN，~50KB） | +| Drag-to-Reorder | **SortableJS**（CDN，~3KB） | + +### 12.2 图片网格 HTML + +```html +
+ + +
+ +
+ + +
+ + + 已选 张 + + +
+ + +
+
+ + +
+ +
+ +
+``` + +### 12.3 Filepond 上传初始化 + +```javascript +// static/js/filepond-init.js +FilePond.registerPlugin(FilePondPluginImagePreview) +FilePond.setOptions({ + server: { + process: '/api/photos/upload/', + headers: { 'X-CSRFToken': getCookie('csrftoken') } + }, + labelIdle: '拖拽图片到此处，或 点击选择', + acceptedFileTypes: ['image/*'], + allowMultiple: true, + maxFiles: 50, +}) +``` + +--- + +## 13. Image Lightbox Viewer + +### 13.1 技术选型 + +**使用 Viewer.js**（CDN，~5KB，无框架依赖）覆盖缩放/旋转/全屏/翻页/缩略图条。 + +```html + + +``` + +### 13.2 初始化 + +```javascript +const gallery = document.getElementById('photo-gallery') +const viewer = new Viewer(gallery, { + toolbar: { + zoomIn: true, zoomOut: true, oneToOne: true, + reset: true, rotateLeft: true, rotateRight: true, download: true, + }, + navbar: true, + title: (image) => `${image.alt} · ${image.naturalWidth} × ${image.naturalHeight}`, + url: 'data-src', // 使用 data-src 存储原图 URL +}) +``` + +### 13.3 触发按钮集成 + +```html + + + + +``` + +--- + +## 14. Accordion Progress Panel + +### 14.1 视觉规格 + +| 属性 | 值 | +|---|---| +| 进度条轨道 | `h-2 bg-neutral-100 rounded-full` | +| 进度条填充（正常） | `bg-warning-600 rounded-full transition-all` | +| 进度条填充（满分） | `bg-success-600` | +| 父行（折叠头） | `flex justify-between items-center h-10 px-4 cursor-pointer hover:bg-neutral-50` | +| 子行 | `flex justify-between items-center h-9 pl-8 pr-4 text-sm` | +| 分数（正常） | `text-sm text-neutral-600 tabular-nums` | +| 分数（0分/未达标） | `text-sm text-danger-600 font-medium tabular-nums` | +| 操作链接 | `text-xs text-primary-600 hover:text-primary-700 ml-2` | + +### 14.2 HTML 结构 + +```html +
+ + +
+
+

信息完整度

+ 69% +
+ +
+
+
+

+ 完善信息可提升房源曝光率。 + 了解更多 +

+
+ + +
+ + {% for group in progress_groups %} + + {% if group.is_collapsible %} + +
+ +
+ {% for item in group.items %} +
+ {{ item.label }} +
+ + {{ item.score }}% / {{ item.max_score }}% + + {% if item.action %} + {{ item.action }} + {% endif %} +
+
+ {% endfor %} +
+
+ + {% else %} + +
+ {{ group.label }} +
+ + {{ group.score }}% / {{ group.max_score }}% + + {% if group.action %} + {{ group.action }} + {% endif %} +
+
+ {% endif %} + + {% endfor %} +
+
+``` + +> **注意**：需引入 Alpine.js 官方 `x-collapse` 插件（1KB）处理高度动画。 + +--- + +## 15. Inline Edit Mode + +### 15.1 视觉规格 + +| 状态 | 区分方式 | +|---|---| +| 只读态 | 纯文本 ``，无边框 | +| 编辑态 | `` / ` + + + +
+ + + +
+ 自动生成员工编号 + + +
+ + + +``` + +### 15.3 Alpine.js 数据结构 + +```javascript +function inlineEdit() { + return { + editing: false, + settings: {}, + _snapshot: null, + + init() { + // 从 Django 注入的 JSON 初始化 + this.settings = JSON.parse(document.getElementById('settings-data').textContent) + }, + + startEdit() { + this._snapshot = JSON.parse(JSON.stringify(this.settings)) + this.editing = true + }, + + cancelEdit() { + this.settings = JSON.parse(JSON.stringify(this._snapshot)) + this.editing = false + }, + + saveEdit() { + this.editing = false + }, + + getFormData() { + return JSON.stringify(this.settings) + } + } +} +``` + +--- + +## 16. Drawer / Slide-over Panel + +### 16.1 视觉规格 + +| 属性 | 值 | +|---|---| +| 遮罩 | `fixed inset-0 bg-black/30 z-40` | +| 面板宽度（默认） | `w-[480px]` | +| 面板宽度（宽型） | `w-[640px]` | +| 面板层级 | `z-50` | +| 入场动画 | `translate-x-full → translate-x-0`，`duration-300 ease-out` | +| Header 高度 | `h-14 border-b border-neutral-200` | +| Footer 高度 | `h-16 border-t border-neutral-200` | +| 内容区 | `flex-1 overflow-y-auto` | + +### 16.2 HTML 结构 + +```html +
+ + + + + +
+``` + +> **注意**：需引入 Alpine.js 官方 `@alpinejs/focus` 插件以支持 `x-trap`（焦点锁定在 Drawer 内）。 + +--- + +## 17. Multi-select Tag Input + +### 17.1 视觉规格 + +| 属性 | 值 | +|---|---| +| 容器（默认） | `flex flex-wrap gap-1 min-h-[36px] px-2 py-1 border border-neutral-200 rounded-md` | +| 容器（激活） | `+ ring-2 ring-primary-600/40 border-primary-400` | +| Tag/Chip | `inline-flex items-center gap-1 bg-primary-50 text-primary-700 text-xs px-2 py-0.5 rounded-full` | +| Tag 删除按钮 | `text-primary-400 hover:text-primary-700` | +| 下拉选项（未选） | `px-3 h-9 text-sm text-neutral-700 hover:bg-neutral-50` | +| 下拉选项（已选） | `+ bg-primary-50 text-primary-700` + `check` 图标 | + +### 17.2 HTML 结构 + +```html +
+ + +
+ + + + + + +
+ + +
+ + + +
+ 暂无匹配选项 +
+
+ +
+``` + +### 17.3 Alpine.js 数据结构 + +```javascript +function multiSelectTag() { + return { + open: false, + query: '', + selected: [], + options: ['出售', '出租', '租售', '他售/不售', '他租/不租', '暂缓'], + + get filteredOptions() { + if (!this.query) return this.options + return this.options.filter(o => o.includes(this.query)) + }, + + toggle(option) { + const i = this.selected.indexOf(option) + i === -1 ? this.selected.push(option) : this.selected.splice(i, 1) + }, + + isSelected(option) { + return this.selected.includes(option) + }, + + remove(option) { + this.selected = this.selected.filter(s => s !== option) + } + } +} +``` + +--- + +## 18. Dynamic Form Table + +### 18.1 视觉规格 + +| 属性 | 值 | +|---|---| +| 表格边框 | `border border-neutral-200 rounded-lg overflow-hidden` | +| 表头 | `bg-neutral-50 text-xs font-semibold text-neutral-500 uppercase` | +| 系统预置行 | 字段名称不可编辑，操作列显示 `-`（`text-neutral-400`） | +| 用户自定义行 | 字段名称可编辑 ``，操作列显示"隐藏不使用" | +| 必填 Badge（必填） | `bg-primary-600 text-white text-xs px-2 py-0.5 rounded-full` | +| 必填 Badge（非必填） | `bg-neutral-200 text-neutral-500 text-xs px-2 py-0.5 rounded-full` | +| Toggle 开关（主色） | `bg-primary-600`（开）/ `bg-neutral-300`（关） | +| 添加行按钮 | `border-t border-dashed border-neutral-200 text-primary-600 hover:bg-primary-50` | + +### 18.2 HTML 结构 + +```html +
+
+ + + + + + + + + + + + + +
字段名称字段类型可选内容是否必填操作
+ + + +
+ + +
+ +
+
+``` + +--- + +## 19. Sortable Table with Drag Handle + +### 19.1 技术选型 + +**SortableJS**（CDN，~3KB），与 Alpine.js 集成，处理拖拽排序。 + +### 19.2 视觉规格 + +| 属性 | 值 | +|---|---| +| 拖拽手柄 | `cursor-grab active:cursor-grabbing text-neutral-300 hover:text-neutral-500` | +| 拖拽中行 | `.sortable-chosen`：`bg-primary-50 shadow-md` | +| 放置占位行 | `.sortable-ghost`：`border-2 border-dashed border-primary-300 bg-transparent opacity-50` | + +### 19.3 HTML 结构 + +```html +
+ + + + + + + + + + + +
字段名称
+
+``` + +### 19.4 Alpine.js + SortableJS 初始化 + +```javascript +function sortableTable() { + return { + rows: [], + + initSort() { + Sortable.create(document.getElementById('sortable-table'), { + handle: '.drag-handle', + animation: 150, + chosenClass: 'bg-primary-50 shadow-md', + ghostClass: 'sortable-ghost', + + onEnd: (evt) => { + const moved = this.rows.splice(evt.oldIndex, 1)[0] + this.rows.splice(evt.newIndex, 0, moved) + this.saveOrder() + } + }) + }, + + saveOrder() { + fetch('/api/field-options/reorder/', { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'X-CSRFToken': getCookie('csrftoken') + }, + body: JSON.stringify({ ids: this.rows.map(r => r.id) }) + }) + } + } +} +``` + +```css +/* Drop 占位行样式（在 static/css/app.css 中定义，不写 inline） */ +.sortable-ghost { + border: 2px dashed #5EEAD4; /* primary-300 */ + background: transparent !important; + opacity: 0.5; +} +``` + +--- + +## 20. Multi-Table Independent Pagination + +### 20.1 核心设计原则 + +每个表格区块拥有**独立的三要素**，通过 HTMX `hx-target` 精准隔离： + +``` +表格区块 N + ├─ id="table-{module}" ← 唯一 DOM 目标 + ├─ hx-target="#table-{module}" ← 分页只刷新自身 + └─ /api/{module}/?page=N ← 独立后端分页接口 +``` + +翻某个表格的页，其他表格 **DOM 完全不变**。 + +### 20.2 HTML 结构 + +```html + +
+ + + +
+ + +
+ + +
+
+

业客信息

+

买卖双方及关联人员信息字段

+
+ + +
+ {% include "partials/table_customer.html" %} +
+ + +
+ {% include "partials/pagination.html" with target="#table-customer" url_base="/params/customer/" page_obj=customer_page %} +
+
+ + +
+
+

合同-应收费用

+
+ +
+ {% include "partials/table_fee.html" %} +
+ +
+ {% include "partials/pagination.html" with target="#table-fee" url_base="/params/fee/" page_obj=fee_page %} +
+
+ +
+``` + +### 20.3 分页器 Partial 模板（可复用） + +```html +{# templates/partials/pagination.html #} +{# 参数：target（HTMX 目标）、url_base（接口基础 URL）、page_obj #} + +``` + +--- + +## 附录 A：第三方库清单 + +| 库 | 版本 | 用途 | 引入方式 | 使用组件 | +|---|---|---|---|---| +| Flatpickr | latest | 日期范围选择 | CDN | Date Range Picker | +| SortableJS | latest | 拖拽排序 | CDN | Sortable Table、Photo Gallery | +| Filepond + ImagePreview 插件 | latest | 图片上传 + 预览 | CDN | Photo Gallery Manager | +| Viewer.js | latest | 图片灯箱预览 | CDN | Image Lightbox | +| @alpinejs/collapse | latest | 折叠高度动画 | CDN | Accordion、Collapsible Card | +| @alpinejs/focus | latest | 焦点锁定 | CDN | Modal、Drawer | + +> 以上库均为**无框架依赖**纯 JS 工具库，与 HTMX + Alpine.js + Tailwind 技术栈完全兼容。 + +--- + +## 附录 B：组件难度分级 + +| 难度 | 组件 | +|---|---| +| ⭐ 简单（<30 行 JS） | Toggle Switch、Tab Navigation、Collapsible Card、Accordion Progress Panel、Toolbar | +| ⭐⭐ 中等（30~80 行 JS） | Data Table、Pagination、Column Visibility Panel、Inline Edit Mode、Drawer、Multi-select Tag Input、Dynamic Form Table | +| ⭐⭐⭐ 较难（需外部库或复杂数据结构） | Tree Select、Sortable Table、Photo Gallery Manager、Image Lightbox、Date Range Picker、Multi-Table Pagination | + +--- + +## 附录 C：关联文档 + +- `UI_SYSTEM/UI_SYSTEM.md` — 设计 Token、颜色系统、基础组件规范（权威基准） +- `UI_SYSTEM/组件清单.md` — 组件可行性分析与实现建议（本文源材料） +- `TECH_STACK/TECH_STACK.md` — 技术选型总纲 +- `PRD/*` — 各业务模块产品需求 + +--- + +*文档版本 v1.0 · 2026-04-25 · 基于 UI_SYSTEM.md v1.1 生成* diff --git a/wiki/index.md b/wiki/index.md index 6e2ca49d..dfbeb6d0 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -4,6 +4,9 @@ - [Overview](overview.md) — living synthesis ## Sources +- [2026-04-25] [MCP Builder Agent](sources/specialized-mcp-builder.md) +- [2026-04-25] [Compliance Auditor Agent](sources/compliance-auditor.md) +- [2026-04-25] [Specialized Salesforce Architect](sources/specialized-salesforce-architect.md) - [2026-04-25] [LSP/Index Engineer Agent Personality](sources/lsp-index-engineer.md) - [2026-04-25] [Model QA Specialist](sources/specialized-model-qa.md) - [2026-04-25] [Corporate Training Designer](sources/corporate-training-designer.md) @@ -408,9 +411,6 @@ - [2026-04-20] [sales-data-extraction-agent](sources/sales-data-extraction-agent.md) — (expected: wiki/sources/sales-data-extraction-agent.md — source missing) - [2026-04-20] [agents-orchestrator](sources/agents-orchestrator.md) — (expected: wiki/sources/agents-orchestrator.md — source missing) - [2026-04-20] [study-abroad-advisor](sources/study-abroad-advisor.md) — (expected: wiki/sources/study-abroad-advisor.md — source missing) -- [2026-04-20] [specialized-mcp-builder](sources/specialized-mcp-builder.md) — (expected: wiki/sources/specialized-mcp-builder.md — source missing) -- [2026-04-20] [compliance-auditor](sources/compliance-auditor.md) — (expected: wiki/sources/compliance-auditor.md — source missing) -- [2026-04-20] [specialized-salesforce-architect](sources/specialized-salesforce-architect.md) — (expected: wiki/sources/specialized-salesforce-architect.md — source missing) - [2026-04-20] [automation-governance-architect](sources/automation-governance-architect.md) — (expected: wiki/sources/automation-governance-architect.md — source missing) - [2026-04-20] [llm-wiki](sources/llm-wiki.md) — (expected: wiki/sources/llm-wiki.md — source missing) - [2026-04-20] [baoyu-skills](sources/baoyu-skills.md) — (expected: wiki/sources/baoyu-skills.md — source missing) diff --git a/wiki/log.md b/wiki/log.md index 5818159a..cd18544e 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -1,3 +1,29 @@ +## [2026-04-25] ingest | MCP Builder Agent +- Source file: Agent/agency-agents/specialized/specialized-mcp-builder.md +- Status: ✅ 成功摄入 +- Summary: MCP Builder Agent——AI Agent 的 MCP（Model Context Protocol）服务器开发专家，设计、构建、测试和部署 MCP 服务器，为 AI Agent 提供自定义工具（Tools）、资源（Resources）和提示词模板（Prompts）能力。核心理念：工具命名即 UX，正确选用率目标 >90%；技术栈 TypeScript+Zod 或 Python+Pydantic；核心原则：无状态设计、结构化错误返回、环境变量密钥、边界验证、真实 Agent 测试。 +- Concepts created: 无（Key Concepts 中 10 个术语均为 Source Page 内可解释的协议/框架级概念，通过 wikilinks 形式表达，不具备跨页面复用价值，未单独建 Concept 页面） +- Entities created: 无（MCP SDK/FastMCP/Zod/Pydantic 仅出现 1 次，不满足 ≥2 次条件，通过 Key Entities 链接保留在 Source Page） +- Source page: wiki/sources/specialized-mcp-builder.md +- Notes: index.md 中原有 "source missing" 占位条目（2026-04-20）已替换为完整条目；overview.md Specialized 部门新增 MCP Builder Agent 条目置于 visionos-spatial-engineer 之后；无冲突内容检测。 + +## [2026-04-25] ingest | Compliance Auditor Agent +- Source file: Agent/agency-agents/specialized/compliance-auditor.md +- Status: ✅ 成功摄入 +- Summary: Compliance Auditor Agent——The Agency Specialized 部门的技术合规审计专家，专注 SOC 2、ISO 27001、HIPAA、PCI-DSS 认证审计全流程。五步工作流：Scoping → Gap Assessment → Remediation Support → Audit Support → Continuous Compliance。核心原则：不跟随的政策比没政策更危险、证据必须证明整个审计周期持续有效、技术控制优于管理控制、自动化证据收集从第一天建立。 +- Concepts created: 无（Key Concepts 中 6 个术语均为 Source Page 内可解释的术语，不具备跨页面复用价值，未单独建 Concept 页面） +- Entities created: 无（SOC-2/ISO-27001/HIPAA/PCI-DSS 均为框架级标准，在多个来源中出现但以 wikilinks 形式表达，未单独建 Entity 页面） +- Source page: wiki/sources/compliance-auditor.md +- Notes: index.md 中原有 "source missing" 占位条目（2026-04-20）已移除并替换为完整条目；overview.md Specialized 部门新增 Compliance Auditor 条目置于 healthcare-marketing-compliance 之后；与 [[specialized-model-qa]] 在证据定义上的差异已记录于 Contradictions 部分。 + +## [2026-04-25] ingest | Specialized Salesforce Architect +- Source file: Agent/agency-agents/specialized/specialized-salesforce-architect.md +- Status: ✅ 成功摄入 +- Summary: Salesforce 企业级解决方案架构师 Agent — 多云架构设计（Sales/Service/Marketing/Commerce/Data Cloud/Agentforce）、企业集成模式（REST/Platform Events/CDC/MuleSoft）、数据模型设计与治理、Governor Limit 预算规划、CI/CD 部署策略（Salesforce DX/DevOps Center）。核心原则：Governor limits 不可协商、Bulkification 强制要求、Declarative-first、Trigger 只委托不分发、集成模式必须处理失败场景。 +- Concepts created: 无（技术术语通过 Source Page Key Concepts + wikilinks 表达，未单独建页面） +- Source page: wiki/sources/specialized-salesforce-architect.md +- Notes: 无冲突内容检测；MuleSoft、Shield Platform Encryption、DevOps Center 作为 Key Entities 链接保留在 Source Page；Platform Events vs CDC 对比表已提取为 Key Claims + ## [2026-04-25] ingest | Model QA Specialist - Source file: Agent/agency-agents/specialized/specialized-model-qa.md - Status: ✅ 成功摄入 diff --git a/wiki/overview.md b/wiki/overview.md index 46dee6b8..586c1f11 100644 --- a/wiki/overview.md +++ b/wiki/overview.md @@ -63,6 +63,8 @@ The wiki covers two major multi-agent frameworks: **The Agency** (agency-agents) **[[visionos-spatial-engineer]]**（visionOS Spatial Engineer）：Apple visionOS 原生空间计算 Agent——专注于 visionOS 26 平台的 SwiftUI volumetric interfaces 和 Liquid Glass Design System 实现。核心能力：Liquid Glass 透明材质设计（自适应 light/dark 环境）、Spatial Widgets（吸附墙面/桌面、持久化放置）、SwiftUI Volumetric APIs（3D 内容集成、volume transient content、breakthrough UI）、RealityKit-SwiftUI 集成（Observable entities、直接手势处理、ViewAttachmentComponent）、Multi-Window Architecture（WindowGroup 管理、玻璃背景效果）、GPU 高效渲染。技术栈：SwiftUI / RealityKit / ARKit / Metal。典型交付物：visionOS 原生空间应用、volumetric 界面、Liquid Glass 体验。与 [[macos-spatial-metal-engineer]] 协同——前者专注 UI/UX 层应用开发，后者专注 GPU 密集型数据渲染，共同构成完整的 Apple 空间计算平台能力。属 [[Spatial-Computing]] 概念在 Apple 原生平台场景的具体实现。 +**[[specialized-mcp-builder]]**（MCP Builder Agent）：AI Agent 的 MCP（Model Context Protocol）服务器开发专家——设计、构建、测试和部署 MCP 服务器，为 AI Agent 提供自定义工具（Tools）、资源（Resources）和提示词模板（Prompts）能力。核心理念：**工具命名即 UX**——`search_tickets` 优于 `query1`，Agent 必须能从名称推断用途，正确选用率目标 >90%。技术栈：TypeScript + Zod（官方 MCP SDK）或 Python + Pydantic（FastMCP）。核心原则：无状态设计（每次调用独立）、结构化错误返回（`isError: true` 而非堆栈跟踪）、环境变量密钥管理、边界层参数验证、真实 Agent 完整链路测试。高级能力：多传输层支持（Stdio/SSE/Streamable HTTP）、OAuth 2.0 认证、动态工具注册（OpenAPI→MCP 自动生成）、组合式服务器架构。与 [[agentic-identity-trust]] 协同——后者提供身份与信任基础，前者提供工具能力扩展，共同构成完整 Agent 基础设施。与 [[llm-wiki]] 在知识系统层面关联——MCP 服务器可为 Wiki Agent 提供外部知识检索能力。 + ### The Agency — Project Management 部门 |The Agency 的 Project Management 部门涵盖多个垂直领域的专业项目管理 Agent，从战略组合管理到实验跟踪，覆盖项目全生命周期。| @@ -689,6 +691,8 @@ Key concepts: [[Django ORM]], [[Django REST Framework]], [[Django Admin 定制]] **[[healthcare-marketing-compliance]]**（Healthcare Marketing Compliance Specialist）：The Agency Specialized 部门的医疗营销合规专家——覆盖中国医疗健康全品类（药品/医疗器械/医美/保健食品/互联网医疗）营销合规，深度熟悉《广告法》《医疗广告管理办法》《互联网广告管理办法》等核心法规体系。核心能力：医疗广告审查（《医疗广告审查证明》申请与合规）、处方药/OTC药广告分规管理、医疗器械三类分级合规（I类备案/II类注册/III类严格审批）、医美"容貌焦虑"红线防控、保健品"蓝帽子"标识管理、互联网诊疗合规（初诊必须线下面诊）、患者隐私 PIPL 合规（敏感个人信息须单独授权）、学术推广合规（医疗代表备案、会议赞助标准、医师讲课费规范）。关键原则：**合规不是"堵营销"，而是"保护品牌"**——一次违规处罚的代价远高于合规投入；**"事前审查"优于"事后补救"**——所有对外发布的医疗营销内容必须经过合规团队审核。成功指标：年度零监管处罚、平台违规 < 3次/年、100% 内容发布前合规审查覆盖率。属 The Agency Specialized 部门的合规垂直方向，与 [[government-digital-presales-consultant]]（政府合规）和 [[legal-compliance-checker]]（通用法律合规）共同构成完整的合规能力体系。 +**[[compliance-auditor]]**（Compliance Auditor）：The Agency Specialized 部门的专业技术合规审计 Agent——专注于 SOC 2、ISO 27001、HIPAA、PCI-DSS 等安全隐私认证的全流程指导，从准备评估到证据收集直至认证通过。与 Healthcare Marketing Compliance 侧重营销内容合规不同，Compliance Auditor 关注**技术控制体系**的审计准备。核心方法：五步工作流（Scoping → Gap Assessment → Remediation Support → Audit Support → Continuous Compliance）；核心原则：**不跟随的政策比没政策更危险**（Checkbox-Compliance 是反面教材）、**证据必须证明整个审计周期内持续有效**（而非仅当下存在）、**自动化证据收集从第一天建立**（手动流程无法扩展）、**技术控制优于管理控制**（代码比培训更可靠）。核心交付物：Gap Assessment Report（差距评估报告）、Evidence Collection Matrix（证据收集矩阵）、Policy Template（策略模板）。成功指标：零不合格发现（zero adverse findings）、审计周期缩短 30%、年度合规状态持续可查。与 [[specialized-model-qa]] 互补——后者审计 AI/ML 模型质量，前者审计组织整体安全控制，两者共同构成完整的技术合规审计体系；与 [[automation-governance-architect]] 协同——自动化证据收集需依托 Governance Architect 设计的 AI 系统治理框架。 + |**[[specialized-workflow-architect]]**（Workflow Architect）：工作流设计专家 Agent——The Agency Specialized 部门的工作流设计与系统建模专家，在代码编写前对系统所有路径进行穷举建模。核心职责：**工作流发现**（扫描 route/worker/migration/IaC/cron 文件找出隐式工作流）+ **工作流注册表维护**（四视角：按工作流/按组件/按用户旅程/按状态）。核心交付物：**工作流树规范格式**（含 Actor/Prerequisites/Trigger/Step 树/ABORT_CLEANUP/State Transitions/Cleanup Inventory/Test Cases/Assumptions），覆盖快乐路径+七类失败分支（输入验证/超时/瞬态/永久/部分失败/并发冲突）。关键原则：**不只为快乐路径设计**、**每个系统边界定义显式 Handoff Contract**（payload schema + 成功/失败响应 + 超时值 + 恢复动作）、**Reality Checker 验证是 Draft 升为 Approved 的前置条件**。Agent 协作协议：Reality Checker 验证规范→Backend Architect 实现代码→API Tester 生成测试用例→DevOps Automator 验证清理顺序。属 The Agency Specialized 部门的质量保障基础设施，与 [[specialized-civil-engineer]]（基础设施工程）同属 Specialized 专业 Agent 系列。 **[[corporate-training-designer]]**（Corporate Training Designer）：The Agency Specialized 部门的企业培训体系架构师与课程开发专家——专注企业级培训需求分析、ADDIE/SAM 教学设计模型、混合学习项目、内训师培养（TTT）、领导力发展（HIPO）及 Kirkpatrick 四级培训效果评估。核心价值观：**优秀培训的衡量标准不是"教了什么"，而是"学员回去做了什么"**。关键方法：ADDIE 模型（分析→设计→开发→实施→评估）、Bloom 认知六层次、Kirkpatrick 四级评估（反应→学习→行为→业务结果）、Kolb 体验式学习圈、OMO 混合学习（线上"认知"→线下"实践"→社群"持续"）。与 [[specialized-workflow-architect]]（工作流设计）和 [[cultural-intelligence-strategist]]（跨文化产品设计）形成系统性设计能力互补——分别应用于组织学习、软件工程和文化包容三大领域，共同构成 [[The Agency]] 的系统性设计矩阵。 diff --git a/wiki/sources/compliance-auditor.md b/wiki/sources/compliance-auditor.md new file mode 100644 index 00000000..6cab9e02 --- /dev/null +++ b/wiki/sources/compliance-auditor.md @@ -0,0 +1,60 @@ +--- +title: "Compliance Auditor Agent" +type: source +tags: [] +date: 2026-04-25 +--- + +## Source File +- [[Agent/agency-agents/specialized/compliance-auditor.md]] + +## Summary（用中文描述） +- 核心主题：专业 AI Agent，专注于 SOC 2、ISO 27001、HIPAA、PCI-DSS 等安全隐私认证审计的全流程指导——从准备评估到证据收集直至认证通过。 +- 问题域：组织如何系统性地通过合规认证，避免"打勾式合规"（checkbox compliance），确保控制措施真正落地而非仅存在于文档中。 +- 方法/机制：五步工作流（Scoping → Gap Assessment → Remediation Support → Audit Support → Continuous Compliance）；强调自动化证据收集、右置控制项设计、以审计员视角反向思考。 +- 结论/价值：合规项目应与公司规模和实际风险匹配；技术控制优于管理控制；证据必须证明控制在整个审计周期内持续有效，而非仅存在于当下。 + +## Key Claims（用中文描述） +- 不被遵守的政策比没有政策更危险——它制造虚假信心，增加审计风险。 +- 自动化证据收集从第一天就应建立——手动流程无法扩展。 +- 使用通用控制框架（common control framework）可一个控制集满足多个认证标准。 +- 技术控制优于管理控制——代码比培训更可靠。 +- 审计边界（scope）必须清晰定义，明确包含和排除的范围。 +- 例外情况（exceptions）需要完整文档：谁批准、为什么、有何时效、有何补偿控制。 + +## Key Quotes +> "A policy nobody follows is worse than no policy — it creates false confidence and audit risk." +> — 核心原则：不follow的政策比没政策更危险 + +> "Evidence must prove the control operated effectively over the audit period, not just that it exists today." +> — 证据的核心要求：证明整个审计周期内持续有效 + +> "Think like the auditor: what would you test? what evidence would you request?" +> — 审计员心态：反向思考，模拟审计师会问什么 + +## Key Concepts +- [[Checkbox-Compliance]]：仅在文档层面满足合规要求，控制实际未落地或未被测试——文档中的反面案例。 +- [[Continuous-Compliance]]：持续合规——在两次年度审计之间建立自动化证据收集管道和季度控制测试机制，而非年度突击准备。 +- [[Common-Control-Framework]]：通用控制框架——设计一组控制项同时满足多个认证标准（如 SOC 2 + ISO 27001），避免重复工作。 +- [[Technical-Controls-Vs-Administrative-Controls]]：技术控制（如 IAM 策略、代码审计）优于管理控制（如培训、签到表），因为代码比人的行为更可靠。 +- [[Compensating-Control]]：补偿控制——当某项控制无法直接满足时，用于降低风险的替代措施；需完整记录批准人、原因和有效期。 +- [[Evidence-Collection-Matrix]]：证据收集矩阵——以控制目标（而非内部团队结构）组织证据的结构化文档，列出控制ID、证据类型、来源、收集方式和频率。 + +## Key Entities +- [[SOC-2]]：安全、可用性、处理完整性、机密性、隐私五大信任服务标准（Trust Service Criteria），最常见的云服务安全认证。 +- [[ISO-27001]]：国际信息安全管理标准，提供系统化的风险管理方法。 +- [[HIPAA]]：美国医疗信息隐私法规，涵盖 PHI（受保护健康信息）的保护要求。 +- [[PCI-DSS]]：支付卡行业数据安全标准，适用于处理信用卡信息的组织。 + +## Connections +- [[specialized-model-qa]] ← extends ← [[compliance-auditor]]：Model QA 关注 ML 模型质量，Compliance Auditor 关注整体安全控制——两者在模型部署合规证据收集上存在交叉。 +- [[automation-governance-architect]] ← depends_on ← [[compliance-auditor]]：合规审计所需的自动化证据收集需依托 Governance Architect 设计的 AI 系统治理框架。 +- [[CTP-Topic-52-3-Lines-of-Defence]] ← extends ← [[compliance-auditor]]：三道防线模型（业务管理 / 风险职能 / 内部审计）与合规审计的职责划分高度对应。 +- [[DevSecOps]] ← extends ← [[compliance-auditor]]：DevSecOps 将安全控制集成到 CI/CD 流水线中，是合规 Auditor 推荐的技术控制实现方式。 + +## Contradictions +- 与 [[specialized-model-qa]] 的侧重点差异： + - 冲突点：Compliance Auditor 关注组织级控制（access control, incident response），Model QA 关注模型本身的质量与统计特性，两者对"证据"的定义不同。 + - 当前观点：合规证据以控制操作日志、策略文档、访问审查记录为主。 + - 对方观点：模型证据以 PSI、校准曲线、SHAP 值等统计指标为主。 + - 协调建议：两者可互补——Compliance Auditor 负责整体安全框架，Model QA 负责嵌入其中的 AI/ML 模型专项审计。 diff --git a/wiki/sources/specialized-mcp-builder.md b/wiki/sources/specialized-mcp-builder.md new file mode 100644 index 00000000..070f1c04 --- /dev/null +++ b/wiki/sources/specialized-mcp-builder.md @@ -0,0 +1,55 @@ +--- +title: "MCP Builder Agent" +type: source +tags: ["agent-personality", "mcp", "tool-design", "ai-integration"] +date: 2026-04-20 +--- + +## Source File +- [[Agent/agency-agents/specialized/specialized-mcp-builder.md]] + +## Summary（用中文描述） +- 核心主题：AI Agent 的 MCP（Model Context Protocol）服务器开发专家——设计、构建、测试和部署 MCP 服务器，为 AI Agent 提供自定义工具、资源和提示词能力 +- 问题域：如何让 AI Agent 能够可靠地调用外部工具和 API，同时保持开发者体验（Developer Experience） +- 方法/机制：遵循 MCP SDK 规范（TypeScript/Zod、Python/Pydantic），设计 Agent 友好的工具接口，提供 Resources（资源）、Tools（工具）、Prompts（提示词模板）三种扩展方式，通过真实 Agent 测试验证可用性 +- 结论/价值：工具命名和描述是 Agent 能否正确选用的关键；每个工具调用必须独立无状态；错误必须返回结构化消息而非堆栈跟踪 + +## Key Claims（用中文描述） +- **描述性工具命名** → Agent 能从名称推断用途，正确选用率 >90% +- **类型化参数验证（Zod/Pydantic）** → 边界层拦截非法输入，防止外部 API 污染 +- **结构化错误返回（isError: true）** → Agent 知道何时重试或请求用户，而非虚构响应 +- **无状态工具设计** → 每次调用独立，不依赖调用顺序，确保分布式环境稳定 +- **真实 Agent 测试循环** → 通过完整调用链路验证，而非仅靠单元测试 +- **环境变量密钥管理** → API Key 和 Token 从环境变量读取，绝不硬编码 + +## Key Quotes +> "If an agent can't figure out how to use your tool from the name and description alone, it's not ready to ship." — MCP Builder 核心理念 +> "A tool that passes unit tests but confuses the agent is broken." — 测试理念，强调必须验证 Agent 的完整调用路径 +> "We return `isError: true` here so the agent knows to retry or ask the user, instead of hallucinating a response." — 错误处理设计哲学 + +## Key Concepts +- [[Model Context Protocol (MCP)]]：Anthropic 提出的 AI Agent 与外部工具/数据源交互的标准化协议 +- [[MCP Server]]：基于 MCP 协议的服务端实现，暴露 Tools/Resources/Prompts 给 Agent +- [[Tool Interface Design]]：为 Agent 设计友好工具接口的实践，关注命名、描述、参数类型和返回结构 +- [[Zod Validation]]：TypeScript 端的参数模式定义和验证库，用于 MCP TypeScript 服务器 +- [[Pydantic Validation]]：Python 端的参数模式定义和验证库，用于 MCP Python (FastMCP) 服务器 +- [[Stdio Transport]]：MCP 标准传输方式，适用于本地 CLI 集成和桌面 Agent +- [[SSE Transport]]：Server-Sent Events 传输方式，适用于基于 Web 的 Agent 接口和远程访问 +- [[Streamable HTTP]]：可扩展云部署的 HTTP 流式传输，支持无状态请求处理 +- [[Stateless Tool Design]]：无状态工具设计原则，确保每次调用独立、幂等、可分布式运行 +- [[Structured Error Response]]：返回 `isError: true` 结构化错误消息，而非堆栈跟踪 + +## Key Entities +- [[@modelcontextprotocol/sdk]]：Anthropic 官方 MCP TypeScript SDK，提供 McpServer、StdioServerTransport 等核心类 +- [[FastMCP]]：Python MCP 服务器框架，基于 Pydantic 的类型验证 +- [[Zod]]：TypeScript schema 声明和验证库，MCP TypeScript SDK 内置支持 +- [[Pydantic]]：Python 数据验证库，FastMCP 的核心依赖 + +## Connections +- [[MCP Builder Agent]] ← implements ← [[Model Context Protocol (MCP)]] +- [[MCP Builder Agent]] ← uses ← [[@modelcontextprotocol/sdk]] +- [[MCP Builder Agent]] ← uses ← [[FastMCP]] +- [[LSP/Index Engineer Agent Personality]] ← shares_tool_design_philosophy_with ← [[MCP Builder Agent]] + +## Contradictions +- 暂无发现与其他 Wiki 页面的冲突 diff --git a/wiki/sources/specialized-salesforce-architect.md b/wiki/sources/specialized-salesforce-architect.md new file mode 100644 index 00000000..0a84b180 --- /dev/null +++ b/wiki/sources/specialized-salesforce-architect.md @@ -0,0 +1,56 @@ +--- +title: "Specialized Salesforce Architect" +type: source +tags: [] +date: 2026-04-20 +--- + +## Source File +- [[Agent/agency-agents/specialized/specialized-salesforce-architect.md]] + +## Summary（用中文描述） +- 核心主题：Salesforce 平台企业级解决方案架构师 Agent — 多云架构设计、企业集成模式、技术治理 +- 问题域：Salesforce 组织从试点到企业规模扩展过程中的架构设计、技术债务规避、governor limits 规划 +- 方法/机制：ADR（架构决策记录）、Governor Limit Budget 追踪、Integration Pattern Template、数据模型审查清单 +- 结论/价值：提供从发现评估 → 架构设计 → 实施指导 → 审查治理的完整工作流，强调 declarative-first 原则和 bulkification 强制性要求 + +## Key Claims（用中文描述） +- Governor limits 是不可协商的铁律，每项设计必须提前计入 SOQL(100)、DML(150)、CPU(同步10s/异步60s)、堆(同步6MB/异步12MB) 等限制 +- 业务逻辑必须放在 Handler 类中，Trigger 只负责委托分发，且每个对象只允许一个 Trigger +- Bulkification 是强制要求 — 若代码在 200 条记录下失败，则该代码就是错误的 +- Declarative first，代码第二：优先使用 Flows、公式字段和验证规则，只在 declarative 方案变得不可维护时才考虑 Apex +- 集成模式必须处理失败场景：每次外部调用都需要重试逻辑、断路器和死信队列 +- 数据模型是基础：在生产上线后再改数据模型，成本是设计阶段的 10 倍 +- PII 数据必须加密存储，使用 Shield Platform Encryption 或自定义加密方案 + +## Key Quotes +> "Governor limits are non-negotiable. Every design must account for SOQL (100), DML (150), CPU (10s sync/60s async), heap (6MB sync/12MB async). No exceptions, no 'we'll optimize later.'" — 核心设计原则 +> "If the code would fail on 200 records, it's wrong." — Bulkification 强制性标准 +> "Data model is the foundation. Changing the data model after go-live is 10x more expensive." — 数据模型优先级 +> "Be direct about technical debt. If someone built a trigger that should be a flow, say so." — 沟通风格示例 + +## Key Concepts +- [[GovernorLimits]]：Salesforce 平台执行上下文的硬性资源限制，包括 SOQL 查询数(100)、DML 语句数(150)、CPU 时间(同步10s)、堆大小(同步6MB)等 +- [[Bulkification]]：批量处理模式 — 要求所有触发器和 Apex 代码必须能在单次交易中处理多条记录（通常按 200 条/批次测试） +- [[PlatformEvents]]：Salesforce 平台事件 — 用于跨系统集成的异步事件驱动机制，支持 72 小时重放窗口和高容量标准（10万/天） +- [[ChangeDataCapture]]（CDC）：变更数据捕获 — 自动追踪 sObject 字段级变更，适合 Salesforce 原生事件同步场景 +- [[ADR]]（Architecture Decision Record）：架构决策记录 — 文档化记录重要技术决策的上下文、备选方案、后果和复审日期 +- [[SalesforceDX]]：Salesforce 开发者体验框架 — 基于 Scratch Org 的源代码驱动部署方式，与 DevOps Center 并行 +- [[Agentforce]]：Salesforce AI Agent 框架 — Agent 在 Salesforce governor limits 内运行，需设计在 CPU/SOQL 预算内完成的动作，使用 Einstein Trust Layer 进行 PII 脱敏 + +## Key Entities +- [[MuleSoft]]：Salesforce 收购的企业级集成中间件，用于跨系统集成模式中的中间转换层（DataWeave 转换、3x 指数退避重试、死信队列） +- [[ShieldPlatformEncryption]]：Salesforce 原生 PII 加密方案，与自定义加密并列作为敏感数据保护选项 +- [[DevOpsCenter]]：Salesforce 原生 CI/CD 平台，与 Salesforce DX 并行的另一种部署方式 + +## Connections +- [[SalesforceDX]] ← supports ← [[ADR]] +- [[PlatformEvents]] ← extends ← [[ChangeDataCapture]] +- [[Bulkification]] ← enforces ← [[GovernorLimits]] +- [[Agentforce]] ← bounded_by ← [[GovernorLimits]] + +## Contradictions +- 与 [[DevOpsCenter]] 关系： + - 冲突点：Salesforce DX 与 DevOps Center 是两种并行的部署策略，文档将两者并列但未明确优先选用哪个 + - 当前观点：Salesforce DX 基于 Scratch Org 源码驱动是现代标准实践 + - 对方观点：DevOps Center 作为 Salesforce 原生工具对非技术用户更友好