platforms/docs/05-平台总后台需求-分析.md

# 平台总后台需求分析

## 1. 文档目标与范围

本文将 [平台总后台需求](05-平台总后台需求.md) 拆解为可实施的领域模型、接口边界与 Vue 管理端页面规划，作为平台总后台的产品、前端与后端共同基线。

平台总后台是全平台唯一的跨组织治理中心，管理所有可燃气体站、配送点、服务人员、用户、智能瓶阀安全事件、全局规则、资金结算和审计数据。它不替代气站、配送点、生产和 API 中心系统处理各自的日常业务，而是维护主数据、全局策略、跨组织协同和高风险审批。

本项目不维护独立数据库迁移功能。表结构由 Go 模型在应用启动时通过 GORM 自动同步；模型、接口契约和中文注释须在同一需求变更中更新。

气站与配送点邀请二维码不属于平台总后台本期功能范围；本期不规划二维码数据表、接口、菜单或页面。

### 1.1 前后端实现目录

| 范围 | 目录 / 文件 | 责任 |
| --- | --- | --- |
| 前端项目 | `frontend/platform_admin` | Vue 平台总后台，承载登录、菜单、页面、数据权限提示和 API 调用 |
| 前端页面 | `frontend/platform_admin/src/views` | 当前后台壳与页面编排；后续可按业务域拆分至 `src/views/` |
| 前端接口 | `frontend/platform_admin/src/api` | 平台总后台 HTTP 客户端、类型和登录会话处理 |
| 后端 API | `backend/api` | Go/Gin 平台总后台 API 进程 |
| 后端路由文件 | `backend/api/internal/routers/platform.go` | 唯一 HTTP 路由注册入口，注册 `/heqi/platform/v1` 前缀及认证路由组 |
| 后端业务逻辑 | `backend/api/internal/logic/platform` | 平台认证、组织、人员、用户、安全、交易、资金与审计逻辑 |
| 后端模型 | `backend/api/internal/models` | GORM 数据模型、表名、数据访问和中文模型注释 |
| 初始数据 | `backend/api/internal/initdb/platform.go` | 初始化 `root` 系统管理员角色与根账户 |

## 2. 实施原则

- 所有表均使用数据库 `id` 自增主键，作为物理主键和内部关联键。
- 所有主表额外包含 `identity` 字段，类型为 `varchar(36)`，由应用生成 UUID V7；`identity` 是对外接口、审计、跨服务关联使用的唯一业务主键，并建立唯一索引。明细表是否保留 `identity` 由是否需要对外暴露或被审计引用决定。
- 表名、Go 模型名、模型文件名使用同一单数实体词根；接口仅以 `list`、`items` 表达集合语义，不使用复数实体名。
- 平台角色权限统一使用 `platform_role` 与 `platform_role_menu_relation`；系统初始化时创建 `root` 系统管理员角色并授予全部菜单权限。
- 可燃气体站、配送点、服务人员与用户的归属、服务关系和状态变更必须留存历史快照，禁止直接覆盖历史业务归属。
- 手机号、身份证件、详细地址、精确位置、头像访问地址、支付和资质资料均属于敏感字段；列表默认脱敏，导出与精确轨迹须审批。
- 高风险安全动作、跨组织变更、组织冻结、资金动作、敏感导出实行职责分离、理由必填和审计留痕。
- 外部支付、地图、短信、对象存储、IoT、生产系统与 API 网关均通过适配层接入；开发阶段可使用 Mock 边界。


## 4. 数据模型规划

### 4.1 公共字段与关联规则

所有表统一包含 `id bigint` 自增物理主键、`created_at`、`updated_at`。主表统一增加 `identity varchar(36)`，由应用生成 UUID V7 并设置唯一索引，同时包含 `status`、`version`。跨服务、审计日志和 HTTP 路由只传递 `identity`，数据库内部关联可使用 `<实体词根>_id`；业务编码另设唯一字段，例如 `gas_code`、`delivery_code`、`order_code`。

主表的 Go 模型应同时声明 `ID uint64`（自增主键）和 `Identity string`（UUID V7 业务主键）；`identity` 不由数据库默认生成，必须在应用层创建记录前写入。

### 4.2 身份、组织与服务关系

