docs/Admin-Client前端原型还原验收规则.md

Admin / Client 前端原型还原验收规则

目标

Admin 与 Client 已向客户讲解或确认过的页面，必须以对应原型为直接事实来源逐页还原。不得先统一套用现有设计系统、抽屉、弹框、详情页或图标规范，再局部调整。

修改门禁

每个页面修改前必须先形成以下矩阵，并给出原型文件及行号、元素 ID、函数名或截图证据：

页面	操作	原型承载方式	原型尺寸/布局	当前实现	结论
示例	详情	独立页面	页面级头部、返回列表	右侧抽屉	改为正式路由页面

操作至少分别核对：详情、新增、编辑、审核/确认、文件预览、删除/停用确认。不得以其中一个操作的结论推断其他操作。

承载方式

• 原型使用独立页面：必须使用正式路由、页面级布局和明确返回入口；不得改成抽屉或弹框。
• 原型使用居中弹框：必须使用居中模态框，并按原型宽度、标题、正文、底部按钮和关闭方式还原；不得改成右侧抽屉。
• 原型使用侧滑面板：仅该操作允许使用抽屉，并按原型方向、宽度和内部布局还原。
• 原型未定义：先停在矩阵中标记待确认，不得因为公共组件方便而自行选择。
• 同一列表的详情、新增、编辑、审核可以采用不同承载方式，必须逐操作判断。

视觉与排版

• 字段顺序、分组、摆放、列宽、控件宽高、换行、对齐、外边距、内边距、间隙和留白按原型逐项核对。
• 顶部背景色、页面背景、区块背景、边框、圆角、阴影、字号、字重和文字颜色直接取原型值。
• 按钮位置、顺序、尺寸、颜色、危险语义、悬停态、禁用态按原型还原；不得自行增加“更多”菜单或纯文字替代。
• 原型已提供图标、字符图标、图片或 SVG 时直接复用原型资源；不得自行绘制或替换。
• 表格按原型核对外边框、单元格边框、表头背景、斑马纹、行悬停背景、行高和横向滚动。
• 原型没有的公司名称图标、下划线、卡片装饰、悬停上浮、缩放和渐变效果不得添加。

Admin 已确认布局基线

• Admin 所有弹窗的统一目标风格见 Admin 统一弹窗规范（2026-10-19 测量弹窗样板）。按大模块逐组盘点、实现和截图确认；在已确认范围内优先采用该规范的外观与密度，原业务字段、权限、提交逻辑以及独立页面/弹框/抽屉承载方式继续逐操作核对。
• 订单样板及国内仓样式统一采用 Admin 高密度界面规范。其已确认的密度、容器和页签图标规则优先于历史原型中的对应视觉；字段、业务分组、权限、操作语义与页面/弹框/抽屉承载方式继续逐操作核对。该规范不表示其他页面已完成验收。
• Admin 是高信息密度业务系统。保留原型字段、顺序、业务分组和交互语义，但普通短字段优先使用连续白底、多列键值网格、描述表或紧凑列表，不把“一个标签 + 一个值”做成独立卡片。
• 详情页顶部尽量合并返回、标题、核心状态和主要操作；路由壳层已显示标题时正文不重复。状态或流程结论只保留一个主要视觉落点，除真实错误、阻断或危险外不叠加大面积彩色横幅。
• 在 1920×1080 下短字段通常并排 4–6 组；长文本、地址、备注和异常原因可以跨列或换行。长编号集中省略说明列宽设计失败，应调整列数、宽度或跨列，不继续缩小字号。
• 同一详情页使用一致的内容底色和容器语言；连续白底区域用分隔线和间距分区，同级独立卡片的背景、圆角、边框和外间距保持一致。
• 高信息密度不授权缩小可点击区域、删除标签、强制截断关键值或牺牲可访问性。使用真实长编号、空值、状态徽标和多字段数据核对首屏。
• 原型明确的承载方式和视觉细节优先；历史原型仅因大量字段卡片、重复状态块或过度留白与当前密度基线冲突时，收敛承载方式但不改变字段、分组和交互语义。

响应式与可访问性

• Admin、Client 当前只按 1920×1080、浏览器缩放 100% 验收；不检查或整改 720px、320px 等窄屏，也不删除已有响应式能力。用户恢复多视口验收后再统一调整。
• 弹框正文超过视口时只滚动正文，标题和操作区保持可见；独立详情页按正常页面滚动。
• 字段数量较多、两列会导致弹框明显过高时，在 1920×1080验收视口下改用宽版三列表单；短字段单列占位，地址、长文本、备注、文件和表格按内容跨列或整行。小型确认类弹框不因此扩宽。
• 保留键盘操作、焦点、表单标签、图标按钮名称和足够对比度。可访问性调整不得改变原型的主要布局与视觉语义。

执行与验收

1. 先提交逐页矩阵，不直接批量替换公共组件。
2. 总控冻结该页结论后，任务只修改职责内模块，不触碰其他任务在途文件。
3. 修改后由人工在 1920×1080、100% 缩放下操作并提供截图，标注与原型仍存在的差异；缺少截图时记录“待人工截图确认”，AI 不自行批量取证。
4. 运行直接测试与类型检查；共享组件变更必须检查全部消费者。
5. 不触发 Jenkins、不部署、不提交，除非当前对话另有明确授权。

已确认示例

Admin 客户管理原型：

• 客户详情：独立页面（page-tenant-detail）。
• 新增客户：居中宽版弹框（modal-tenant-add，宽度约 1120px），基础资料和联系与商务使用三列，地址、备注和资质表格整行。
• 编辑客户：复用新增客户的居中宽版三列弹框（modal-tenant-edit，宽度约 1120px）。
• 重置密码：居中弹框（modal-tenant-reset-password，宽度约 520px）。
• 入驻审核：居中弹框（modal-tenant-audit，宽度约 900px）。

这些结论只适用于上述操作，不自动推广到其他页面。