Arco Design

## 任务目标

请基于 Arco Design Vue，对指定 Vue 工程或模块完成工程标准化、代码整理和界面优化。直接修改并交付可运行的代码，保持真实业务流程与数据含义，完成检查和页面验收，不要只给审查意见、设计建议或静态效果图。

在现有授权范围内完成实际改动和验证；缺少外部条件时先完成可独立实现的部分，不能只停留在计划。

## 输入信息（选填）

两项均可留空，也可直接用一句话说明目标并附上已有资料。无需自行整理版本、配置或完整需求表；能读取的内容由执行者补齐。

改造目标：从当前对话、选定文件和改动关联路由识别待整理页面；未指定具体问题时，先检查一个代表性业务页面的结构、Arco 用法与中文布局，再在能够确认的局部范围实施。
工程或页面资料：读取当前已确认工作区的 Vue 工程、页面、接口和现有设计配置；已有截图或访问入口作为界面比对资料，不要求重复填写版本和组件清单。

## 信息不完整时

先使用本次对话中已经说明的信息；用户留空、写“暂无／不清楚”或未替换输入标记，都按缺失处理，不当作真实路径、参数或业务值。已能从资料确定的内容不重复询问，不编造文件、日志、接口、业务值或执行结果。在用户已授权的范围内读取相关工程和材料，不为补齐输入擅自扩大操作范围。

### 优先确认

- 检查分支、已有改动、package.json、锁文件和构建入口，确认 Vue、Arco、Node、JS/TS 及包管理器。
- 沿路由追踪查询、编辑、权限、字典与请求封装，识别重复组件和状态所有者。
- 读取已安装 Arco 类型及样式入口，核对 ConfigProvider、Table、Form、Modal 的属性、事件、校验返回值和主题机制。
- 查找现有布局、语言、字号、间距、ESLint、Prettier 和 EditorConfig 约定及可执行检查脚本。

### 可采用的默认处理

- 沿用实际技术选型和 Arco 版本，仅整理本次页面及直接关联的公共能力；不自动迁移 Vue 2 或混合组件库，不整仓格式化。
- 无设计约定时采用正文已有的桌面政企业务界面默认值，兼顾窄屏；默认不新增深色模式、统计指标和装饰性文案。
- 保留现有字段、权限、字典码和操作顺序；未知字典值可识别地显示原值，按 Arco Vue 的真实 API 实现表单和弹窗，不套用 Ant Design。

### 必须有依据的事项

- 同一字段的金额、时区、状态码或权限规则在页面与接口之间相互矛盾，且本次改造必须选择其中一种才能保存正确业务数据。
- 目标要求必须使用 Arco Vue，但当前工程不支持该库且完成目标需要主版本迁移或更换组件库；该迁移范围不能自行决定。

只有缺口会改变业务结果、权限边界或关键实现，且无法从现有资料确认时，才集中提出最多 3 个关键问题；说明影响，并继续完成不依赖答案的部分。一般命名、排版和可逆实现细节按现有约定决定，不逐项等待确认。

### 资料仍不足时的交付

- 只有截图时交付页面分组、主次操作、中文排版和状态反馈的具体调整方案，明确交互及接口尚未验证。
- 没有工程时给出 Arco Vue 组件职责、数据契约核对表和最小接入示意，不创建未经要求的新系统或声称改造已完成。

## 执行要求

### 先明确工程现状与改造边界

检查当前分支、未提交改动、package.json、锁文件、构建配置、路由、权限、接口封装、状态管理和组件目录，列出本次涉及的页面及主要问题。保留无关改动，不以格式化为由改写全仓库。
核实 Node、Vue、TypeScript、Arco、构建工具与包管理器版本，沿用已有锁文件和安装方式。Arco Design Vue 的包名是 @arco-design/web-vue，适用于 Vue 3；不得混用 @arco-design/web-react 或其他组件库的接口。发现 Vue 2、混合组件库或版本不兼容时，先说明迁移影响，不擅自升级主版本或全量替换。
已有工程逐步整理；只有明确要求新建时才创建工程。未明确提供仓库或业务资料时，先检查当前可访问工程；仍缺资料则完成可落实的结构与页面方案，不编造已完成的改造。可从代码确认的事项自行确认，只提出阻塞业务判断的问题。
不擅自修改接口字段、权限规则、审批顺序、统计口径、路由地址、持久化键和对外事件。必要的契约调整必须说明影响并同步处理调用方。