| 实体 | 表 / 模型 / 文件 | 关键字段 | 说明 |
| --- | --- | --- | --- |
| 平台账户 | `platfrom_account` / `PlatfromAccount` / `platfrom_account.go` | `id`、`identity`、`username`、`display_name`、`avatar`、`password_hash`、`platform_role_code`、`phone` | 平台后台登录账户；头像保存受控资源地址 |
| 平台角色 | `platform_role` / `PlatformRole` / `platform_role.go` | `id`、`identity`、`role_code`、`name`、`data_scope`、`is_system` | 角色定义；初始化内置 `root` 系统管理员角色 |
| 气站基础资料 | `gas_basic` / `GasBasic` / `gas_basic.go` | `id`、`identity`、`code`、`name`、`credit_code`、`principal`、`address`、`longitude`、`latitude` | 气站主体主档案 |
| 气站账户 | `gas_account` / `GasAccount` / `gas_account.go` | `id`、`identity`、`gas_basic_id`、`username`、`display_name`、`password_hash`、`role_code` | 气站身份账户 |
| 配送点资料 | `delivery_basic` / `DeliveryBasic` / `delivery_basic.go` | `id`、`identity`、`delivery_code`、`gas_basic_id`、`name`、`principal`、`address` | 末端配送组织单元；可归属平台或气站 |
| 配送点账户 | `delivery_account` / `DeliveryAccount` / `delivery_account.go` | `id`、`identity`、`delivery_basic_id`、`username`、`display_name`、`password_hash`、`role_code` | 配送点身份账户；仅能访问本点数据 |
| 服务人员账户 | `staff_account` / `StaffAccount` / `staff_account.go` | `id`、`identity`、`staff_id`、`username`、`password_hash`、`gas_basic_id`、`delivery_basic_id`、`work_status` | 安装维修、安检、配送人员账号及资料 |
| 人员资质 | `staff_credential` / `StaffCredential` / `staff_credential.go` | `id`、`identity`、`staff_id`、`credential_type`、`credential_no`、`expired_at` | 培训、证照、保险与技能等级 |
| 业主客户账户 | `user_account` / `UserAccount` / `user_account.go` | `id`、`identity`、`user_id`、`username`、`password_hash`、`status` | 用户端登录账户 |
| 用户地址 | `user_address` / `UserAddress` / `user_address.go` | `id`、`identity`、`user_id`、`address`、`longitude`、`latitude`、`is_default` | 地址历史和订单快照来源 |
| 用户服务关系 | `user_service_relation` / `UserServiceRelation` / `user_service_relation.go` | `id`、`identity`、`user_id`、`gas_basic_id`、`delivery_basic_id`、`staff_id` | 用户与气站/配送点的服务归属 |

### 4.3 设备与安全

| 实体 | 表 / 模型 / 文件 | 关键字段 | 说明 |
| --- | --- | --- | --- |
| 智能瓶阀 | `dev_smart_cylinder_valve` / `DevSmartCylinderValve` / `dev_smart_cylinder_valve.go` | `device_no`、`model`、`online_status`、`owner_identity` | 智能瓶阀全生命周期档案 |
| 设备绑定 | `dev_device_binding` / `DevDeviceBinding` / `dev_device_binding.go` | `id`、`identity`、`smart_cylinder_valve_id`、`user_id`、`effective_at`、`expired_at` | 用户/家庭与智能瓶阀授权关系 |
| 遥测 | `dev_telemetry` / `DevTelemetry` / `dev_telemetry.go` | `smart_cylinder_valve_identity`、`reported_at`、`payload`、`quality_flag` | 遥测摘要与质量标记 |
| 安全规则 | `saf_rule` / `SafRule` / `saf_rule.go` | `rule_code`、`version_no`、`threshold`、`action`、`gray_scope` | 告警、自动关阀、静默和灰度规则 |
| 安全事件 | `saf_event` / `SafEvent` / `saf_event.go` | `event_code`、`level`、`smart_cylinder_valve_identity`、`status`、`sla_at` | 告警、安检和人工发现事件统一入口 |
| 安全处置 | `saf_event_disposal` / `SafEventDisposal` / `saf_event_disposal.go` | `saf_event_identity`、`action`、`reason`、`operator_identity` | 派发、升级、关阀、复核和结案记录 |
| 安检记录 | `saf_inspection` / `SafInspection` / `saf_inspection.go` | `id`、`identity`、`user_id`、`staff_id`、`result`、`evidence_uri` | 安检、整改和复检证据 |

### 4.4 电商、订单与配送轨迹

