feat: 标准资源使用独立页面并优化详情布局

2026-08-11 00:49:41 +08:00
parent 7242048abf
commit 13daa996a2
39 changed files with 3826 additions and 2106 deletions
--- a/docs/05-平台总后台需求.md
+++ b/docs/05-平台总后台需求.md
@@ -110,6 +110,14 @@

 当前资源契约共 48 个资源。下表中的路径均相对于 `/heqi/platform/v1`。

+标准列表资源统一使用独立页面承载新建、详情和编辑，不再从列表打开抽屉。浏览器路径分别为“列表路径 `/new`”“列表路径 `/:identity`”“列表路径 `/:identity/edit`”；页面通过 `return_to` 保留来源列表、筛选上下文和返回位置。详情采用响应式信息分区与关联子表，编辑和新建采用双列表单。审核、启停、归档、重置密码、流程流转等短操作继续使用确认框或模态框，不与基础资料保存混合。树形资源仍沿用树页面交互。
+
+新建和编辑页使用全宽信息卡，内部表单内容最大宽度为 `1440px`，并按内容容器宽度在双列与单列之间切换。页面内容从顶部自然排列，只保留面包屑和右侧返回按钮，不重复展示“新建/编辑资源名称”及操作说明；字段和底部操作按钮保持统一基线。账户头像摘要和详情页展示结构不随该表单布局调整而改变。
+
+标准详情页同样只保留面包屑、编辑和返回操作，不重复展示“详情资源名称”及说明文字。详情卡片按内容自然高度从顶部排列，统一使用 `12px` 间距和紧凑内边距；基本信息在大屏、中屏和小屏分别采用三列、两列和单列。未开通钱包使用单行提示，气站启停继续保留独立状态管理卡片，不改变原有接口和权限校验。
+
+新建与编辑使用不同字段规则。唯一标识、用户名、创建编码、不可变归属等创建后锁定字段只读展示且禁止修改；后端更新协议要求原归属标识时，页面只会原样回传该字段。合同状态、检修结果、系统角色和平台权限等限制同时由页面和后端校验。编辑页离开前检测未保存内容，详情页的聚合子表、钱包摘要、气站状态开关及资源专属业务动作继续保留。
+
 ### 6.1 机构管理

 | 资源 | 路径 | 模式 | 已实现能力 |
@@ -130,7 +138,7 @@

 工作人员支持安装人员 `installer`、配送人员 `delivery`、运维人员 `operations` 三种角色，可关联气站或配送点，并记录在岗/离岗状态。前端按角色提供独立列表和新增入口；后端按菜单和人员实际角色校验详情、修改及资质访问。

-工作人员详情与编辑使用独立资料页，不再使用列表抽屉。资料页默认只读，可切换编辑状态；顶部展示头像、用户名、唯一标识和创建时间，下方维护现有基本信息。头像仅支持 JPG/PNG、本地预览和保存时上传，读取继续受平台 JWT、菜单及人员角色权限保护。
+工作人员的新建、详情和编辑均使用独立页面。账户页面顶部展示头像、用户名、唯一标识和创建时间，下方维护现有基本信息与钱包摘要；头像仅支持 JPG/PNG、本地预览和保存时上传，读取继续受平台 JWT、菜单及人员角色权限保护。用户名和密码仅用于创建，编辑时用户名只读且密码不回填。

 ### 6.3 用户管理

@@ -142,7 +150,7 @@

 用户页面同时提供配送合同入口。当前后台可直接维护用户、地址和服务关系，但尚未实现邀请二维码注册、服务关系审批和完整历史时间线。

-用户账户详情与编辑复用工作人员资料页布局，默认只读并支持页内编辑。用户头像通过受保护资源接口读取，不在通用详情响应中暴露头像 URI；新增用户仍沿用现有新增抽屉。
+用户账户的新建、详情和编辑复用工作人员账户布局，并使用各自独立 URL。用户头像通过受保护资源接口读取，不在通用详情响应中暴露头像 URI；详情页继续展示钱包摘要并可进入钱包独立详情页。

 ### 6.4 智能气阀管理