### 统一代码结构与复用方式

沿用工程既有分层，将页面编排、业务组件、可复用组件、组合式函数、接口请求、类型、字典和样式放在职责清楚的位置。缺少约定时，可使用 views、components、composables、api、types、constants、styles；不要为了目录形式拆出大量空文件。
新建 Vue 3 组件优先遵循项目的 Composition API 与 script setup 用法。声明清楚的 props、emits 和接口类型，禁止直接修改 props、用 any 掩盖类型问题、无依据的非空断言以及跨层读取组件内部状态。JS 工程按范围补足必要类型说明，不强行一次性迁移整个工程。
先查找已有能力，再抽取组件、composable 或纯函数。至少有明确复用场景或独立业务职责时才抽取；不要重复封装无业务增益的 Arco 按钮、输入框，也不要制造用几十个开关控制所有页面的万能表格、万能弹窗。
纯格式化、数据转换可放 util；含响应式状态、生命周期或副作用的逻辑放 composable；请求统一经过现有请求层。组件不得直接拼接 SQL 或持有服务端密钥。
状态码、权限码、业务类型和单位集中定义。以后端字典为准的值使用同一数据来源，保留 code 与 label 的对应关系，不在多处复制数字和中文判断。未知、历史或停用字典值保留可识别的原值，不默认替换成第一项。
删除本次范围内确认无用的导入、变量、分支、样式和旧代码。查清动态路由、自动注册及反射式引用后再删除文件。禁止保留注释掉的整段旧实现和没有使用场景的兜底层。

### 统一格式、检查和注释

以现有 ESLint、Prettier、EditorConfig 为准；缺少规则时默认 UTF-8、LF、2 空格缩进、文件末尾换行，统一引号、分号、属性换行和导入顺序。不要混用 Tab 与空格，不做对齐式空格堆砌。
按工程实际 ESLint 版本配置 Vue 与 TypeScript 支持，避免同时引入互相冲突的旧配置和 flat config。格式化规则与代码质量规则分工清楚，不堆叠重复插件，不用全局关闭规则、ts-ignore 或大范围 disable 消除报错。
提供与当前包管理器相符的 lint、必要的类型检查和 build 命令；已有脚本可复用就不另造一套。TS 工程检查 Vue 单文件组件类型，使用兼容版本的 vue-tsc 等现有工具。说明实际运行命令，不把示例命令当作运行结果。
名称表达业务含义。注释用简明中文解释业务约束、兼容原因和复杂计算；公共方法说明必要参数、返回值与边界。不要给每一行加翻译式注释，不写装饰性分隔线、口号或与产品无关的说明。

### 按 Arco Vue 实际能力接入组件与主题