| 实体 | 表 / 模型 / 文件 | 关键字段 | 说明 |
| --- | --- | --- | --- |
| 商品分类 | `ec_category` / `EcCategory` / `ec_category.go` | `id`、`identity`、`parent_id`、`name`、`sort_no`、`status` | 可燃气体商品及服务分类树 |
| 商品 | `ec_product` / `EcProduct` / `ec_product.go` | `id`、`identity`、`ec_category_id`、`product_code`、`name`、`price_amount`、`stock_quantity`、`status` | 可燃气体商品与服务主数据 |
| 商品属性 | `ec_product_attribute` / `EcProductAttribute` / `ec_product_attribute.go` | `id`、`identity`、`ec_product_id`、`name`、`value`、`sort_no` | 商品属性子表，例如规格、重量和服务时长 |
| 商品图片 | `ec_product_image` / `EcProductImage` / `ec_product_image.go` | `id`、`identity`、`ec_product_id`、`image_uri`、`sort_no`、`is_cover` | 商品图片子表，保存受控资源地址 |
| 购物车 | `ec_cart` / `EcCart` / `ec_cart.go` | `id`、`identity`、`user_id`、`ec_product_id`、`quantity`、`selected` | 用户购物车明细 |
| 订单 | `ec_order` / `EcOrder` / `ec_order.go` | `id`、`identity`、`order_no`、`user_id`、`gas_station_id`、`delivery_point_id`、`total_amount`、`status` | 电商订单主表及组织快照 |
| 订单项 | `ec_order_item` / `EcOrderItem` / `ec_order_item.go` | `id`、`identity`、`ec_order_id`、`ec_product_id`、`product_snapshot`、`quantity`、`sale_amount` | 订单商品快照和金额明细 |
| 商品评论 | `ec_review` / `EcReview` / `ec_review.go` | `id`、`identity`、`ec_order_id`、`ec_product_id`、`user_id`、`score`、`content`、`status` | 用户评价、审核和隐藏状态 |
| 配送任务 | `delivery_task` / `DeliveryTask` / `delivery_task.go` | `id`、`identity`、`ec_order_id`、`staff_id`、`delivery_point_id`、`status` | 配送履约任务 |
| 配送轨迹 | `delivery_track` / `DeliveryTrack` / `delivery_track.go` | `id`、`identity`、`delivery_task_id`、`status`、`started_at`、`completed_at` | 用户可见简化配送轨迹 |
| 配送轨迹点 | `delivery_track_point` / `DeliveryTrackPoint` / `delivery_track_point.go` | `id`、`identity`、`delivery_track_id`、`point_type`、`occurred_at`、`longitude`、`latitude` | 精确位置与任务节点；访问受授权控制 |

### 4.5 财务、钱包与内容

| 实体 | 表 / 模型 / 文件 | 关键字段 | 说明 |
| --- | --- | --- | --- |
| 支付记录 | `fin_payment` / `FinPayment` / `fin_payment.go` | `id`、`identity`、`ec_order_id`、`channel`、`amount`、`status`、`paid_at` | 支付、退款和外部渠道流水关联 |
| 财务结算 | `fin_settlement` / `FinSettlement` / `fin_settlement.go` | `id`、`identity`、`settlement_no`、`subject_type`、`subject_id`、`period_start`、`period_end`、`status` | 气站、配送点、服务人员结算单 |
| 财务对账 | `fin_reconciliation` / `FinReconciliation` / `fin_reconciliation.go` | `id`、`identity`、`channel`、`bill_date`、`difference_amount`、`status` | 支付渠道对账及差异处理 |
| 钱包 | `wallet` / `Wallet` / `wallet.go` | `id`、`identity`、`owner_type`、`owner_id`、`balance_amount`、`frozen_amount`、`status` | 用户、组织和服务人员的钱包余额账户 |
| 钱包流水 | `wallet_ledger` / `WalletLedger` / `wallet_ledger.go` | `id`、`identity`、`wallet_id`、`amount`、`direction`、`balance_after`、`reference_identity` | 钱包唯一资金事实流水 |
| 钱包充值 | `wallet_recharge` / `WalletRecharge` / `wallet_recharge.go` | `id`、`identity`、`wallet_id`、`amount`、`channel`、`status` | 钱包充值申请和支付结果 |
| 钱包提现 | `wallet_withdrawal` / `WalletWithdrawal` / `wallet_withdrawal.go` | `id`、`identity`、`wallet_id`、`amount`、`bank_account_masked`、`status` | 提现申请、审核与付款凭证 |
| 内容 | `cms_content` / `CmsContent` / `cms_content.go` | `content_type`、`title`、`version_no`、`publish_status` | 公告、协议、安全宣教内容 |
| 客服工单 | `cs_ticket` / `CsTicket` / `cs_ticket.go` | `id`、`identity`、`ticket_no`、`user_id`、`category`、`status`、`priority` | 咨询、投诉、回访与升级 |

## 5. API 路由规则

### 5.1 通用约定

- 基础路径：`/heqi/platform/v1`；本节列出的路由均为该前缀后的相对路径。
- 资源路径采用模块名与单数蛇形实体名：`/{domain}/{resource}`，例如 `/gas/gas_station`。
- 平台总后台接口以 CRUD 为主：`GET` 列表/详情、`POST` 创建、`PUT /:identity` 更新、`PATCH /:identity/status` 启用/停用、`DELETE /:identity` 逻辑删除或归档；主数据不做物理删除。
- 分页参数统一为 `page`、`size`；筛选参数使用明确字段名；列表返回 `{ total, list }`。
- 批量启停、导入、导出等扩展动作使用明确动作路径，例如 `/:identity/status`、`/import`、`/export`；请求必须携带 `reason`（如适用）。
- 认证接口以 `/auth` 开头；除登录和健康检查外，均要求原始 JWT `Authorization` 请求头。
- 请求和响应字段使用 `snake_case`；时间使用 ISO 8601；金额使用最小货币单位整数；位置字段仅在获授权接口中返回。

