标准资源全页管理项目文档 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 约定如下：

列表路径/new                         # 新建页
列表路径/:identity                   # 详情页
列表路径/:identity/edit              # 编辑页

路由元数据使用 resource、recordMode 和 listRouteName 驱动共享页面。
隐藏详情路由通过 activeMenu 保持来源菜单高亮。
return_to 只接受站内绝对路径，防止开放重定向，并支持从钱包、机构账户等关联页面返回原记录。
旧的账户资料 ?mode=edit 地址会转换到 /edit，保留已有书签兼容性。
/staff/add 与 /gasorder/create 保留原业务入口名称，但直接渲染独立新建页。

3. 目录结构

platforms/
├── frontend/platform_admin/
│   ├── scripts/
│   │   ├── check-backend-contract.mjs       # 前后端资源契约检查
│   │   ├── check-resource-pages.mjs         # 独立页面覆盖与抽屉残留检查
│   │   └── check-staff-organization-linkage.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                 # 列表与全页跳转入口
│               ├── ProtectedAvatarThumbnail.vue     # 受控头像缩略图
│               └── protected-list-avatar-loader.ts  # 懒加载、限流和当前页缓存
├── backend/api/internal/
│   ├── logic/platform/platform/account.go   # 平台账户头像受控读取
│   └── routers/platform.go                  # 平台账户头像路由
└── docs/                                    # 同步需求、安全、项目与操作日志

4. 核心设计

4.1 显式页面规则

resource-page-rules.ts 按“资源 + 字段”声明能力，不通过字段名猜测更新权限：

identity 永不进入创建或更新请求。
账户用户名、密码和业务创建编码按服务端 DTO 设为仅创建或只读。
工作人员资质所属人员、用户地址所属用户、服务关系所属用户、检修产品等归属字段在编辑时锁定；后端协议必传时只原样回传。
智能气阀归属变更使用专属业务动作并提交动作、原因和备注，不混入普通编辑。
配送合同仅草稿可编辑；已完成检修只允许维护备注；系统角色和平台角色权限按当前操作者锁定。
保存时只从允许更新字段构造请求，保存后重新读取详情校验服务端结果。

4.2 详情内容

详情页顶部只保留“列表 / 详情”面包屑、编辑和返回操作，不重复展示“详情资源名称”及说明文字。
页面网格从顶部按内容自然排列，详情卡片统一使用 12px 间距、圆角、标题高度和内容内边距，不随剩余视口高度拉伸。
普通资源使用响应式三列信息区；字段标签按文字自然宽度与值保持 12px 间距，长标签保持单行，避免短标签后留白或中文标签拆字换行；金额、状态、日期、布尔和关系字段统一格式化。
聚合详情中的数组继续以页签和表格展示，例如合同产品、修订记录和订单轨迹。
气站详情保留独立的紧凑启停区域；钱包归属资源保留钱包摘要和钱包详情入口，未开通钱包时显示单行紧凑提示。
工作人员、用户和平台账户保留头像、用户名、唯一标识、创建时间的账户摘要；气站、配送点和生产商账户仅展示紧凑文字摘要，不显示无数据能力的装饰头像。
工作人员、用户和平台账户列表将头像字段渲染为 32px 圆形缩略图。缩略图接近可视区时才通过单条受控接口读取，最多并发 6 个请求；404 使用默认头像，权限、网络或解码异常回退默认头像并提供非阻断提示。列表刷新会清除当前页缓存，离开列表会取消请求并释放 Blob URL。
资源专属流程动作继续使用短模态框，危险动作显示风险提示，平台角色菜单分配保留专属适配。

4.3 新建与编辑