优先阅读已安装版本的类型声明与对应版本官方文档。不能因为同样使用 a- 前缀就照搬 Ant Design Vue 的 props、事件、插槽或主题配置。组件名称、图标入口、按需加载与样式加载方式都必须能在当前工程中验证。
全量引入样式的官方入口是 @arco-design/web-vue/dist/arco.css；按需方案应核实组件样式和浮层样式均已加载，不重复引入整套样式。中文语言在统一入口配置，ConfigProvider 的 locale 使用语言包对象，例如从 @arco-design/web-vue/es/locale/lang/zh-cn 导入，而不是直接传入语言字符串。全局尺寸按当前版本支持的 mini、small、medium、large 统一选择，并检查局部覆盖。
优先使用当前版本真实存在的主题变量或项目设计变量，集中管理主色、背景、边框、文本、间距与圆角。采用 Less 变量定制时必须匹配 Less 样式与构建配置，不能仅加载预编译 CSS 后期待编译变量生效。不要复制其他组件库的主题 token API。
业务样式优先限定在业务容器和语义类名内，减少深层选择器；必须覆盖组件内部样式时，限定范围并说明原因。禁止大范围覆盖 .arco-*、堆叠 !important，或通过固定高度、负边距掩盖布局问题。
仅在业务需要时提供深色模式；官方深色机制使用 body 的 arco-theme="dark" 属性，仍应检查自定义区域、图表、弹层和文字对比度。函数式 Modal、Message 等额外验证语言、主题和应用上下文，不假定包裹 ConfigProvider 后任何独立调用都会继承配置。

### 建立克制、规整的中文业务界面

以下数值属于本项目缺少规范时的设计建议，不是 Arco 官方强制标准。已有品牌和设计规范优先，同一工程保持一致。
采用中性浅灰页面背景、清晰的内容表面、单一主色和必要的状态色。默认正文 14px、辅助说明 12px、区块标题 16px、页面标题 20px；间距优先使用 4、8、12、16、24px。字号、行高、圆角和边框形成稳定层级，不随页面任意新增尺度。
查询列表页按“标题与主要操作 → 查询条件 → 结果或业务内容 → 分页”组织；需要结果摘要时才增加摘要，详情与编辑页面按业务内容分组。对齐左边缘、控件基线、操作区和内容宽度，同类页面沿用同一骨架。用留白、分组和轻边框区分层级，不把每一小段内容都包成卡片。
主按钮突出当前最重要的业务动作，次要动作保持克制；相同行为的按钮顺序、名称和危险色一致。图标辅助识别，不代替必要文字，不混用多套视觉风格。
不添加大面积渐变、玻璃效果、夸张阴影、胶囊化控件、彩虹状态卡、装饰性徽章和占据首屏的欢迎区。没有业务数据支撑时不增加统计指标、增长率、荣誉认证和宣传口号。
文案使用真实业务名称，短而明确；提示说明用户需要做什么。界面不展示组件实现、内部架构、技术术语堆砌或“智能赋能”等无实际含义的宣传文字。不要为展示设计能力改变用户已熟悉的办理顺序。

### 把列表、表单和详情作为完整业务流程处理

列表：筛选项按使用频率排序，展开与收起不丢值；查询、重置和变更每页条数后的页码规则明确。对象标识、关键状态及主要操作易于定位；文本通常左对齐，金额和数量右对齐并注明单位。长内容提供完整查看入口，状态同时用文字表达，不只靠颜色。
Table 的数据、列、唯一键、分页、排序、选择事件必须核对 Arco Vue 文档。row-key 使用稳定业务键字段，不用页内序号冒充记录标识；远程分页、排序和筛选与服务端参数对应，不对单页数据做排序却宣称全量排序。selected-keys 等受控选择仅维护一份真实状态，明确当前页和跨页批量选择范围。
详情返回列表时按业务需要保留筛选、页码和滚动位置。批量操作反馈成功、失败与可重试范围，能定位失败记录；关键字段、长公司名、大金额和时间信息不被固定列或操作列遮挡。
表单：字段按业务填写顺序分组，标签、必填标识、控件宽度及帮助文字一致。错误在字段附近展示并可定位，保存失败保留合理输入，重置前确认需要恢复的基准值。日期、时区、精度、ID 字符串及空值含义以接口契约为准，不用格式化操作改变业务值。
Arco Form 使用 model，FormItem 使用 field 对应数据路径。validate() 的成功结果是 undefined，失败结果是错误对象，不能仅靠 catch 判断校验失败；resetFields 与 clearValidate 分别涉及字段重置与校验状态清理，不能互相替代。按已安装版本确认行为后实现。
简单确认使用弹窗，较长编辑或需要保留列表上下文时选择合适的抽屉或独立页面。弹窗使用当前版本支持的 v-model:visible；异步确认正确处理 on-before-ok 的返回结果。before-close 是事件，不能当作异步关闭守卫。提交失败时不误关弹窗，重新打开时不残留上一条记录和校验状态。
详情页先呈现对象名称、编号、状态和适用操作，再按业务关系组织字段。审批记录和时间线来自真实数据，不补造操作者、进度或成功记录。