### 5.2 认证与平台账户

| 方法 | 路由 | 作用 |
| --- | --- | --- |
| `POST` | `/auth/login` | 平台账户登录并签发 JWT |
| `GET` | `/auth/profile` | 当前登录账户资料，含头像 |
| `PUT` | `/auth/password` | 修改当前账户密码 |
| `GET` | `/platform/platfrom_account` | 平台账户分页列表 |
| `POST` | `/platform/platfrom_account` | 创建平台账户 |
| `GET` | `/platform/platfrom_account/:identity` | 平台账户详情 |
| `PUT` | `/platform/platfrom_account/:identity` | 更新名称、头像、角色、手机号 |
| `PATCH` | `/platform/platfrom_account/:identity/status` | 启用、冻结、归档账户 |
| `GET/POST` | `/platform/platform_role` | 角色列表、创建角色；初始化内置 `root` 系统管理员角色 |
| `PUT` | `/platform/platform_role/:identity/menu` | 覆盖角色菜单与按钮权限集合 |
| `GET` | `/platform/platform_menu` | 菜单树和当前账户可见菜单 |

### 5.3 组织、人员和用户

| 方法 | 路由 | 作用 |
| --- | --- | --- |
| `GET/POST` | `/gas/gas_station` | 查询、创建可燃气体站 |
| `GET/PUT/DELETE` | `/gas/gas_station/:identity` | 气站详情、更新、逻辑删除/归档 |
| `PATCH` | `/gas/gas_station/:identity/status` | 气站启用、停用、冻结 |
| `GET/POST` | `/gas/gas_account` | 气站账户查询、创建和授权 |
| `GET/POST` | `/delivery/delivery_point` | 查询、创建配送点 |
| `GET/PUT/DELETE` | `/delivery/delivery_point/:identity` | 配送点详情、更新、逻辑删除/归档 |
| `PATCH` | `/delivery/delivery_point/:identity/status` | 配送点启用、停用、冻结 |
| `GET/POST` | `/delivery/delivery_account` | 配送点账户查询、创建和授权 |
| `GET/POST` | `/staff/account` | 服务人员查询、建档或导入 |
| `GET/PUT/DELETE` | `/staff/:identity` | 服务人员详情、更新、逻辑删除/归档 |
| `GET/POST/PUT/DELETE` | `/staff/credential` | 服务人员资质 CRUD |
| `GET/POST` | `/user/account` | 业主客户查询、创建 |
| `GET/PUT/DELETE` | `/user/:identity` | 用户详情、更新、逻辑删除/归档 |
| `PATCH` | `/user/:identity/status` | 冻结登录、限制下单或设备控制 |
| `POST` | `/user/service_relation` | 建立或变更用户服务关系 |

### 5.4 智能瓶阀安全、订单与配送轨迹

| 方法 | 路由 | 作用 |
| --- | --- | --- |
| `GET/POST` | `/device/dev_smart_cylinder_valve` | 智能瓶阀查询、建档 |
| `GET/PUT/DELETE` | `/device/dev_smart_cylinder_valve/:identity` | 智能瓶阀详情、更新、逻辑删除/归档 |
| `GET/POST` | `/safety/saf_event` | 安全事件查询、创建 |
| `GET/PUT/DELETE` | `/safety/saf_event/:identity` | 安全事件详情、更新、逻辑删除/归档 |
| `GET/POST` | `/safety/saf_rule` | 安全规则 CRUD 的列表与创建 |
| `GET/PUT/DELETE` | `/safety/saf_rule/:identity` | 安全规则详情、更新、逻辑删除 |
| `GET/POST` | `/ec/ec_order` | 电商订单查询、创建 |
| `GET/PUT/DELETE` | `/ec/ec_order/:identity` | 电商订单详情、更新、逻辑删除/归档 |
| `GET/POST` | `/delivery/delivery_track` | 配送轨迹查询、创建 |
| `GET/PUT/DELETE` | `/delivery/delivery_track/:identity` | 配送轨迹详情、更新、逻辑删除/归档 |

### 5.5 电商、财务、钱包、统计报表、内容与审计