--- a/docs/11-数据接口与安全.md
+++ b/docs/11-数据接口与安全.md
@@ -121,7 +121,7 @@
 - 银行卡号、身份证号、预留手机号使用 `Global.FieldEncryptionKey` 经 HKDF 派生独立 AES-GCM 加密键和 HMAC 指纹键；接口列表只返回末四位掩码。开发占位密钥不得用于生产。
 - 支付密码独立于登录密码，仅允许六位数字，使用 bcrypt 保存；连续失败达到阈值后在 Redis 短时锁定。绑卡、解绑、余额支付和提现均要求支付密码或限定用途的一次性验证码。
 - 公共上传接口 `/upload/file` 必须携带平台、气站、配送点、用户或工作人员任一合法 JWT；图片/PDF 最大 10MB，视频上限从配置读取。上传只返回资源 URI，业务接口负责建立关联并记录操作者、采集与接收时间。
- 平台账户资料头像使用专用 `/upload/avatar` 上传入口，仅允许真实 JPG/PNG、最大 2MB、最大 4096×4096，并在服务端完成扩展名、MIME、尺寸和完整图片解码校验。头像读取通过 `/heqi/platform/v1/{staff_account|user_account}/:identity/avatar` 受 JWT、菜单和对象角色权限保护；通用列表及详情响应继续移除 `avatar` 字段。
+- 平台账户资料头像使用专用 `/upload/avatar` 上传入口，仅允许真实 JPG/PNG、最大 2MB、最大 4096×4096，并在服务端完成扩展名、MIME、尺寸和完整图片解码校验。头像读取通过 `/heqi/platform/v1/{staff_account|user_account|platform_account}/:identity/avatar` 受 JWT、菜单和对象角色权限保护；通用列表及详情响应继续移除 `avatar` 字段。普通资料更新未提交 `avatar` 时保持原头像，只有明确上传或恢复默认头像时才修改该字段。
 - 充值、支付、提现、工单证据、轨迹点、内容确认等写入均携带幂等号；资金入账在数据库事务内锁定钱包并同时写不可变流水。
 - 钱包可提现余额是当前总余额的子集，始终满足 `0 <= 可提现余额 <= 总余额`。普通消费扣减总余额后，必须同步把可提现余额限制在剩余总余额以内。
 - 提现申请在同一数据库事务内锁定钱包、同时预扣总余额和可提现余额并写入不可变流水；驳回只返还该申请实际预扣的两类余额，完成打款只确认外部结果，不得再次扣款。