### 保证状态、权限与请求一致

区分初次加载、刷新中、无数据、查询无结果、失败、权限不足和成功。空值、零值与未知状态不能混用。失败提供适当重试入口，恢复后回到正常界面，不把临时加载失败永久保留为“服务升级中”。
复用现有请求封装与错误处理，用户提示和排查日志各有明确位置，不重复弹出同一错误。快速切换筛选、路由或编辑对象时，使用适当的请求取消或结果序号校验，防止旧响应覆盖新状态；清理定时器、监听器和订阅。
提交按钮展示处理中状态并防止连续点击，但不把前端禁用当成服务端幂等保证。写请求超时不能直接认定失败并自动重复提交，应展示结果待确认，并提供结果查询或人工核对路径；用户点击确认本身不代表可以安全重试。
菜单、按钮、数据列表、详情、导出和统计遵循实际角色、组织与租户范围。前端隐藏按钮不能替代服务端授权。缺少后端能力时明确指出，不用前端模拟校验宣称已经解决权限或幂等问题。
不硬编码真实密钥，不把错误堆栈和敏感业务字段展示给用户。富文本、外部链接和文件操作沿用工程安全约束，避免未经处理的 v-html。

### 兼顾性能、适配和可操作性

基于实际瓶颈优化：避免模板内重复大规模运算、无意义深度监听、重复请求以及可以局部更新却整页重建的行为。按现有能力使用路由懒加载和资源按需加载；大列表先核实分页与组件能力，确有需要再采用虚拟化，不凭空宣称性能提高多少。
同一页面信息密度一致，不用极小字号、压缩点击区或大面积空白解决布局问题。宽表可在自身区域横向滚动，页面主体不得意外横向溢出；窄屏合理收纳筛选和次要操作，保留关键对象、状态与主要动作。
按约定终端验收；未约定时桌面至少检查 1440px 和 1280px 宽度，窄屏兼容检查 768px 和 390px。检查长中文换行、固定区域遮挡和弹窗可见范围，不以固定宽高适配所有屏幕。
保证键盘能够进入主要操作，焦点可见，弹窗关闭后焦点合理返回。仅图标按钮有可理解的名称，重要信息不只依赖悬浮或颜色；检查浏览器放大后的文本与操作可达性。使用真实或明确标记的脱敏样例覆盖边界内容。

## 交付与验收

### 完成验证并交付

先改造一个有代表性的页面验证公共规则，再在明确范围内推广；已有明确规范或任务很小时直接按范围实施，不增加无必要的审批环节。
运行与变更匹配的 lint、类型检查、构建和已有测试。对校验、字典映射、请求竞态、权限状态、批量操作等实际风险补充必要测试，不为颜色、空格或简单配置编写只重复实现的测试。
实际打开改造页面，至少验证查询与重置、分页、详情返回、新建或编辑、校验失败、保存成功与失败、取消关闭，以及范围内涉及的权限和异常状态。检查本轮产生的控制台错误、请求失败、中文截断、布局溢出和按钮遮挡；后端不可用时区分静态检查与真实联调结果。
交付时简要说明：改了哪些文件及原因；采用的布局与主题约定；复用或删除了哪些重复能力；实际运行的命令及结果；实际验证的页面和状态；尚未验证或依赖外部条件的事项。必要时提供页面截图对比，不伪造测试通过、数据结果和性能结论。
默认直接修改已有工程并在回复中说明使用方式，不额外生成总结类 Markdown 文档；只有用户明确要求或项目流程已有明确要求时才增加相应文档。