新建和编辑卡片铺满主内容区，卡片内部使用最大 1440px 的内容容器控制输入框行长；标题、字段和操作按钮保持同一左基线。
表单根据容器实际宽度响应：内容区达到约 900px 时使用双列，否则切换为单列；地址、备注、条款、参数和正文等长字段独占整行。
页面网格从顶部自然排列；新建、编辑页只保留“列表 / 当前操作”面包屑和右侧返回按钮，不重复展示操作大标题及说明文字；保存和取消按钮位于表单末尾，不吸附浏览器底部。
具备受控头像接口的账户继续保留头像和身份摘要；没有头像能力的账户在新建页直接进入表单，在编辑页使用紧凑文字摘要。
编辑页继续以禁用控件展示创建后不可修改字段，不额外显示说明条、字段旁提示或禁用占位文字；禁用字段不会进入更新请求。
必填、密码最短 6 位、关系选项和金额转换复用统一校验与负载构建逻辑。
页面检测表单和头像变更；返回、取消或浏览器路由离开时均提示是否放弃未保存内容。
机构“账户管理”不再打开二级模态框，而是进入带机构过滤条件的隐藏账户列表及其独立 CRUD 页面。
工作人员表单通过字段级可选配置启用气站与配送点联动：选择气站后只查询其直属配送点，先选普通配送点时自动回填所属气站；平台主管配送点仅在气站为空时可选。
更换或清空气站时只在已确认配送点不兼容后清空当前值；关联数据加载失败会保留现值，编辑记录不在列表前 100 条时按唯一标识补载。
配送点搜索始终携带当前气站条件，并以请求版本丢弃过期响应；未配置联动的用户服务关系、合同、产品和业务动作保持原行为。

4.4 安全与兼容

详情始终调用现有受保护资源接口，不使用列表缓存绕过脱敏和对象权限。
头像继续通过专用上传与受控读取接口；平台账户补充同等头像读取能力。列表缩略图不读取或暴露通用响应中的头像 URI，只允许 staff_account、user_account、platform_account 三种已配置受控路由的资源启用。
平台账户普通编辑没有提交头像时保持原值，避免更新其他资料时意外清空头像。
气站和配送点账户的 admin 分别显示为“气站管理员”和“配送点管理员”，表单只读；历史未知编码保留并显示明确提示，不做自动权限迁移。
平台账户列表和详情使用动态平台角色名称，不直接暴露角色编码；无法匹配时显示“未知角色（原编码）”。
return_to 拒绝协议相对地址和站外地址。
附件查看未接入：现有通用响应会剥离敏感 URI，待受控下载接口完成后再扩展。

5. 行为变化

场景	变更前	变更后
标准资源详情	列表内详情抽屉	独立详情 URL
标准资源新建/编辑	共用表单抽屉	独立新建/编辑 URL
账户管理	列表内二级模态框	隐藏账户列表与独立页面
审核、启停、删除	模态框或确认框	保持不变
树形资源	树页面抽屉	保持不变
返回来源	关闭抽屉	安全 `return_to` 返回
未保存修改	关闭即丢失	离开前二次确认
账户列表头像	普通文本列固定显示“-”	当前可视记录显示受控圆形缩略图，无头像回退默认图
工作人员组织选择	气站和配送点独立选择，保存时才发现不匹配	双向联动、按气站筛选、切换时清除不兼容配送点

6. 验证方法

在 frontend/platform_admin 执行：

npm.cmd run resource-pages:check
npm.cmd run staff-organization:check
npm.cmd run account-roles:check
npm.cmd run contract:check
npm.cmd run build

在 backend/api 执行：

go test ./...

浏览器回归至少覆盖：标准列表进入详情、详情进入编辑、新建页、只读资源 404、钱包跳转、机构账户管理、未保存取消/确认、/staff/add 专用入口和小屏单列布局。

7. 维护指南

新增资源时先维护资源契约和 resources.ts，再在页面规则中显式声明可编辑字段。
服务端 Update DTO 变化时必须同步 resource-page-rules.ts，禁止直接把创建字段复用于更新。
新增详情专属内容时优先扩展详情区块或动作适配器，不把长流程塞回列表。
新增关联跳转时必须使用安全返回路径工具，不直接信任查询参数。
新增父子关联表单时必须显式配置 relationLinkage，不得按关联资源地址做全局推断；涉及强制业务规则时应同步增加后端专用校验。
新增标准资源后必须运行页面覆盖检查，保证详情、新建和编辑能力与资源模式一致。

8. 已知边界

气站后台 5175 和配送点后台 5176 尚未迁移。
树形资源仍保留现有抽屉与确认交互。
附件下载、预览和权限签名不在本次实现范围。
聚合子表在本地没有完整业务样本时主要依赖结构检查和生产构建，后续应补充固定测试数据的端到端用例。

11 KiB Raw Blame History Unescape Escape