01 / Introduction
系统定位与设计宗座
工程级组件资产手册定位
随着 Acme.IBP 后台页面的大规模扩张及 AI 编码的常态化，界面视觉与组件策略的碎片化问题日益严峻。本设计系统的核心宗旨是对存量与增量页面实施工程化的“资产治理”，将散落在仓库各个角落的组件进行全量百科化登记。
技术约束声明：本系统完全基于既有技术底座（.NET 8、Razor 模板、jQuery 3.5.1、Bootstrap 4.5、SmartAdmin 及 ag-Grid）开发。严禁为开发业务页面引入任何第三方 SPA 框架（如 React/Vue/Angular）或其组件库（如 Ant Design/ElementUI），严禁脱离现有系统视觉风格另起炉灶。我们通过提取全局 CSS 变量与沉淀标准组件契约，在既有底座上低成本实现 Ant Design 等成熟设计系统的卓越工程规范度。
02 / Asset Map
Acme 组件资产总表地图
本表为 Acme.IBP 后台与移动端真实存在的全部工程组件资产总表。后续开发人员与 AI 编写页面时，必须先在此地图检索标准资产，禁止重复造轮子：
| 组件名 | 组件类型 | 源码与样式路径 | 标准入口 | 适用场景与业务含义 | 所属页 | PC 推荐 | 移动端 | 替代/禁止方案 |
|---|---|---|---|---|---|---|---|---|
| acmeAgGrid | 数据网格 (PC) | acme.AgGrid.js- |
acmeAgGrid.init(opts) |
PC 大宗数据列表展示、多维度检索、服务端分页 | Tables | ✔ 强制 | - | 禁止使用原生 <table> 或手写 jQuery 拼接 |
| AcmeGridOperations | 操作条 (PC) | acme.gridOperations.jsdata-operations.css |
AcmeGridOperations.init(opts) |
数据网格右侧刷新、批量导入、导出、批量物理删除 | Tables | ✔ 推荐 | - | 禁止在左侧业务操作区内零散排布导入导出按钮 |
| dataOperationsContainer | 操作容器 (PC) | - (DOM 挂载点)data-operations.css |
id="dataOperationsContainer" |
操作条按钮的 DOM 容器占位，固定位于右侧 | Tables | ✔ 强制 | - | 必须放在 .operetion-section 右侧 |
| DataBinder | 数据绑定 (PC) | acme.controlBind.js- |
DataBinder.bind(opts) |
下拉 (Select/Select2)、单选多选从 API 自动填充数据 | Forms | ✔ 强制 | - | 绝对禁止手写 AJAX 循环拼接 `<option>` 追加 |
| selUser | 人员选择器 (PC) | selUser.cshtmlselUser.css |
Html.RenderPartial |
多选/单选用户、所属部门、关联标签的高级弹窗选择器 | Forms | ✔ 强制 | - | 禁止业务开发自己手写人员选择弹窗 |
| userTree | 人员选择树 (PC) | userTree.cshtml- |
Html.RenderPartial |
左树右表极简单选人员，jsTree 驱动 | Forms | ✔ 推荐 | - | 不适用于多选、标签过滤及多维度人员检索 |
| selSysDic | 字典选择器 (PC) | selSysDic.cshtml- |
Html.RenderPartial |
系统字典 (SysDict)、枚举 (Enum)、基础数据级联绑定 | Forms | ✔ 强制 | - | 禁止在业务中硬编码系统配置字段 |
| selResource | 资源选择器 (PC) | selResource.cshtml- |
Html.RenderPartial |
运维服务器资源、物理设备多选/单选穿透框 | Modals | ✔ 推荐 | - | 禁止手动编写针对 toolResource 接口的下拉框 |
| AcmeUpload | 附件上传 (PC) | acme.upload.js- |
AcmeUpload.init(opts) |
拖拽分片直传 OSS，进度条及 Policy Token 自动绑定 | Uploads | ✔ 强制 | - | 严禁手写后端服务器中转上传，避免 IIS 网带宽打满 |
| AcmeEditor | 富文本 (PC) | acme.editor.js- |
AcmeEditor.create(opts) |
Quill 驱动富文本输入，支持直传图片至 OSS 归档 | Forms | ✔ 推荐 | - | 禁止直接在富文本中保存 Base64 图片大字段至数据库 |
| Msg | 状态消息 (PC/M) | wwwroot/js/lib.js- |
Msg.Success / Error |
Toast 提示、阻断式警告、iframe 父子弹框穿透传递 | Feedback | ✔ 强制 | - | 强硬红线：绝对禁止使用原生 window.alert / confirm |
| Ajax | 基建服务 (PC) | lib.js- |
Ajax.Get / Post |
统一底层 XHR 请求封装，拦截 LongTask 返回 `taskNo` | Feedback | ✔ 强制 | - | 禁止使用未被包装的原始 $.ajax 或 fetch |
| TaskCenter | 任务中心 (PC) | acme.taskCenter.js- |
TaskCenter.flyToTaskCenter |
长耗时异步任务状态中心，物理飞入动画与周期轮询 | Feedback | ✔ 强制 | - | 耗时超过 5s 的任务禁止同步 Block 页面，必须走异步 |
| LoadingState | 载入状态 (PC) | wwwroot/js/lib.js- |
LoadingState.init(container, opts) |
表格/抽屉/页面区块加载时的轻量骨骼旋转 Spinner | Feedback | ✔ 推荐 | - | 禁止在异步未完成时显示空页面，防止用户误以为卡死 |
| TraceIdDisplay | 诊断工具 (PC) | wwwroot/js/lib.js- |
Ajax 自动渲染 |
AJAX 500 级崩溃时自动抓取并在 Error 对话框输出 API 追踪 ID | Feedback | ✔ 推荐 | - | 错误弹框必须带 TraceId，严禁仅弹“网络异常”应付 |
| SystemNotificationBell | 通知铃铛 (PC) | 主框架内置 |
window.AcmeSystemNotificationBell.reload() |
右上角基于 API 轮询心跳的实时提醒铃铛下拉列表 | Feedback | ✔ 推荐 | - | 禁止频繁发起 HTTP 轮询去拉取全局最新系统公告数 |
| AcmePrinter | 打印控制 (PC) | acme.printer.js- |
AcmePrinter.init(opts) |
硬件打印机驱动、PDF 查看器封装、合同模板本地/云端转换 | Templates | ✔ 推荐 | - | 禁止绕开组件使用原生 window.print() |
| AcmeKnowledgeBase | 知识库 (PC) | wwwroot/js/components/acme.knowledgeBase.js |
AcmeKnowledgeBase.init(in, container, opts) |
本地 window.LOCAL_SOLUTIONS 关键词模糊检索匹配与回调触发 |
Templates | ✔ 推荐 | - | 不适用于非 markdown 静态内容的高性能全文检索 |
| ProductCard | 卡片布局 (PC) | product-card.js- |
ProductCard.renderHtml(data) |
SPU 规格、单品库存及视觉比例大卡片 | Templates | ✔ 推荐 | - | 禁止使用 bootstrap 的 .card 裸盒子包裹商品信息 |
| global-search | 全局检索 (PC) | global-search.jsglobal-search-ui.css |
自动绑定快捷键 Ctrl+K |
顶部导航或浮层主输入框，全表拼音/简称 Elastic-Search 索引搜索 | Templates | ✔ 推荐 | - | 禁止在没有全表检索时让用户人工分页跨菜单翻找 |
| global-search-spu-drawer | SPU抽屉 (PC) | global-search-spu-drawer.js |
SPUDrawer.open(spu) |
全局检索穿透后呼出的商品 SPU 属性、规格、打印一站式抽屉 | Templates | ✔ 推荐 | - | 禁止直接弹出庞大混乱的商品 SKU 网格表单 |
| MobileUserSearch | 人员选择器 (M) | mobile-user-search.js |
MobileUserSearch.open() |
移动端 H5 专用人员过滤弹窗选择器 | Templates | - | ✔ 强制 | 禁止在移动端引入 PC 端的 modal selUser 渲染 |
| AcmeMobileScroll | 弹性滚动 (M) | wwwroot/js/components/acme.mobileScroll.js |
AcmeMobileScroll.init(root) |
移动端 data-mobile-iscroll 弹性滚动包装器 (IScroll) |
Templates | - | ✔ 强制 | 禁止移动端长页面采用 PC 服务端分页或不做分页全量加载 |
03 / Architecture Map
规范地图与组件分层
Acme Harmony UI 设计系统遵循自底向上的高内聚分层模型，从底层的像素级 Token 规范，到顶层的工程发布自检门禁：
1. 基础规范 / Design Tokens
基于翡翠绿主色（#41b584）派生的 HSL 色卡、Slate Gray 中性文本色、小圆角比例（4px/6px/8px）、三级微动投影（Elevation）以及 Modal/Drawer 标准宽度与高度限制。
前往 Tokens 规格手册2. 布局模型 / Archetypes
确立了纯列表管理页（ListPage）、带弹窗编辑列表（ListModalPage）、带详情抽屉列表（ListDrawerPage）和复杂配置运维页（OperationsListPage）等 6 大标准页面骨架模型。
前往 Layout 范式手册3. 组件一致性契约
统一控件规格。涵盖 DataBinder 编程式下拉绑定、AcmeUpload 拖拽与断点直传 OSS、acmeAgGrid 视口高度自适应监听、AcmeGridOperations 批量工具条及 TaskCenter 异步进度中心接入协议。
4. AI 治理与质量自检
在项目根目录 AGENTS.md 强力注入审核门禁，AI 在开发或改动 UI 代码前必须前置调用本规范，并严格通过 10 大维度自检 checklist 方可执行 Git 安全提交。
前往 Checklist 质量门禁04 / Page Templates
系统重构样板与范本
为了避免“纸上谈兵”，本系统对以下 3 个极具代表性的高吞吐业务页面进行了全方位的 Harmony UI 重构，它们是未来页面开发的标准范本：
| 业务样板页面 | 适用 Archetype | 核心重构细节与依据 |
|---|---|---|
| 第三方算力 Token 使用监控 | OperationsListPage | 5个摘要卡片升级为无缝微浮雕卡片；重塑状态面板为 Slate Gray 中性扁平面板；ag-Grid 容器强绑定 `acmeAgGrid.enableResizeListener` 高度自适应监听；ECharts 热力图重新调配为翡翠绿渐变。 |
| Codex 使用权限管理 | ListPage | 升级面包屑层级；重构列表工具栏，将次要“同步统计”按钮从 primary 降级为 default，防止按钮墙出现；表格挂载 `AcmeGridOperations` 批量操作。 |
| 招聘需求列表与表单 | ListModalPage | 废除生硬的二次 card 包裹，改用标准的 `.acme-form-section` 规范类；通过 modal-content flex 限定与 modal-body 滚动条，彻底消灭双重滚动条。 |
05 / Version Log
版本与发布记录
| 版本 | 发布日期 | 主要变更内容 | 状态 |
|---|---|---|---|
v2.0.0 |
2026-05-28 | **重磅升级！** 废除空泛设计概念，将 23 项仓库真实存在的组件、Partial、JS 及 CSS 封装全部纳入，反向建立企业“组件资产总表地图”。深度重构 Forms、Tables、Templates 及 Feedback 页面，提供工程级 API 参数、签名、常见错误与 Do/Don't，建立真正的 Ant Design 式工程手册。 | Active |
v1.0.0 |
2026-05-28 | 初始化 Harmony UI 规范，建立 app.css CSS 变量与 Tokens，发布 10 个子视图规范，重构 3 个主样板页面。 | Deprecated |