--- a/docs/操作日志_标准资源全页改造_20260810.md
+++ b/docs/操作日志_标准资源全页改造_20260810.md
@@ -0,0 +1,67 @@
+# 标准资源全页改造操作日志
+
+## 记录一：范围确认与现状检查
+
+操作时间：2026-08-10  
+操作类型：扩展  
+影响模块：平台总后台标准资源管理
+
+操作前状态：工作人员和用户账户已有独立资料页，其余标准资源的新建、详情和编辑主要使用 `CrudListPage.vue` 内的抽屉；机构账户管理使用二级模态框。  
+具体操作：盘点 48 个资源契约、三类管理端路由、后端 Create/Update DTO、聚合详情、钱包摘要、气站状态、详情动作和树形资源差异；按用户确认将范围限定为 5173。  
+操作后状态：确定 46 类标准列表资源详情、25 类新建和 23 类编辑的全页迁移边界；树形资源和短操作保留原交互。  
+风险评估：创建字段与更新字段不一致是主要风险，采用显式资源字段规则和保存后详情复读缓解。
+
+## 记录二：路由与共享页面改造
+
+操作时间：2026-08-10  
+操作类型：新增、修改  
+影响模块：`frontend/platform_admin`
+
+具体操作：
+
+- 新增标准资源路由生成器，统一创建 `/new`、`/:identity`、`/:identity/edit` 隐藏子路由。
+- 新增共享资源页面、详情内容、双列表单、账户摘要、钱包摘要、业务动作、关系加载、头像和未保存保护组件。
+- 将 `CrudListPage.vue` 收敛为列表与短操作入口，移除标准 CRUD 抽屉和账户二级模态框。
+- 将机构账户管理改为带归属过滤条件的隐藏列表及独立 CRUD 页面。
+- 删除已被共享页面替代的 `AccountProfilePage` 和未使用的 `ReadOnlyListPage`。
+- 拆分仪表盘、财务和资源路由构建文件，控制主要代码文件规模。
+
+操作后状态：所有标准资源的详情、新建和编辑均从列表导航到独立 URL；详情动作、审核、启停、归档等短操作保持原有模态交互。  
+风险评估：路由数量增加但由构建器统一生成，并通过资源覆盖脚本检查，降低漏配和路径漂移风险。
+
+## 记录三：字段规则与安全兼容
+
+操作时间：2026-08-10  
+操作类型：扩展  
+影响模块：资源表单、导航、平台账户头像
+
+具体操作：
+
+- 为可编辑资源逐项声明更新字段、创建隐藏字段、编辑必填和不可变归属。
+- 增加合同、检修、系统角色和平台角色权限的动态编辑限制。
+- 增加智能气阀归属变更专属动作，要求填写动作、原因和备注。
+- 增加安全 `return_to`、404/403 中文错误页、密码长度校验和未保存离开确认。
+- 增加平台账户受控头像读取路由；平台账户更新未提交头像时保持原头像。
+
+操作后状态：编辑请求只提交服务端允许更新的字段，详情继续使用受保护接口和脱敏响应。  
+风险评估：附件 URI 仍受保护且没有受控下载接口，因此本次明确不提供附件预览，避免绕过资源权限。
+
+## 记录四：验证
+
+操作时间：2026-08-10  
+操作类型：验证  
+影响模块：前端、后端、浏览器交互
+
+验证结果：
+
+- `npm.cmd run resource-pages:check`：通过，详情 46 类、新建 25 类、编辑 23 类，列表无标准 CRUD 抽屉。
+- `npm.cmd run contract:check`：通过，48 个前后端资源契约一致。
+- `npm.cmd run type:check`：通过，Vue 与 TypeScript 类型检查无错误。
+- Biome 新增文件错误级检查：通过，无错误级诊断。
+- `npm.cmd run build`：通过，Vue 类型检查和 Vite 生产构建成功。
+- `go test ./...`：通过，后端全部包测试成功。
+- 浏览器：通过用户详情/编辑/新建、钱包详情跳转、机构账户管理、气站状态区、404 中文提示、未保存“继续编辑/确认放弃”和 `/staff/add` 独立页检查。
+- 数据安全：浏览器回归未执行创建、保存、启停、归档或流程动作，没有修改测试业务数据。
+
+边界案例：聚合详情子表在本地缺少完整订单/合同样本，已完成代码结构检查和生产构建，后续使用固定测试数据补充端到端验证。  
+风险评估：本次只改平台总后台；5175、5176 的标准资源仍沿用原交互，不受影响。
--- a/docs/操作日志_标准资源表单布局优化_20260811.md
+++ b/docs/操作日志_标准资源表单布局优化_20260811.md
@@ -0,0 +1,50 @@
+# 标准资源表单布局优化操作日志
+
+操作时间：2026-08-11  
+操作类型：修改  
+影响模块：平台总后台标准资源新建、编辑页
+
+## 操作前状态
+
+- 新建和编辑页使用 `1080px` 最大宽度卡片，在宽屏主内容区两侧产生大面积灰色空白。
+- 面包屑已经表达“资源列表 / 新建或编辑”，页头又重复展示操作大标题及说明文字，下方卡片仍有“基本信息”标题，形成三层重复信息。
+- 页面根节点为网格布局但没有限制纵向内容对齐，在确定高度下可能拉伸自动行，造成顶部和底部空白。
+- 表单只按浏览器视口宽度切换单双列，没有考虑左侧菜单占用后的真实内容宽度。
+- 保存和取消按钮使用底部吸附定位，长表单可能出现覆盖或视觉脱节。
+
+## 具体操作
+
+- 修改 `frontend/platform_admin/src/views/resource/ResourceRecordPage.vue`：
+  - 仅为新建、编辑模式增加专用布局类。
+  - 增加共享 `form-shell` 内容容器，使卡片标题、字段和按钮使用同一基线。
+  - 新建、编辑模式隐藏重复的操作大标题和说明文字，详情模式继续保留原有标题区。
+  - 保留原字段组件、校验、保存和取消事件，不调整业务逻辑。
+- 修改 `frontend/platform_admin/src/views/resource/ResourceRecordPage.less`：
+  - 表单卡片改为主内容区全宽，内部内容最大宽度为 `1440px`。
+  - 页面网格使用顶部自然对齐，并压缩新建、编辑页头间距。
+  - 桌面卡片内边距调整为横向 `32px`，小屏调整为 `16px`。
+  - 表单内容以 `900px` 容器宽度作为单双列切换阈值。
+  - 保存和取消按钮恢复普通文档流定位。
+
+## 操作后状态
+
+- 宽屏下白色表单卡片与主内容区对齐，截图标注的顶部及左右大面积灰色空白已消除。
+- 新建、编辑页顶部仅保留面包屑和返回按钮，表单卡片继续显示“基本信息”，页面层级更简洁；详情页标题和编辑入口保持不变。
+- 输入区仍由最大宽度限制控制可读性，不会在超宽屏无限拉长。
+- 账户头像和身份摘要保持现有居中设计，详情页和业务操作弹窗不受影响。
+- 地址、备注、条款等长字段继续独占整行；普通字段根据容器宽度自动切换双列或单列。
+
+## 验证结果
+
+- `npm.cmd run type:check`：通过。
+- `npm.cmd run build`：通过，Vite 生产构建包含 `@container record-form` 响应式规则。
+- `npm.cmd run resource-pages:check`：通过，详情 46 类、新建 25 类、编辑 23 类。
+- `npm.cmd run contract:check`：通过，48 个资源契约一致。
+- Biome 错误级检查：通过。
+- 浏览器回归：气站、配送点新建页卡片全宽且顶部自然排列；工作人员新建页头像摘要未变化，表单同步采用全宽布局；配送点新建页和用户编辑页均不再显示重复操作标题，用户详情页标题、说明及编辑入口保持原状；控制台无警告或错误；未执行保存操作。
+
+## 风险评估
+
+- 本次仅修改平台总后台 5173 的共享新建、编辑布局，不改变字段、校验、接口、数据库或详情页。
+- 容器查询依赖现代浏览器；当前项目运行环境和生产构建均支持该 CSS 能力。
+- 气站后台 5175、配送点后台 5176 和树形资源页面保持原状。
--- a/docs/操作日志_标准资源详情页布局优化_20260811.md
+++ b/docs/操作日志_标准资源详情页布局优化_20260811.md
@@ -0,0 +1,51 @@
+# 标准资源详情页布局优化操作日志
+
+操作时间：2026-08-11 00:40:15  
+操作类型：修改  
+影响模块：平台总后台标准资源详情页
+
+## 操作前状态
+
+- 详情页同时显示“列表 / 详情”面包屑、操作大标题和说明文字，信息表达重复。
+- 页面网格未限制纵向内容对齐，内容较少时标题区和多张卡片会被剩余视口高度拉伸，产生大块空白。
+- 未开通钱包使用大尺寸空状态，占据过多纵向空间。
+- 基本信息、钱包和状态管理卡片的标题高度与内容内边距缺少统一约束。
+
+## 具体操作
+
+- 修改 `frontend/platform_admin/src/views/resource/ResourceRecordPage.vue`：
+  - 删除所有标准详情页重复的操作大标题和说明文字。
+  - 保留面包屑、编辑、返回、气站启停和资源业务动作。
+  - 移除不再使用的标题计算与说明文字依赖。
+- 修改 `frontend/platform_admin/src/api/resource-display.ts`：删除已无调用方的页面说明文字函数，保留模式名称和错误提示格式化能力。
+- 修改 `frontend/platform_admin/src/views/resource/ResourceRecordPage.less`：
+  - 页面网格统一采用顶部自然对齐和 `12px` 间距。
+  - 统一业务操作、状态管理卡片的标题高度和内容内边距。
+- 修改 `frontend/platform_admin/src/views/resource/ResourceDetailContent.vue`：
+  - 详情卡片统一为紧凑标题和内容间距。
+  - 保留大屏三列、中屏两列、小屏单列的响应式信息布局。
+- 修改 `frontend/platform_admin/src/views/resource/ResourceWalletSummary.vue`：
+  - 未开通钱包改为小图标和单行提示。
+  - 保留已开通钱包摘要及详情入口。
+
+## 操作后状态
+
+- 详情页顶部只保留导航和操作，页面层级与新建、编辑页一致。
+- 基本信息、钱包、状态管理和业务操作卡片均按内容自然高度紧凑排列。
+- 钱包和气站状态能力不变，仅调整展示密度。
+
+## 验证结果
+
+- `npm.cmd run type:check`：通过。
+- `npm.cmd run build`：通过，Vite 生产构建完成。
+- `npm.cmd run resource-pages:check`：通过，详情 46 类、新建 25 类、编辑 23 类。
+- `npm.cmd run contract:check`：通过，48 个资源契约一致。
+- 浏览器回归：截图对应气站详情不再显示重复标题，页面网格为顶部自然对齐；基本信息、未开通钱包、状态管理卡片按内容高度排列且间距为 `12px`。
+- 已开通钱包账户详情继续显示钱包标识、余额、可提现余额、状态和详情入口。
+- 响应式验证：`1440px` 三列、`1000px` 两列、`700px` 单列；浏览器控制台无警告或错误；未执行编辑、启停或保存操作。
+
+## 风险评估
+
+- 本次只修改平台总后台 5173 的标准详情页布局，不改变接口、数据库、权限、状态流转或表单保存逻辑。
+- 聚合子表、账户摘要、钱包详情入口和资源专属业务动作继续使用原组件和事件。
+- 气站后台 5175、配送点后台 5176 和树形资源页面保持原状。
--- a/docs/项目文档_标准资源全页管理_v1.0.md
+++ b/docs/项目文档_标准资源全页管理_v1.0.md
@@ -0,0 +1,140 @@
+# 标准资源全页管理项目文档 v1.0
+
+## 1. 项目概述
+
+- 项目名称：平台总后台标准资源全页管理。
+- 实施范围：仅端口 5173 的 `frontend/platform_admin`；气站后台、配送点后台和树形资源不在本次范围。
+- 主要功能：把标准资源的新建、详情和编辑从列表抽屉迁移为独立 URL 页面，同时保留审核、归档、重置密码和流程流转等短操作。
+- 技术栈：Vue 3、TypeScript、Vue Router、Arco Design、Less、Go、Gin、GORM。
+- 资源覆盖：48 个资源契约中，46 类标准列表资源提供详情页，25 类提供新建页，23 类提供编辑页；`ec_category`、`platform_menu` 两类树形资源保持树页面交互。
+
+## 2. 页面与路由约定
+
+标准资源路由由列表路由自动扩展，三类 URL 约定如下：
+
+```text
+列表路径/new                         # 新建页
+列表路径/:identity                   # 详情页
+列表路径/:identity/edit              # 编辑页
+```
+
+- 路由元数据使用 `resource`、`recordMode` 和 `listRouteName` 驱动共享页面。
+- 隐藏详情路由通过 `activeMenu` 保持来源菜单高亮。
+- `return_to` 只接受站内绝对路径，防止开放重定向，并支持从钱包、机构账户等关联页面返回原记录。
+- 旧的账户资料 `?mode=edit` 地址会转换到 `/edit`，保留已有书签兼容性。
+- `/staff/add` 与 `/gasorder/create` 保留原业务入口名称，但直接渲染独立新建页。
+
+## 3. 目录结构
+
+```text
+platforms/
+├── frontend/platform_admin/
+│   ├── scripts/
+│   │   ├── check-backend-contract.mjs       # 前后端资源契约检查
+│   │   └── check-resource-pages.mjs         # 独立页面覆盖与抽屉残留检查
+│   └── src/
+│       ├── api/
+│       │   ├── resource-page-rules.ts       # 新建、编辑、只读和状态限制规则
+│       │   ├── resource-navigation.ts       # 页面地址与安全返回路径
+│       │   ├── resource-display.ts          # 字段、状态、金额和日期展示
+│       │   └── resource-record-form.ts      # 表单初始化与页面校验
+│       ├── router/routes/modules/
+│       │   ├── resource-route-builder.ts    # 自动生成详情、新建和编辑路由
+│       │   ├── dashboard-route.ts           # 仪表盘路由分组
+│       │   ├── finance-route.ts             # 钱包与财务路由分组
+│       │   └── platform.ts                  # 平台业务列表路由
+│       └── views/
+│           ├── resource/                    # 共享全页详情、表单、动作和摘要组件
+│           └── shared/CrudListPage.vue      # 列表与全页跳转入口
+├── backend/api/internal/
+│   ├── logic/platform/platform/account.go   # 平台账户头像受控读取
+│   └── routers/platform.go                  # 平台账户头像路由
+└── docs/                                    # 同步需求、安全、项目与操作日志
+```
+
+## 4. 核心设计
+
+### 4.1 显式页面规则
+
+`resource-page-rules.ts` 按“资源 + 字段”声明能力，不通过字段名猜测更新权限：
+
+- `identity` 永不进入创建或更新请求。
+- 账户用户名、密码和业务创建编码按服务端 DTO 设为仅创建或只读。
+- 工作人员资质所属人员、用户地址所属用户、服务关系所属用户、检修产品等归属字段在编辑时锁定；后端协议必传时只原样回传。
+- 智能气阀归属变更使用专属业务动作并提交动作、原因和备注，不混入普通编辑。
+- 配送合同仅草稿可编辑；已完成检修只允许维护备注；系统角色和平台角色权限按当前操作者锁定。
+- 保存时只从允许更新字段构造请求，保存后重新读取详情校验服务端结果。
+
+### 4.2 详情内容
+
+- 详情页顶部只保留“列表 / 详情”面包屑、编辑和返回操作，不重复展示“详情资源名称”及说明文字。
+- 页面网格从顶部按内容自然排列，详情卡片统一使用 `12px` 间距、圆角、标题高度和内容内边距，不随剩余视口高度拉伸。
+- 普通资源使用响应式三列信息区，金额、状态、日期、布尔和关系字段统一格式化。
+- 聚合详情中的数组继续以页签和表格展示，例如合同产品、修订记录和订单轨迹。
+- 气站详情保留独立的紧凑启停区域；钱包归属资源保留钱包摘要和钱包详情入口，未开通钱包时显示单行紧凑提示。
+- 工作人员、用户和平台账户保留头像、用户名、唯一标识、创建时间的账户摘要。
+- 资源专属流程动作继续使用短模态框，危险动作显示风险提示，平台角色菜单分配保留专属适配。
+
+### 4.3 新建与编辑
+
+- 新建和编辑卡片铺满主内容区，卡片内部使用最大 `1440px` 的内容容器控制输入框行长；标题、字段和操作按钮保持同一左基线。
+- 表单根据容器实际宽度响应：内容区达到约 `900px` 时使用双列，否则切换为单列；地址、备注、条款、参数和正文等长字段独占整行。
+- 页面网格从顶部自然排列；新建、编辑页只保留“列表 / 当前操作”面包屑和右侧返回按钮，不重复展示操作大标题及说明文字；保存和取消按钮位于表单末尾，不吸附浏览器底部。
+- 账户类资源继续保留头像和身份摘要的居中结构，详情页布局不受表单优化影响。
+- 编辑页展示创建后不可修改字段，但禁用字段不会进入更新请求。
+- 必填、密码最短 6 位、关系选项和金额转换复用统一校验与负载构建逻辑。
+- 页面检测表单和头像变更；返回、取消或浏览器路由离开时均提示是否放弃未保存内容。
+- 机构“账户管理”不再打开二级模态框，而是进入带机构过滤条件的隐藏账户列表及其独立 CRUD 页面。
+
+### 4.4 安全与兼容
+
+- 详情始终调用现有受保护资源接口，不使用列表缓存绕过脱敏和对象权限。
+- 头像继续通过专用上传与受控读取接口；平台账户补充同等头像读取能力。
+- 平台账户普通编辑没有提交头像时保持原值，避免更新其他资料时意外清空头像。
+- `return_to` 拒绝协议相对地址和站外地址。
+- 附件查看未接入：现有通用响应会剥离敏感 URI，待受控下载接口完成后再扩展。
+
+## 5. 行为变化
+
+| 场景 | 变更前 | 变更后 |
+| --- | --- | --- |
+| 标准资源详情 | 列表内详情抽屉 | 独立详情 URL |
+| 标准资源新建/编辑 | 共用表单抽屉 | 独立新建/编辑 URL |
+| 账户管理 | 列表内二级模态框 | 隐藏账户列表与独立页面 |
+| 审核、启停、删除 | 模态框或确认框 | 保持不变 |
+| 树形资源 | 树页面抽屉 | 保持不变 |
+| 返回来源 | 关闭抽屉 | 安全 `return_to` 返回 |
+| 未保存修改 | 关闭即丢失 | 离开前二次确认 |
+
+## 6. 验证方法
+
+在 `frontend/platform_admin` 执行：
+
+```powershell
+npm.cmd run resource-pages:check
+npm.cmd run contract:check
+npm.cmd run build
+```
+
+在 `backend/api` 执行：
+
+```powershell
+go test ./...
+```
+
+浏览器回归至少覆盖：标准列表进入详情、详情进入编辑、新建页、只读资源 404、钱包跳转、机构账户管理、未保存取消/确认、`/staff/add` 专用入口和小屏单列布局。
+
+## 7. 维护指南
+
+- 新增资源时先维护资源契约和 `resources.ts`，再在页面规则中显式声明可编辑字段。
+- 服务端 Update DTO 变化时必须同步 `resource-page-rules.ts`，禁止直接把创建字段复用于更新。
+- 新增详情专属内容时优先扩展详情区块或动作适配器，不把长流程塞回列表。
+- 新增关联跳转时必须使用安全返回路径工具，不直接信任查询参数。
+- 新增标准资源后必须运行页面覆盖检查，保证详情、新建和编辑能力与资源模式一致。
+
+## 8. 已知边界
+
+- 气站后台 5175 和配送点后台 5176 尚未迁移。
+- 树形资源仍保留现有抽屉与确认交互。
+- 附件下载、预览和权限签名不在本次实现范围。
+- 聚合子表在本地没有完整业务样本时主要依赖结构检查和生产构建，后续应补充固定测试数据的端到端用例。