| 方法 | 路由 | 作用 |
| --- | --- | --- |
| `GET/POST` | `/ec/ec_category` | 商品分类查询、创建 |
| `GET/PUT/DELETE` | `/ec/ec_category/:identity` | 商品分类详情、更新、逻辑删除 |
| `GET/POST` | `/ec/ec_product` | 商品查询、创建 |
| `GET/PUT/DELETE` | `/ec/ec_product/:identity` | 商品详情、更新、逻辑删除 |
| `GET/POST/PUT/DELETE` | `/ec/ec_product_attribute` | 商品属性子表 CRUD |
| `GET/POST/PUT/DELETE` | `/ec/ec_product_image` | 商品图片子表 CRUD |
| `GET/POST/PUT/DELETE` | `/ec/ec_cart` | 购物车 CRUD |
| `GET/POST/PUT/DELETE` | `/ec/ec_review` | 商品评论 CRUD |
| `GET/POST` | `/finance/fin_payment` | 支付记录查询、创建 |
| `GET/PUT/DELETE` | `/finance/fin_payment/:identity` | 支付记录详情、更新、逻辑删除 |
| `GET/POST/PUT/DELETE` | `/finance/fin_settlement` | 财务结算 CRUD |
| `GET/POST/PUT/DELETE` | `/finance/fin_reconciliation` | 财务对账 CRUD |
| `GET` | `/wallet/wallet` | 钱包列表查询 |
| `GET` | `/wallet/wallet/:identity` | 钱包详情查看 |
| `GET` | `/wallet/wallet_ledger` | 钱包流水列表查询 |
| `GET` | `/wallet/wallet_ledger/:identity` | 钱包流水详情查看 |
| `GET` | `/wallet/wallet_recharge` | 钱包充值记录列表查询 |
| `GET` | `/wallet/wallet_withdrawal` | 钱包提现记录列表查询 |
| `GET/POST/PUT/DELETE` | `/content/cms_content` | 内容 CRUD |
| `GET/POST/PUT/DELETE` | `/customer_service/cs_ticket` | 客服工单 CRUD |

## 6. 前端页面规划

### 6.1 全局框架

前端项目位于 `frontend/platform_admin`，使用 Vue 3、TypeScript 和 Vite。页面采用“应用壳 + 一级侧边栏 + 二级菜单 + 列表工作区 + 详情抽屉/编辑弹窗”的后台信息架构；每个实体页面围绕其模型的列表、详情、新增、编辑、状态和逻辑删除组织。

- 路由配置文件：`frontend/platform_admin/src/router/routes.ts`；菜单配置由 `platform_menu` 驱动并映射到受控本地路由。
- 页面根目录：`frontend/platform_admin/src/views`；按一级菜单拆分目录，禁止将所有页面堆放在 `App.vue`。
- 共享组件目录：`frontend/platform_admin/src/components`；提供 `DataTable`、`FilterBar`、`DetailDrawer`、`FormDrawer`、`StatusTag`、`ConfirmDialog` 和 `EmptyState`。
- 图标库：`lucide-vue-next`；菜单仅保存图标名称，页面通过统一 `IconRenderer` 映射，避免散落硬编码 SVG。

| 一级导航 | 页面 | 核心内容 |
| --- | --- | --- |
| 登录 | 登录页 | 账号密码登录、错误提示、服务条款入口 |
| 工作台 | 运营总览 | 气站、配送点、人员、用户、智能瓶阀、安全事件、订单、结算核心指标；异常待办与地图概览 |
| 组织权限 | 可燃气体站列表、站点详情、配送点列表、配送点详情、服务区域、角色权限 | 主档案、审批、归属、服务能力、组织 KPI、账号与数据范围 |
| 人员用户 | 服务人员列表、人员详情、资质审核、调配中心、用户列表、用户 360 | 人员生命周期、任务绩效、资质预警、用户设备/订单/安全/投诉概览 |
| 安全设备 | 智能瓶阀列表、设备详情、安全事件中心、安全规则、安检整改 | 实时状态、遥测摘要、告警处置、规则版本、证据和复核 |
| 电商管理 | 分类管理、商品管理、商品属性、商品图片、购物车、订单、评论 | `ec` 电商实体 CRUD、商品上下架、订单与评论管理 |
| 财务钱包 | 支付记录、财务结算、财务对账、钱包、钱包流水、充值、提现 | `fin` 财务实体 CRUD；钱包、流水、充值和提现记录仅列表与详情查看 |
| 统计报表 | 报表列表、报表明细、指标看板 | 报表生成记录、维度明细和聚合指标只读查询 |
| 内容客服 | 内容中心、消息模板、客服工单 | 草稿/审核/发布/撤回、触达渠道、工单 SLA 与满意度 |
| 配送轨迹 | 配送任务、配送轨迹、轨迹点 | 配送履约记录、轨迹节点和异常信息 CRUD |
| 全局运营 | 指标中心、地图态势、运营规则、消息任务 | 跨组织下钻、阈值预警、规则灰度、触达效果 |
| 审计合规 | 审批中心、操作审计、导出审计、合规工单 | 审批队列、前后值追溯、敏感访问与留存处置 |

### 6.2 前端目录、菜单与页面映射（以本表为准）

页面目录统一位于 `frontend/platform_admin/src/views`；`ListPage.vue` 负责筛选、分页和表格，`DetailDrawer.vue` 负责查看详情，`FormDrawer.vue` 负责创建与编辑。钱包、流水和报表目录不创建 `FormDrawer.vue`，只保留列表和详情组件。图标使用 `lucide-vue-next`。

