32 KiB
32 KiB
平台总后台需求分析
1. 文档目标与范围
本文将 平台总后台需求 拆解为可实施的领域模型、接口边界与 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自增主键，作为物理主键和内部关联键。 - 平台后台管理的平台、气站、配送、员工和业主账号在初始化、创建和修改密码时仅校验密码不少于 6 个字符，不校验字符种类或组合复杂度。
- 所有主表额外包含
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 |
遥测摘要与质量标记 |
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开头；除登录和健康检查外，均要求原始 JWTAuthorization请求头。 - 请求和响应字段使用
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 |
/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、用户与智能瓶阀绑定 |
电商管理 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 组织准入与跨组织变更
- 运营创建草稿或批量导入。
- 系统校验编码唯一、区域冲突、资质有效期、结算主体和未完成任务。
- 运营初审，平台管理员或合规员复审。
- 审批通过后生效；拒绝、冻结、合并和归档均保留原组织、订单、资金、安全事件和服务关系快照。
7.2 服务人员准入
- 人员自主注册、组织创建或批量导入形成草稿。
- 审核实名、角色、证照、培训、保险、组织和服务区域。
- 安全相关角色由安全主管复核；到期后自动限制对应任务能力。
- 调配须记录来源、目标、有效期、影响任务与审批意见。
7.3 电商 CRUD 与财务、钱包、报表查询
- 管理员维护
ec_category、ec_product、ec_product_attribute和ec_product_image，商品详情聚合展示分类、属性和图片。 - 购物车、订单和评论按用户、商品、状态和时间进行查询、详情查看、创建、更新和逻辑删除。
- 财务人员维护支付、结算、对账记录；钱包、钱包流水、充值和提现记录由业务动作生成，后台仅支持列表与详情查看。金额字段采用最小货币单位整数。
- 运营人员按统计周期、组织、区域和商品维度查询报表、报表明细和指标；报表数据由统计任务生成，后台不提供新增、编辑或删除。
7.4 最小验收集
- 可创建、审核、启停和查询可燃气体站、配送点、服务人员及平台账户。
- 气站可在授权范围内管理所属配送点、服务人员和用户服务关系；配送点仅管理本点人员和用户关系。
- 电商分类、商品、属性、图片、购物车、订单和评论均可完成 CRUD。
- 财务支付、结算和对账记录可完成 CRUD；钱包、钱包流水、充值、提现、统计报表和报表明细仅支持列表与详情查看。
- 订单详情可查询配送轨迹，轨迹和轨迹点数据均可完成 CRUD。
- 智能瓶阀安全事件具备分级、派发、升级、处置、复核和审计闭环。
- 所有高风险操作、资金审批、跨组织变更及敏感导出均可按操作人、对象、时间和理由追溯。