# 服务关系管理项目文档 v1.1

## 1. 项目概述

- 项目名称：服务关系名称展示统一。
- 主要功能：服务关系在列表、详情、新建和编辑页面统一展示业务名称，并对气站、配送点、服务人员执行前后端组织一致性校验。
- 实施范围：平台总后台、气站后台、配送点后台。
- 技术栈：Vue 3、TypeScript、Arco Design。

## 2. 核心实现

三个后台的 `resources.ts` 已统一服务关系字段名称和空值语义。平台总后台是当前唯一暴露服务关系管理菜单和写接口的后台，因此新建、详情、编辑和联动交互在平台总后台实现；气站、配送点后台仅同步共享资源定义，不扩大原有权限范围。

平台总后台共享列表会补载当前页实际引用的关系记录，以业务名称渲染并保留唯一标识的悬停查看与复制能力。详情页展示业务名称和可复制标识；编辑页的用户账户以只读名称显示。

列表名称“服务关系”保持不变，四列表头统一为：

- 用户账户
- 所属气站
- 所属配送点
- 服务人员

新建和编辑页面的组织规则如下：

- 用户账户必选，编辑时不可变更。
- 气站、配送点、服务人员允许同时为空，表示“暂未分配”。
- 选择配送点后自动回填所属气站；切换气站会清理不匹配的配送点。
- 服务人员按当前气站、配送点、启用状态和业务角色精确过滤。
- 历史异常关系允许查看，但再次保存前必须修正。

接口地址、请求字段和数据库结构保持不变。工作人员列表接口新增可选组织过滤参数，旧调用不传参数时行为不变。

## 3. 目录结构

```text
frontend/
├── platform_admin/               # 平台总后台
│   └── src/views/shared/         # 通用列表与名称展示组件
├── gas_admin/                    # 气站后台
│   └── src/views/shared/         # 通用列表与名称展示组件
└── delivery_admin/               # 配送点后台
    └── src/views/shared/         # 通用列表与名称展示组件
backend/api/internal/logic/platform/
├── staff/                        # 服务人员组织范围过滤
└── user/                         # 服务关系写入一致性校验
```

## 4. 维护指南

新增类似关联名称列时，应通过字段级配置启用，不得按资源名称硬编码。新增组织关联必须同时提供前端联动和后端最终校验，不得只依赖下拉框过滤。

## 5. 验证记录

- 平台总后台：类型检查、资源页契约、组织联动契约和生产构建通过。
- 气站后台、配送点后台：类型检查及生产构建通过。
- 后端：平台工作人员与用户服务关系定向测试通过。

## 6. 风险评估

风险集中在历史异常数据：详情仍可查看，编辑保存会被严格校验阻止。未新增菜单、角色或写接口，现有权限边界不变；接口字段和数据库结构保持兼容。