| 一级菜单 / 图标 | 二级菜单 / 图标 | 路由 | 目录名 | 文件名 | 核心内容 |
| --- | --- | --- | --- | --- | --- |
| 工作台 `LayoutDashboard` | 运营概览 `ChartNoAxesCombined` | `/dashboard` | `views/dashboard` | `DashboardPage.vue` | 气站、配送点、人员、用户、智能瓶阀、电商订单、财务和安全指标卡片 |
| 气站管理 `Fuel` | 气站管理 `Building2` | `/gas/basic` | `views/gas/basic` | `ListPage.vue` | `gas_basic` CRUD、状态和基础档案 |
| 气站管理 `Fuel` | 气站账户 `UserCog` | `/gas/account` | `views/gas/account` | `ListPage.vue` | `gas_account` CRUD、账号状态和角色 |
| 配送管理 `Truck` | 配送点管理 `Warehouse` | `/delivery/basic` | `views/delivery/basic` | `ListPage.vue` | `delivery_basic` CRUD、归属气站、负责人和状态 |
| 配送管理 `Truck` | 配送点账户 `UserRoundCog` | `/delivery/account` | `views/delivery/account` | `ListPage.vue` | `delivery_account` CRUD、登录账号和权限 |
| 配送管理 `Truck` | 配送任务 `ListTodo` | `/delivery/task` | `views/delivery/task` | `ListPage.vue` | `delivery_task` CRUD、订单、配送员、配送点和状态 |
| 配送管理 `Truck` | 配送轨迹 `Route` | `/delivery/track` | `views/delivery/track` | `ListPage.vue` | `delivery_track`、`delivery_track_point` CRUD 和轨迹时间线 |
| 服务人员 `HardHat` | 人员档案 `Contact` | `/staff/list` | `views/staff/list` | `ListPage.vue` | `staff` CRUD、头像、组织归属、岗位状态 |
| 服务人员 `HardHat` | 人员账户 `Smartphone` | `/staff/account` | `views/staff/account` | `ListPage.vue` | `staff_account` CRUD、App 账号和登录状态 |
| 服务人员 `HardHat` | 人员资质 `FileBadge` | `/staff/credential` | `views/staff/credential` | `ListPage.vue` | `staff_credential` CRUD、证照、有效期和附件 |
| 业主客户 `UsersRound` | 客户档案 `UserRound` | `/user/list` | `views/user/list` | `ListPage.vue` | `user` CRUD、实名状态和账户状态 |
| 业主客户 `UsersRound` | 客户账户 `KeyRound` | `/user/account` | `views/user/account` | `ListPage.vue` | `user_account` CRUD、登录账号和状态 |
| 业主客户 `UsersRound` | 客户地址 `MapPinHouse` | `/user/address` | `views/user/address` | `ListPage.vue` | `user_address` CRUD、默认地址和位置 |
| 业主客户 `UsersRound` | 服务关系 `GitFork` | `/user/service-relation` | `views/user/service-relation` | `ListPage.vue` | `user_service_relation` CRUD、气站/配送点归属 |
| 设备管理 `ShieldAlert` | 智能瓶阀 `Gauge` | `/device/valve` | `views/device/valve` | `ListPage.vue` | `dev_smart_cylinder_valve` CRUD、型号、在线状态、归属 |
| 设备管理 `ShieldAlert` | 设备绑定 `Link2` | `/device/binding` | `views/device/binding` | `ListPage.vue` | `dev_device_binding` CRUD、用户与智能瓶阀绑定 |
| 设备管理 `ShieldAlert` | 安全规则 `Siren` | `/safety/rule` | `views/safety/rule` | `ListPage.vue` | `saf_rule` CRUD、阈值、规则版本和状态 |
| 设备管理 `ShieldAlert` | 安全事件 `TriangleAlert` | `/safety/event` | `views/safety/event` | `ListPage.vue` | `saf_event` CRUD、等级、设备、用户和状态 |
| 设备管理 `ShieldAlert` | 安检记录 `ClipboardCheck` | `/safety/inspection` | `views/safety/inspection` | `ListPage.vue` | `saf_inspection` CRUD、人员、结果和证据 |
| 电商管理 `ShoppingBag` | 商品分类 `FolderTree` | `/ec/category` | `views/ec/category` | `TreePage.vue` | `ec_category` 分类树 CRUD、排序和状态 |
| 电商管理 `ShoppingBag` | 商品管理 `PackageSearch` | `/ec/product` | `views/ec/product` | `ListPage.vue` | `ec_product` CRUD、分类、价格、库存和状态 |
| 电商管理 `ShoppingBag` | 商品属性 `Tags` | `/ec/product-attribute` | `views/ec/product-attribute` | `ListPage.vue` | `ec_product_attribute` CRUD、商品规格与属性 |
| 电商管理 `ShoppingBag` | 商品图片 `Image` | `/ec/product-image` | `views/ec/product-image` | `ListPage.vue` | `ec_product_image` CRUD、封面、排序和预览 |
| 电商管理 `ShoppingBag` | 购物车 `ShoppingCart` | `/ec/cart` | `views/ec/cart` | `ListPage.vue` | `ec_cart` CRUD、用户、商品、数量和选中状态 |
| 电商管理 `ShoppingBag` | 电商订单 `ReceiptText` | `/ec/order` | `views/ec/order` | `ListPage.vue` | `ec_order`、`ec_order_item` CRUD、金额和履约状态 |
| 电商管理 `ShoppingBag` | 商品评论 `MessageSquareText` | `/ec/review` | `views/ec/review` | `ListPage.vue` | `ec_review` CRUD、评分、评论内容和显示状态 |
| 财务管理 `Landmark` | 支付记录 `CreditCard` | `/finance/payment` | `views/finance/payment` | `ListPage.vue` | `fin_payment` CRUD、订单、渠道、金额和支付状态 |
| 财务管理 `Landmark` | 财务结算 `Scale` | `/finance/settlement` | `views/finance/settlement` | `ListPage.vue` | `fin_settlement` CRUD、结算主体、周期和金额 |
| 财务管理 `Landmark` | 财务对账 `BookOpenCheck` | `/finance/reconciliation` | `views/finance/reconciliation` | `ListPage.vue` | `fin_reconciliation` CRUD、渠道账单和差异 |
| 钱包中心 `WalletCards` | 钱包列表 `Wallet` | `/wallet/list` | `views/wallet/list` | `ListPage.vue` | `wallet` 只读列表、余额、冻结金额和状态 |
| 钱包中心 `WalletCards` | 钱包流水 `ListOrdered` | `/wallet/ledger` | `views/wallet/ledger` | `ListPage.vue` | `wallet_ledger` 只读列表、方向、金额和余额快照 |
| 钱包中心 `WalletCards` | 充值记录 `CirclePlus` | `/wallet/recharge` | `views/wallet/recharge` | `ListPage.vue` | `wallet_recharge` 只读列表和详情 |
| 钱包中心 `WalletCards` | 提现记录 `CircleMinus` | `/wallet/withdrawal` | `views/wallet/withdrawal` | `ListPage.vue` | `wallet_withdrawal` 只读列表和详情 |
| 内容客服 `MessagesSquare` | 内容管理 `FileText` | `/content/cms-content` | `views/content/cms_content` | `ListPage.vue` | `cms_content` CRUD、类型、标题和发布状态 |
| 内容客服 `MessagesSquare` | 客服工单 `Headset` | `/content/ticket` | `views/content/ticket` | `ListPage.vue` | `cs_ticket` CRUD、客户、分类、优先级和状态 |
| 平台配置 `ShieldCheck` | 平台账户 `ContactRound` | `/platform/account` | `views/platform/account` | `ListPage.vue` | `platfrom_account` 列表、头像、角色、状态；新增/编辑抽屉 |
| 平台配置 `ShieldCheck` | 角色管理 `BadgeCheck` | `/platform/role` | `views/platform/role` | `ListPage.vue` | `platform_role` CRUD，`root` 角色只读保护 |
| 平台配置 `ShieldCheck` | 菜单管理 `MenuSquare` | `/platform/menu` | `views/platform/menu` | `TreePage.vue` | `platform_menu` 树、图标、路由、排序和角色菜单授权 |

