# 业务模块界面规范：adminui-v1（必须遵守）

本平台的统一视觉来源为 `C:/outlook.code/adminui`：浅色侧栏、紫色强调色、统一卡片、表单和表格，并支持深浅主题。工单、报销、请假及后续业务模块必须遵守本规范。在线样板：`/docs/ui-style`；SDK 样板：`ui/index.html`。

## 协议 v1 的推荐方式

模块实现 `modulekit.Business`，通过 `Describe()` 声明标题、说明、fields，通过 manifest.json 声明 record_columns、permissions 和 role_templates。底座统一生成菜单、登记表单、列表和权限界面，自动应用 adminui-v1 风格；模块无需自带 HTML、CSS 或登录页。

当前 ZIP 仅允许 manifest.json、本机架构的模块可执行文件和可选 simulation.json。不要将 Vue 构建物、CSS、第三方脚本或其他资源塞入模块 ZIP；协议 v1 尚不接受自定义前端资源。新增交互能力应先扩展底座描述协议，再由所有模块共享。

## 视觉与组件要求

- 必须使用平台主题变量。主色 `--c-brand`，强调 `--c-brand-strong`，浅底 `--c-brand-soft`；画布 `--c-canvas`，卡片 `--c-surface`，浮层 `--c-elevated`，正文 `--c-text`，说明 `--c-text-muted`，边框 `--c-border`，表头 `--c-table-head`。
- 浅色基准：主色 #5b5ef0、画布 #f5f7fc、正文 #121826、边框 #e4e8f2；深色通过相同变量切换，不得硬编码白底黑字。
- 布局采用 236px 侧栏、64px 顶栏、24px 主区留白。卡片圆角 16px，控件 10–12px；字体使用 Inter、系统字体及中文字体回退。小屏必须可操作，表格仅在容器内滚动。
- 标题、说明、统计卡、操作区、表单、列表按相同层级排列；主操作使用紫色按钮，次要操作使用中性或浅紫按钮。状态必须同时展示文字与语义色，不得只依赖颜色。
- 表单字段使用明确中文标签；必填、长度、枚举由 Describe 声明，并在模块服务端再次校验。不得加入脚本、内联 HTML 或富文本执行内容。
- 表格使用统一表头色、行分隔线和悬停色；空态、错误、加载态必须说明当前情况。长列表使用有界滚动容器，禁止宽表撑破布局。
- 菜单来自平台注册与权限目录，不得在模块内另建侧栏、账号系统或导航壳。角色和用户权限在后台统一配置。
- 图表如后续协议支持，仅采用 Apache ECharts，颜色使用主题变量；不得新增第二套视觉系统。

## 模块验收清单

1. Describe 与清单一致，底座自动展示标题、字段、列表列与菜单；文字清楚，无硬编码品牌色或自定义布局。
2. 在浅色和深色主题下检查表单、列表、状态标签、弹窗、空态及错误文字。
3. 检查桌面和手机宽度，字段不溢出，表格在容器滚动，主操作可见。
4. 验证只读、登记与管理员角色，菜单和按钮遵循服务端权限；邮件登录继续由底座负责。
5. 提交 simulation.json，在后台完成隔离模拟测试，再由管理员审核功能与界面后批准发布。

自动模拟测试覆盖协议、业务校验、数据隔离、幂等和权限；视觉一致性仍需管理员按本清单检查。不要将模拟测试通过当成任意前端界面已自动验收。