### 本条完成检查

- 交付实际改动文件、职责与状态归属、布局和主题约定，说明重复能力的复用或删除依据。
- 核对 Form 的 model/field 与 validate 返回值、Modal 的 visible/on-before-ok、Table 的稳定键和受控选择，验收成功、失败及切换记录。
- 运行适用的 lint、类型检查和构建，检查正文规定的桌面与窄屏尺寸、中文换行和新增控制台错误；未执行项单列。

按本条要求组织结果，使用简洁中文和一致的编号、术语、缩进及空行；已有项目格式优先。只说明实际完成的内容，将采用的假设、未完成项和缺少的条件写在相关位置，不额外生成无关文档。未执行、无法复现或缺少证据的检查如实标注，不宣称已通过或已有性能收益。

## 参考资料与适用边界

本提示词是结合 Arco Design Vue 官方资料整理的工程执行规则。组件用法按官方资料核对；目录划分、视觉默认值与交付要求属于项目实践建议，不代表官方认证，也不表示已经在任意工程中运行验证。资料核验日期：2026-09-08；下面的 main 链接会更新，实际实施必须以工程安装版本及对应版本文档为准。

[Arco Design Vue 官方仓库与安装入口](https://github.com/arco-design/arco-design-vue)
[ConfigProvider 中文配置与上下文](https://github.com/arco-design/arco-design-vue/blob/main/packages/web-vue/components/config-provider/README.zh-CN.md)
[中文语言包使用示例](https://github.com/arco-design/arco-design-vue/blob/main/packages/web-vue/components/config-provider/__demo__/basic.md)
[主题定制](https://github.com/arco-design/arco-design-vue/blob/main/packages/arco-vue-docs/docs/theme.zh-CN.md)
[深色模式](https://github.com/arco-design/arco-design-vue/blob/main/packages/arco-vue-docs/docs/dark.zh-CN.md)
[Table 数据、分页与选择](https://github.com/arco-design/arco-design-vue/blob/main/packages/web-vue/components/table/README.zh-CN.md)
[Form 校验与字段方法](https://github.com/arco-design/arco-design-vue/blob/main/packages/web-vue/components/form/README.zh-CN.md)
[Modal 异步确认与关闭](https://github.com/arco-design/arco-design-vue/blob/main/packages/web-vue/components/modal/README.zh-CN.md)

## 任务目标

请为桌面管理端与小程序建立一致而可实现的组件使用约定。目标是减少同类页面的视觉和交互偏差。

交付能用于评审或后续实施的具体方案、规则与样例；未要求实施的部分不声称已经落地。

## 输入信息（选填）

两项均可留空，也可直接用一句话说明目标并附上已有资料。无需自行整理版本、配置或完整需求表；能读取的内容由执行者补齐。

组件统一范围：从当前桌面端和小程序中承担相同业务任务的页面识别范围；未指定组件时，先整理已有查询区、状态、选择器、附件和操作栏，不新增不存在的终端。
工程或设计资料：读取现有包版本、组件引用、业务封装、主题变量和页面样例，使用已提供品牌资料识别共同规范与跨端差异。

## 信息不完整时

先使用本次对话中已经说明的信息；用户留空、写“暂无／不清楚”或未替换输入标记，都按缺失处理，不当作真实路径、参数或业务值。已能从资料确定的内容不重复询问，不编造文件、日志、接口、业务值或执行结果。在用户已授权的范围内读取相关工程和材料，不为补齐输入擅自扩大操作范围。

### 优先确认

- 查两端实际组件包、锁文件和封装入口，核对当前版本支持的组件 API 与样式配置机制。
- 定位同类业务组件的使用页面，比较输入、状态、权限与操作结果，不只比较外观。
- 盘点主题变量、局部样式覆盖与已有设计稿，找出重复定义、不同业务同名及触屏不可用的交互。

### 可采用的默认处理

- 沿用现有组件库与版本，先给使用约定和差异映射，不为统一外观引入第二套库或升级框架。
- 跨端统一业务含义、状态名称与主次操作，保留表格和移动记录卡、点击和触摸等必要呈现差异。
- 优先复用现有视觉变量，缺值时提出少量项目建议；颜色、字号和间距不包装为组件库强制规则。

### 必须有依据的事项

- 两端同一字段或状态的业务含义不同且无法从契约解释时，不能直接合并为通用组件。
- 实际安装版本或 API 支持无法确认时，不能承诺对应代码可运行；先交付组件职责和状态约定。

只有缺口会改变业务结果、权限边界或关键实现，且无法从现有资料确认时，才集中提出最多 3 个关键问题；说明影响，并继续完成不依赖答案的部分。一般命名、排版和可逆实现细节按现有约定决定，不逐项等待确认。

### 资料仍不足时的交付

- 只获得一端工程时，先交付该端盘点及已知跨端业务约定，把另一端的 API 与适配核对留为明确缺口。
- 只有设计资料时交付业务组件映射、变量建议、状态矩阵和交接样例，不声称完成代码兼容验证。

## 执行要求

主题、设计变量和组件 API 均以项目安装版本为准；跨端统一的是业务含义和使用约定，不能假定不同组件库的 API 相同。

1. 盘点项目实际使用的组件库、版本、定制组件和样式覆盖，区分已经存在与建议新增。先确认项目选择，优先复用已有组件库。
2. 建立业务组件清单，将查询区、审批状态、附件区、成员选择、操作栏等映射到基础组件或组合组件，注明适用场景和不适用场景。名字应能让设计与研发直接对应。
3. 整理颜色语义、文字层级、间距、边框、圆角与控件密度，优先使用当前库的可配置变量。必须自定义时解释业务原因，变量值来源未知的标为建议。
4. 定义组件的默认、悬浮、聚焦、禁用、加载、错误和只读状态，明确哪些状态适用于触屏。不能把鼠标悬浮作为小程序读取重要内容的唯一方式。
5. 逐项区分跨端保持一致的业务含义与需要因终端改变的呈现，例如审批结果名称一致，但桌面表格与手机记录卡可不同。明确点击、触摸、返回和输入法下的行为。
6. 形成设计到研发的对照与验收样例，列出长中文、空值、大数值、无权限、弱网等内容条件。核验组件 API 应基于安装版本文档，不能凭名称推断支持属性。

## 交付与验收

输出：现有组件盘点、业务组件映射、视觉变量建议、状态矩阵、跨端差异表、设计交付与验收清单。涉及代码时仅使用已核实版本支持的能力。

验收：相同业务状态名称与含义一致；视觉变量有来源；终端差异有任务依据；不存在组件库混用造成的重复样式；小程序任务不依赖桌面专有交互。

信息边界：未读取实现或未运行终端时不得声称完成兼容验证；官方仓库说明只能证明其公开能力，不能作为对本项目质量或合规性的品牌背书。

### 本条完成检查

- 组件映射有真实使用位置，相同状态的名称与含义一致，例外有业务理由。
- 变量、版本与能力来源明确，不假设不同组件库 API 相同。
- 触屏任务不依赖悬浮等桌面专有操作，长中文、空值、无权限及弱网样例进入验收清单。

按本条要求组织结果，使用简洁中文和一致的编号、术语、缩进及空行；已有项目格式优先。只说明实际完成的内容，将采用的假设、未完成项和缺少的条件写在相关位置，不额外生成无关文档。未执行、无法复现或缺少证据的检查如实标注，不宣称已通过或已有性能收益。

## 参考资料与适用边界

参考来源（核验于 2026-09-08）：
- [Arco Design 官方仓库中文说明](https://github.com/arco-design/arco-design/blob/main/README.zh-CN.md)
- [TDesign 官方仓库](https://github.com/Tencent/tdesign)