### 6.3 页面类型与组件规范

| 页面类型 | 适用实体 | 目录内文件 | 前端职责 |
| --- | --- | --- | --- |
| 标准 CRUD 列表页 | 气站、配送点、人员、用户、电商、财务、内容客服 | `ListPage.vue`、`DetailDrawer.vue`、`FormDrawer.vue` | 筛选、分页、详情、新增、编辑、逻辑删除和状态更新 |
| 树形管理页 | `platform_menu`、`ec_category` | `TreePage.vue`、`FormDrawer.vue` | 层级展示、拖拽排序、节点新增、编辑和逻辑删除 |
| 只读列表页 | 钱包、流水、充值、提现、报表、审计 | `ListPage.vue`、`DetailDrawer.vue` | 条件筛选、分页、详情、复制标识和受控导出；无新增/编辑/删除按钮 |
| 指标看板页 | 工作台、报表指标快照 | `DashboardPage.vue`、`MetricCard.vue`、`TrendChart.vue` | 指标卡、趋势图、筛选条件和下钻链接 |

### 6.4 重点页面规格

| 页面 | 查询区 | 列表/主视图 | 关键动作 |
| --- | --- | --- | --- |
| 可燃气体站列表 | 区域、状态、资质、风险、创建时间 | 站点编码、名称、负责人、服务能力、订单/安全/结算摘要 | 新建、导入、审核、启停、合并、归档 |
| 气站详情 | 固定站点上下文 | 基础档案、服务能力、配送点、人员、用户、设备、财务、资质、审计标签页 | 编辑草稿、提交审核、冻结、查看下钻 |
| 配送点列表 | 归属气站、区域、状态、负载 | 编码、负责人、配送能力、在岗人数、准时率、库存摘要 | 创建、审核、归属变更、启停 |
| 服务人员列表 | 角色、组织、资质、在岗、区域 | 姓名、头像、角色、资质有效期、当前负载、评分、状态 | 导入、审核、授予角色、调配、冻结 |
| 用户 360 | 用户编号/手机号/订单号 | 身份、地址、智能瓶阀、订单、支付摘要、安全事件、工单和服务关系时间线 | 合规处置发起、查看最小必要信息 |
| 安全事件中心 | 等级、状态、设备、区域、SLA | 告警队列、地图、处置时钟和责任方 | 派发、升级、关阀、复核、结案 |
| 商品分类与商品 | 分类、状态、商品编码、创建时间 | 分类树、商品名称、封面、价格、库存、上下架状态 | 新增、编辑、逻辑删除、维护属性和图片 |
| 购物车、订单与评论 | 用户、商品、订单状态、评论状态、日期 | 购物车商品项、订单金额、履约状态、评分和评论内容 | 新增、编辑、逻辑删除、状态更新 |
| 配送轨迹 | 订单、配送员、配送点、日期、异常类型 | 时间线与地图；默认隐藏精确坐标 | 查看简化轨迹、申请精确回放、导出审批 |
| 财务与钱包 | 主体、周期、状态、金额区间、渠道 | 支付、结算、对账、钱包余额、流水、充值和提现 | 财务记录可维护；钱包、流水、充值和提现记录仅列表与详情查看 |
| 统计报表 | 报表类型、统计周期、组织、状态 | 报表编号、生成时间、维度明细和指标值 | 列表筛选、查看报表及明细，不提供新增、编辑、删除 |
| 审计中心 | 操作人、对象、动作、时间、结果 | 不可变日志、前后值摘要、审批关联、导出记录 | 检索、筛选、合规导出申请 |

