156 lines
11 KiB
Markdown
156 lines
11 KiB
Markdown
# 标准资源全页管理项目文档 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 # 独立页面覆盖与抽屉残留检查
|
||
│ │ └── 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` 执行：
|
||
|
||
```powershell
|
||
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` 执行：
|
||
|
||
```powershell
|
||
go test ./...
|
||
```
|
||
|
||
浏览器回归至少覆盖：标准列表进入详情、详情进入编辑、新建页、只读资源 404、钱包跳转、机构账户管理、未保存取消/确认、`/staff/add` 专用入口和小屏单列布局。
|
||
|
||
## 7. 维护指南
|
||
|
||
- 新增资源时先维护资源契约和 `resources.ts`，再在页面规则中显式声明可编辑字段。
|
||
- 服务端 Update DTO 变化时必须同步 `resource-page-rules.ts`，禁止直接把创建字段复用于更新。
|
||
- 新增详情专属内容时优先扩展详情区块或动作适配器，不把长流程塞回列表。
|
||
- 新增关联跳转时必须使用安全返回路径工具，不直接信任查询参数。
|
||
- 新增父子关联表单时必须显式配置 `relationLinkage`，不得按关联资源地址做全局推断；涉及强制业务规则时应同步增加后端专用校验。
|
||
- 新增标准资源后必须运行页面覆盖检查，保证详情、新建和编辑能力与资源模式一致。
|
||
|
||
## 8. 已知边界
|
||
|
||
- 气站后台 5175 和配送点后台 5176 尚未迁移。
|
||
- 树形资源仍保留现有抽屉与确认交互。
|
||
- 附件下载、预览和权限签名不在本次实现范围。
|
||
- 聚合子表在本地没有完整业务样本时主要依赖结构检查和生产构建，后续应补充固定测试数据的端到端用例。
|