### 6.5 页面交互规则

- 列表页默认服务端分页；筛选条件可保存为个人视图，不影响他人。
- 新建、编辑和逻辑删除使用统一表单与二次确认；页面主要完成列表查询、详情、新增、编辑、状态更新和逻辑删除。
- 状态动作必须展示影响范围提示；安全、支付与敏感导出等高风险能力在后续迭代中再增加审批与复核流程。
- 详情抽屉展示主字段、创建/更新时间和关联数据；复杂审批时间线不作为本阶段 CRUD 的必做能力。
- 头像为空时显示名称首字或默认图形；头像 URL 失效时回退为默认图形，不暴露对象存储签名。

## 7. 关键流程与验收口径

### 7.1 组织准入与跨组织变更

1. 运营创建草稿或批量导入。
2. 系统校验编码唯一、区域冲突、资质有效期、结算主体和未完成任务。
3. 运营初审，平台管理员或合规员复审。
4. 审批通过后生效；拒绝、冻结、合并和归档均保留原组织、订单、资金、安全事件和服务关系快照。

### 7.2 服务人员准入

1. 人员自主注册、组织创建或批量导入形成草稿。
2. 审核实名、角色、证照、培训、保险、组织和服务区域。
3. 安全相关角色由安全主管复核；到期后自动限制对应任务能力。
4. 调配须记录来源、目标、有效期、影响任务与审批意见。

### 7.3 电商 CRUD 与财务、钱包、报表查询

1. 管理员维护 `ec_category`、`ec_product`、`ec_product_attribute` 和 `ec_product_image`，商品详情聚合展示分类、属性和图片。
2. 购物车、订单和评论按用户、商品、状态和时间进行查询、详情查看、创建、更新和逻辑删除。
3. 财务人员维护支付、结算、对账记录；钱包、钱包流水、充值和提现记录由业务动作生成，后台仅支持列表与详情查看。金额字段采用最小货币单位整数。
4. 运营人员按统计周期、组织、区域和商品维度查询报表、报表明细和指标；报表数据由统计任务生成，后台不提供新增、编辑或删除。

### 7.4 最小验收集

- 可创建、审核、启停和查询可燃气体站、配送点、服务人员及平台账户。
- 气站可在授权范围内管理所属配送点、服务人员和用户服务关系；配送点仅管理本点人员和用户关系。
- 电商分类、商品、属性、图片、购物车、订单和评论均可完成 CRUD。
- 财务支付、结算和对账记录可完成 CRUD；钱包、钱包流水、充值、提现、统计报表和报表明细仅支持列表与详情查看。
- 订单详情可查询配送轨迹，轨迹和轨迹点数据均可完成 CRUD。
- 智能瓶阀安全事件具备分级、派发、升级、处置、复核和审计闭环。
- 所有高风险操作、资金审批、跨组织变更及敏感导出均可按操作人、对象、时间和理由追溯。