docs: align platform requirements with implementation
This commit is contained in:
david
182
AGENTS.md
Normal file
182
AGENTS.md
Normal file
@@ -0,0 +1,182 @@
|
|||||||
|
# AGENTS.md
|
||||||
|
|
||||||
|
本文件适用于整个仓库。目标是让后续开发始终围绕“物联网智能瓶阀平台”的既定业务边界、架构和契约推进，避免把当前平台总后台扩成万能系统，或让样例、文档规划与已实现代码相互混淆。
|
||||||
|
|
||||||
|
## 1. 开始工作前
|
||||||
|
|
||||||
|
1. 先阅读 `docs/README.md`，再按改动范围阅读：
|
||||||
|
- 业务边界：`docs/01-项目总览与边界.md`
|
||||||
|
- 跨系统流程：`docs/02-核心业务流程.md`
|
||||||
|
- 对应终端需求：`docs/03` 至 `docs/09`
|
||||||
|
- 架构和命名：`docs/10-技术实现规划.md`
|
||||||
|
- 接口、安全与隐私：`docs/11-数据接口与安全.md`
|
||||||
|
- 验收范围：`docs/12-验收与迭代规划.md`
|
||||||
|
2. 检查 `git status`，保留用户已有改动；不要顺手格式化、重写或删除无关文件。
|
||||||
|
3. 区分三类内容：
|
||||||
|
- `frontend/platform_admin`、`backend/{api,worker,iot}` 是当前业务实现。
|
||||||
|
- `sample/front`、`sample/server` 是工程基线和参考，不是线上业务模块；除非任务明确要求更新基线，否则不要修改。
|
||||||
|
- `docs/10-技术实现规划.md` 中尚不存在的目录和系统属于规划，不得为完成局部任务擅自创建空壳工程。
|
||||||
|
4. 需求不明确时以文档中的系统主责、数据主责和安全规则为边界；不得把标为“待确认”的事项自行固化为政策。
|
||||||
|
5. 文档之间出现冲突时按以下顺序处理：
|
||||||
|
- 用户在当前任务中的明确要求。
|
||||||
|
- 已实现代码、资源契约和 `docs/05-平台总后台需求-分析.md` 中的平台后台实施规则。
|
||||||
|
- `docs/01` 至 `docs/12` 的全局规划。
|
||||||
|
- `docs/superpowers` 和审计报告只说明特定历史变更，不自动成为新需求。
|
||||||
|
不能静默选择其中一套；会影响数据兼容、接口或业务口径时，应先记录冲突及迁移影响。
|
||||||
|
|
||||||
|
## 2. 当前架构与模块边界
|
||||||
|
|
||||||
|
首期架构是“模块化单体 API + 独立 Worker + 独立 IoT 进程”：
|
||||||
|
|
||||||
|
- `backend/api`：Gin HTTP API/BFF、鉴权、同步业务事务、数据库事实和审计。
|
||||||
|
- `backend/worker`：Outbox 投递、Redis Streams 消费、告警、派单、通知、对账和超时任务。当前主要是 Mock 边界，未确定持久化消息契约前不要伪造完整实现。
|
||||||
|
- `backend/iot`：MQTT 会话、协议适配、遥测、设备命令和回执。当前使用 Mock 适配，不得假定已连接真实设备或 Broker。
|
||||||
|
- `frontend/platform_admin`：平台级治理、运营、财务、安全、主数据和审计界面；后端资源契约是其资源和操作能力的依据。
|
||||||
|
- `docs`：产品和技术基线；涉及业务口径、实体、状态、权限或跨端流程的变更必须同步更新相应文档。
|
||||||
|
- `doc`：原始设计图和协议附件，仅作需求来源；不要批量改名、压缩或重写。
|
||||||
|
|
||||||
|
系统职责必须保持分离：
|
||||||
|
|
||||||
|
- 平台总后台不承接气站、配送点、生产单位的日常重复操作。
|
||||||
|
- 气站、配送点、生产、API 中心的业务事实各有唯一主责系统；其他系统通过 API、事件或只读聚合使用。
|
||||||
|
- API 中心只管理接口产品和调用方，不能绕过业务服务直接写业务数据库。
|
||||||
|
- `api` 不应承担长期运行的异步循环；`worker` 不应复制同步领域事务；`iot` 不应内嵌交易、资金或后台页面逻辑。
|
||||||
|
|
||||||
|
### 目录归属规则
|
||||||
|
|
||||||
|
仓库目录按以下职责使用，不要跨目录堆放代码：
|
||||||
|
|
||||||
|
```text
|
||||||
|
platforms/
|
||||||
|
apps/ # 规划：Flutter 用户端与服务端 App
|
||||||
|
user_app/ # 用户设备、安全、商城、订单、钱包
|
||||||
|
service_app/ # 配送、安装维修、安检的角色化工作台
|
||||||
|
frontend/
|
||||||
|
platform_admin/ # 当前：平台总后台
|
||||||
|
gas_admin/ # 规划：气站日常经营
|
||||||
|
delivery_admin/ # 规划：配送点调度和配送库存
|
||||||
|
product_admin/ # 规划：生产、质检和设备追溯
|
||||||
|
openapi/ # 规划：API 产品和调用方治理
|
||||||
|
backend/
|
||||||
|
api/ # 当前：同步 HTTP API/BFF
|
||||||
|
worker/ # 当前：异步任务和事件消费
|
||||||
|
iot/ # 当前：MQTT 与设备协议边界
|
||||||
|
contracts/
|
||||||
|
openapi/ # 规划：HTTP 契约
|
||||||
|
asyncapi/ # 规划：MQTT/事件契约
|
||||||
|
deploy/ # 规划：Caddy、发布和回滚
|
||||||
|
scripts/ # 当前：仓库级开发启动脚本
|
||||||
|
tests/ # 规划：跨模块契约、E2E 和性能测试
|
||||||
|
docs/ # 需求与技术基线
|
||||||
|
doc/ # 原始设计图、协议和附件
|
||||||
|
sample/ # 前后端工程基线，只作参考或上游模板
|
||||||
|
```
|
||||||
|
|
||||||
|
- “规划”目录只表示未来归属；任务没有明确要求时不得提前创建。
|
||||||
|
- 新管理端统一使用 `sample/front` 的公共机制，新 Go 进程统一使用 `sample/server` 的分层；通过共享包、模板或上游同步复用，禁止复制后独立漂移。
|
||||||
|
- 跨系统契约放入 `contracts`（目录落地后）；不能把共享协议定义埋在某个前端页面或单个进程的私有目录中。
|
||||||
|
- 仓库级启动、生成和质量脚本放 `scripts/`；单模块构建脚本放该模块的 `scripts/`。
|
||||||
|
|
||||||
|
### 平台总后台内部目录
|
||||||
|
|
||||||
|
- `frontend/platform_admin/src/views`：按一级业务域组织页面，不把业务页面堆进 `App.vue`。
|
||||||
|
- `frontend/platform_admin/src/components`：跨业务复用的展示与交互组件；仅供单一业务域使用的组件留在对应 `views/<domain>` 下。
|
||||||
|
- `frontend/platform_admin/src/api`：HTTP 客户端、会话、资源调用和接口类型。
|
||||||
|
- `frontend/platform_admin/src/contracts`：由后端同步的资源契约生成物，不手工维护漂移版本。
|
||||||
|
- `frontend/platform_admin/src/router`：受控本地路由及菜单映射；菜单授权仍由后端能力决定。
|
||||||
|
- `backend/api/internal/routers/platform.go`：平台 HTTP 路由注册入口。
|
||||||
|
- `backend/api/internal/logic/platform/<domain>`：平台各业务域规则；跨域共性能力才进入 `logic/common`。
|
||||||
|
- `backend/api/internal/models`：GORM 模型、表名和中文模型注释。
|
||||||
|
- `backend/api/internal/initdb`：系统必需的幂等初始化数据；演示数据属于 `seed`，二者不得混用。
|
||||||
|
|
||||||
|
## 3. 不可破坏的业务与安全约束
|
||||||
|
|
||||||
|
- 设备远程控制必须记录命令、幂等键和设备回执；请求成功不等于执行成功，超时应进入“待确认”。
|
||||||
|
- 自动关阀必须有设备侧安全兜底；普通用户不能绕过安全事件、整改或授权规则直接复开。
|
||||||
|
- 订单、支付、提现、设备命令、安全事件、检查、整改和敏感数据访问必须可审计。
|
||||||
|
- 金额使用最小货币单位整数；资金、安全事件和审计事实不得物理删除或由前端直接改状态。
|
||||||
|
- 状态流转、金额、权限、地理围栏和工单完成条件必须由服务端校验；菜单隐藏、按钮禁用和客户端缓存不构成安全控制。
|
||||||
|
- 写操作需要幂等；支付回调必须校验签名、金额、订单和商户身份；异步操作返回可查询的任务或命令标识。
|
||||||
|
- 手机号、地址、证件、收款账户、定位、照片、视频和合同属于敏感数据，必须最小权限、脱敏展示、受控下载并记录访问。
|
||||||
|
- 离线补传必须保留原始采集时间、服务端接收时间、操作者、任务、来源、完整性标记和幂等键，不得用补传时间覆盖采集时间。
|
||||||
|
- Redis 只用于缓存、会话、限流、延迟任务和可恢复事件流，不能替代 PostgreSQL 中的业务事实；关键事件遵循“数据库事务 + Outbox + Worker 投递”。
|
||||||
|
|
||||||
|
## 4. 数据模型与契约
|
||||||
|
|
||||||
|
- 新领域实体遵循 `docs/10-技术实现规划.md` 的“模块前缀 + 单数实体词根”规范；同一实体的表、文件、Go/Vue/Flutter 类型和 Schema 使用同一词根。
|
||||||
|
- **每一张表（包括主表、明细表、关系表、流水表和日志表）都必须包含 `id bigint` 自增主键。** Go 模型对应声明自增主键 `ID uint64`。不允许使用 UUID、业务编号或联合字段替代数据库物理主键。
|
||||||
|
- 主表必须额外包含 `identity varchar(36)`，由应用生成 UUID V7 并建立唯一索引；需要被接口单独访问、跨服务引用或审计定位的明细/关系表也必须包含 `identity`。
|
||||||
|
- `id` 只用于本数据库内部关联和查询；HTTP、消息、日志审计、前端及跨服务调用统一使用 `identity`，不得暴露或接受内部自增 ID 作为资源身份。
|
||||||
|
- 数据库内部外键优先使用 `<实体词根>_id` 关联自增主键；跨服务契约、异步事件和审计关联使用 `<实体词根>_identity`。同一场景不要混用二者。
|
||||||
|
- 每张表至少包含 `id`、`created_at`、`updated_at`；主表按需统一包含 `identity`、`status`、`version`、创建人与更新人。不可变流水和日志可以禁止业务更新，但仍需保留自增主键。
|
||||||
|
- 业务编号另设唯一字段，只用于展示和检索，不能替代 `id` 或 `identity`。
|
||||||
|
- 表、字段、枚举、领域模型、公开接口、复杂状态机、金额和权限规则必须有说明业务意图的中文注释。
|
||||||
|
- 当前代码存在早期实体名和扁平资源路径（例如 `/gas_basic`）。不要在普通功能改动中顺手重命名；规范化必须有单独设计、迁移、兼容方案和全仓引用检查。
|
||||||
|
- HTTP 路由、后端资源契约、前端资源定义和权限菜单必须一起变更。修改后端模型或路由后，在 `frontend/platform_admin` 执行 `pnpm contract:sync`，提交生成的 `src/contracts/platform-resources.json`，再执行 `pnpm contract:check`。
|
||||||
|
- 业务状态流转使用专用动作接口，不通过通用 CRUD 直接写 `status`。前端不得依据错误文案驱动流程，应使用稳定错误码。
|
||||||
|
- 不新增同义模型、同义路由或只为某个页面服务的重复事实表；新增实体前先确认所属领域和唯一名称。
|
||||||
|
|
||||||
|
## 5. 后端实现规范
|
||||||
|
|
||||||
|
- Go 版本以 `backend/go.work` 和各 `go.mod` 为准；三个模块保持 `cmd`、`internal/config`、`internal/impl`、`internal/logic`、`internal/models`、`internal/routers`、`etc` 等 BSM-SDK Core 分层。
|
||||||
|
- 路由只做绑定、中间件和请求入口；业务规则放在对应 `internal/logic` 领域包；模型集中于 `internal/models`；基础设施装配放在 `internal/impl`。
|
||||||
|
- 所有后台接口执行服务端 JWT、角色、菜单能力和数据范围校验。现有平台 JWT 请求头传原始令牌，不擅自改成 `Bearer`，除非同步完成兼容迁移。
|
||||||
|
- 数据库写入应明确事务、并发和审计边界；关键消费者、回调和命令处理必须可安全重试。
|
||||||
|
- 不把真实密码、令牌、数据库凭证写入 YAML、日志、测试或提交记录。开发配置只保留安全示例；初始化 root 密码优先读取 `HEQI_PLATFORM_ROOT_PASSWORD`。
|
||||||
|
- 修改 Go 文件后运行 `gofmt`；不要用全仓格式化掩盖业务改动。
|
||||||
|
|
||||||
|
## 6. 前端实现规范
|
||||||
|
|
||||||
|
- 技术栈保持 Vue 3、TypeScript、Vite、Pinia、Arco Design；包管理器使用 pnpm，Node.js 要求见 `frontend/platform_admin/package.json`。
|
||||||
|
- 管理端界面保持中文。浏览器路由按业务域组织，API 资源路径以当前后端契约为准。
|
||||||
|
- 普通契约型资源优先复用 `views/shared/ResourcePage.vue` 及共享列表/表单能力；只有复杂工作流、可视化或跨资源交互才新增专用页面。
|
||||||
|
- 权限、枚举、字段和动作从契约或统一定义读取，禁止在多个页面复制一套易漂移的配置。
|
||||||
|
- 不在前端实现可信的金额计算、权限决策或状态机；提交 `identity`，不提交数据库内部 ID。
|
||||||
|
- 未经明确要求不要修改 `dist`、`node_modules` 或构建报告等生成物。
|
||||||
|
|
||||||
|
## 7. 测试与验证
|
||||||
|
|
||||||
|
按改动范围执行最小充分验证，并在交付说明中列出实际运行的命令：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 后端 API
|
||||||
|
cd backend/api
|
||||||
|
go test ./...
|
||||||
|
go vet ./...
|
||||||
|
go build ./cmd/main/main.go
|
||||||
|
|
||||||
|
# Worker / IoT（改动对应模块时）
|
||||||
|
cd backend/worker && go test ./... && go build ./cmd/main/main.go
|
||||||
|
cd backend/iot && go test ./... && go build ./cmd/main/main.go
|
||||||
|
|
||||||
|
# 平台总后台
|
||||||
|
cd frontend/platform_admin
|
||||||
|
pnpm type:check
|
||||||
|
pnpm lint
|
||||||
|
pnpm contract:check
|
||||||
|
pnpm build
|
||||||
|
```
|
||||||
|
|
||||||
|
- 领域规则、金额、权限、状态机和幂等逻辑必须有单元测试。
|
||||||
|
- 路由或资源变化必须更新路由/契约测试；高风险操作必须覆盖越权、非法状态和重复请求。
|
||||||
|
- 修复缺陷时优先添加能复现问题的回归测试。
|
||||||
|
- 不使用 `go fmt ./...`、`pnpm lint:fix` 等批量写命令，除非任务明确是全仓格式化。
|
||||||
|
|
||||||
|
本地启动入口：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./scripts/run_backend.sh
|
||||||
|
./scripts/run_frontend.sh
|
||||||
|
# 或同时运行
|
||||||
|
./scripts/run_platform.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
默认地址为后端 `http://localhost:12426/heqi/platform/v1`、前端 `http://localhost:5173`。
|
||||||
|
|
||||||
|
## 8. 变更完成标准
|
||||||
|
|
||||||
|
- 改动只落在正确的主责模块，没有把规划系统偷塞进平台总后台。
|
||||||
|
- 需求、模型、契约、路由、权限、前端和测试在受影响范围内保持一致。
|
||||||
|
- 没有引入同义实体、越权入口、直接状态写入、浮点金额、不可恢复事件或敏感信息泄露。
|
||||||
|
- 已运行与改动相称的测试/检查；若因环境或外部依赖未运行，明确说明具体原因。
|
||||||
|
- 不提交日志、临时文件、本地配置、构建目录、依赖目录或无关格式化变更。
|
||||||
@@ -1,138 +1,305 @@
|
|||||||
# 平台总后台需求
|
# 平台总后台需求（现状基线）
|
||||||
|
|
||||||
## 1. 系统定位
|
## 1. 文档目的
|
||||||
|
|
||||||
平台总后台是全平台唯一的治理与跨组织运营中心，负责组织/权限、全局安全、设备全生命周期、交易资金、内容与规则、跨系统数据分析和审计。它不是各业务系统日常重复操作的入口：可燃气体站、配送点和生产单位在各自系统中处理本组织日常业务。
|
本文根据当前已完成的 `frontend/platform_admin` 与 `backend/api` 代码反向整理，是平台总后台现阶段的功能、权限、数据和验收基线。
|
||||||
|
|
||||||
## 2. 主要功能域
|
本文只描述代码中已经存在的能力。原始产品规划中尚未实现的安全运营中心、邀请注册二维码、全局地图、生产管理、API 中心等能力统一列入“未实现范围”，不得据此文档认定为已交付。
|
||||||
|
|
||||||
| 功能域 | 核心功能 | 数据边界 |
|
实现事实来源按以下顺序核对：
|
||||||
|
|
||||||
|
1. `backend/api/internal/routers/platform.go`：实际 HTTP 路由。
|
||||||
|
2. `frontend/platform_admin/src/contracts/platform-resources.json`：前后端资源契约。
|
||||||
|
3. `frontend/platform_admin/src/api/resources.ts`：字段、关系、页面模式和业务动作。
|
||||||
|
4. `frontend/platform_admin/src/router/routes/modules/platform.ts`：菜单、页面与隐藏子资源。
|
||||||
|
5. `backend/api/internal/logic/platform`：状态机、事务、权限和业务校验。
|
||||||
|
|
||||||
|
## 2. 系统定位与边界
|
||||||
|
|
||||||
|
平台总后台是和气平台当前已落地的 Web 管理端，面向平台管理员提供跨组织主数据、人员用户、智能气阀、配送合同与订单、电商数据、钱包财务、内容客服和后台权限管理。
|
||||||
|
|
||||||
|
当前系统不替代以下业务系统：
|
||||||
|
|
||||||
|
- 气站管理系统：站点经营、站内库存和日常订单运营仍由后续气站端主责。
|
||||||
|
- 配送点管理系统：末端调度、配送仓和配送作业仍由后续配送点端主责。
|
||||||
|
- 生产管理系统：设备生产、质检、序列号注入和出厂追溯尚未在本后台实现。
|
||||||
|
- API 中心：开放 API 产品、调用方、凭证和配额管理尚未实现。
|
||||||
|
- 用户端与服务端 App：本后台不承担用户设备控制、配送员定位采集或现场取证。
|
||||||
|
|
||||||
|
当前后端 API 基础路径为 `/heqi/platform/v1`。除健康检查和登录外，其余接口均要求 JWT，并继续执行平台菜单权限校验。
|
||||||
|
|
||||||
|
## 3. 技术与数据约定
|
||||||
|
|
||||||
|
### 3.1 实现目录
|
||||||
|
|
||||||
|
| 范围 | 当前目录 | 职责 |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| 组织权限 | 管理员、角色、权限、可燃气体站、配送点、生产单位、服务区域、数据范围 | 全局；支持按组织、区域、对象归属授权 |
|
| 管理端 | `frontend/platform_admin` | Vue 3、TypeScript、Vite、Pinia、Arco Design |
|
||||||
| 用户与服务人员 | 用户 360、服务关系、服务人员准入/培训/打卡、资质、角色、冻结、分账、跨组织调配 | 查看敏感数据受字段权限和审计控制 |
|
| 页面 | `frontend/platform_admin/src/views` | 仪表盘、报表及契约驱动的资源页面 |
|
||||||
| 设备与安全 | 设备模型、绑定、遥测、命令、规则、事件、SLA、安检/整改、强制升级 | 全局安全规则和高风险动作仅授权角色可操作 |
|
| 资源定义 | `frontend/platform_admin/src/api/resources.ts` | 字段、关联、读写模式和详情动作 |
|
||||||
| 商品交易 | 全局商品主数据、价格策略、订单、售后、支付、合同、优惠规则 | 站点商品与库存由站点系统主责，平台可治理与审计 |
|
| 前端契约 | `frontend/platform_admin/src/contracts/platform-resources.json` | 后端资源和路由生成清单 |
|
||||||
| 资金结算 | 充值、支付、退款、分账、结算、提现、对账、打款凭证 | 财务角色分离，关键审批支持双人复核 |
|
| 前端路由 | `frontend/platform_admin/src/router/routes/modules/platform.ts` | 一级菜单、二级菜单和隐藏详情资源 |
|
||||||
| 内容与客服 | 轮播、公告、协议、宣教内容、消息模板、客服配置、投诉工单 | 发布有审核、版本和撤回能力 |
|
| 后端 API | `backend/api` | Gin HTTP API、JWT、事务和统一响应 |
|
||||||
| 邀请与轨迹治理 | 气站/配送点邀请二维码、注册归因、配送轨迹、定位访问与导出审批 | 二维码、服务关系和定位均按最小权限、可撤销与审计治理 |
|
| 路由 | `backend/api/internal/routers/platform.go` | 平台 API 唯一路由注册入口 |
|
||||||
| 全局运营 | 用户/订单/设备/事件/履约指标，地图和异常看板 | 支持跨组织下钻但遵循权限和脱敏 |
|
| 业务逻辑 | `backend/api/internal/logic/platform` | 各领域查询、动作、权限和状态流转 |
|
||||||
| 审计合规 | 操作审计、导出审计、敏感访问、数据留存、注销与合规工单 | 不可由普通管理员删除或篡改 |
|
| 模型 | `backend/api/internal/models` | GORM 模型、表名与中文注释 |
|
||||||
|
| 初始化 | `backend/api/internal/initdb` | root 账户和系统必需数据的幂等初始化 |
|
||||||
|
|
||||||
## 3. 全局组织与主体管理
|
### 3.2 数据身份
|
||||||
|
|
||||||
平台总后台维护所有经营主体的唯一主档，并将组织、区域、人员、库存、设备、订单、资金和服务能力关联起来。任何业务系统都只能编辑其被授权字段；组织准入、冻结、跨组织变更、结算主体与高风险资质由平台审批。
|
- 每一张表均使用 `id bigint` 自增主键，Go 模型对应 `ID uint64`。
|
||||||
|
- 主表额外使用应用生成的 UUID V7 `identity`，并建立唯一索引。
|
||||||
|
- `id` 仅用于数据库内部关联；HTTP 路径、前端选择器、审计和跨服务关联使用 `identity`。
|
||||||
|
- 前端不得提交数据库内部 `id`，关联字段统一提交业务 `identity`。
|
||||||
|
- 通用记录状态包括草稿、启用、停用、归档和冻结；业务状态另设专用字段。
|
||||||
|
- 删除接口执行归档或受控删除语义；资金流水、订单过程记录、归属记录等事实资源不开放通用删除。
|
||||||
|
- 金额由后端以最小货币单位整数保存；前端展示时换算为元。
|
||||||
|
|
||||||
### 3.1 可燃气体站管理
|
### 3.3 资源页面模式
|
||||||
|
|
||||||
可燃气体站是销售、安装维修、安检协同和结算的经营主体。后台应支持创建、导入、审核、启停、合并/迁移及归档，且所有历史订单、资金和安全事件必须保留原站点归属。
|
| 模式 | 能力 |
|
||||||
|
|
||||||
| 管理项 | 必填/展示信息 | 平台操作与规则 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| 基本档案 | 站点编码、名称、统一社会信用代码、法人/负责人、联系人、地址、经纬度、营业时间、状态 | 站点编码全局唯一；证照、负责人、结算主体变更进入审核流 |
|
|
||||||
| 经营与服务 | 覆盖区域、可售商品、库存仓、服务类型、预约时段、客服信息、配送协作方式 | 覆盖区域不得无审批重叠；服务类型决定可创建的订单和任务 |
|
|
||||||
| 人员与权限 | 站长、运营、仓管、客服、财务等站内账号及其数据范围 | 平台可授权、冻结、重置和回收；在平台授权的角色和数据范围内，站点管理员可管理本站账号、配送点、服务人员与用户服务关系，但不能自行提升权限 |
|
|
||||||
| 业务与质量 | 用户数、设备数、订单、履约时效、售后、投诉、安检整改、告警响应 | 支持按区域/时间下钻；超时、投诉率、整改率触发经营风险预警 |
|
|
||||||
| 资金与结算 | 支付、退款、佣金、分账比例、待结算、提现、对账差异和打款凭证 | 分账规则按版本和生效时间保存；冻结站点时停止新结算和新订单，存量订单按预案处理 |
|
|
||||||
| 资质与风险 | 营业证照、服务资质、保险、到期日、风险等级、冻结/解冻原因 | 临期提醒；资质失效自动限制受影响业务，并通知站点和平台责任人 |
|
|
||||||
|
|
||||||
### 3.2 配送点管理
|
|
||||||
|
|
||||||
配送点是末端配送资源和配送库存的组织单元，可独立归属平台或某个可燃气体站。平台负责配送点准入、服务范围、资源能力、库存关系、负责人和异常监管；气站可在授权范围内创建和维护归属本站的配送点，平台负责审核及跨组织变更。
|
|
||||||
|
|
||||||
| 管理项 | 必填/展示信息 | 平台操作与规则 |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| 基本档案 | 配送点编码、名称、归属组织、负责人、地址、经纬度、营业时段、状态 | 一个配送点只能有一个当前归属；变更归属须盘点库存、结清在途任务后审批 |
|
|
||||||
| 服务能力 | 覆盖区域、日配送上限、车辆/工具、服务时段、可配送商品、预约规则 | 超出能力或服务区时禁止自动分单，进入人工调度队列 |
|
|
||||||
| 服务人员与用户 | 服务人员角色、班次、在岗状态、资质、负载、评分、违规/异常记录，以及配送服务用户关系 | 配送点可在授权范围内管理本点服务人员和用户服务关系；人员可归属一个主配送点，跨点支援需要授权和有效期 |
|
|
||||||
| 配送库存 | 仓位、可用/锁定/在途/损耗库存、调拨、盘点、批次 | 站点转入、配送领用、签收/退回均生成库存流水；盘亏、报损需审批 |
|
|
||||||
| 运营质量 | 接单率、准时率、签收率、异常率、投诉率、配送成本 | 阈值预警、整改任务和配送点/负责人考核可配置 |
|
|
||||||
|
|
||||||
### 3.3 服务人员统一管理
|
|
||||||
|
|
||||||
服务人员是安装维修员、安检员和配送员的统一人员主档。一个人员可配置多个角色，但角色资格、服务区域、组织归属和可执行任务必须分别生效，避免以“有账号”替代“有作业资格”。
|
|
||||||
|
|
||||||
| 管理项 | 要求 |
|
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| 人员档案 | 姓名、手机号、证件/实名核验、紧急联系人、头像、所属组织、主归属、可服务区域、入离职状态；敏感字段脱敏并限制导出 |
|
| `writable` | 列表、详情、新增、编辑、状态调整和归档 |
|
||||||
| 角色与资质 | 配送、安装维修、安检角色；对应证书、培训、技能等级、有效期、保险、设备/车辆能力和附件。到期前提醒，到期后自动停用对应角色能力 |
|
| `editable` | 列表、详情、新增、编辑和状态调整，不提供归档 |
|
||||||
| 账号与设备 | 登录账号、角色、服务端 App 授权设备、登录历史、异常登录、密码重置、MFA（可配置）和会话强制失效 |
|
| `readonly` | 列表和详情；可通过显式业务动作处理，但无通用增删改 |
|
||||||
| 服务能力 | 工作时间、接单状态、最大负载、预约可用时段、服务区域、可处理商品/设备型号、语言或无障碍能力（可选） |
|
| `append_only` | 可创建事实记录，既有记录不通用编辑或删除 |
|
||||||
| 任务与绩效 | 当前/历史任务、接单率、准时率、完成率、复检通过率、投诉、违规、用户评分、收益和分账明细；指标须说明计算口径 |
|
| `managed` | 可创建和编辑，但生命周期必须通过专用动作推进 |
|
||||||
| 生命周期 | 草稿 -> 待审核 -> 在职/可接单 -> 暂停接单/冻结 -> 离职/归档。冻结不删除历史任务和资金流水；恢复须记录审批人和原因 |
|
|
||||||
|
|
||||||
#### 服务人员关键操作
|
普通资源统一复用 `ResourcePage.vue` 和共享列表组件。账户、钱包、关联记录等从所属资源详情进入；隐藏子资源不单独授予菜单权限。
|
||||||
|
|
||||||
- 平台可批量导入、审核、分配组织/区域、授予角色、设置分账比例、调整可接单状态和发起跨组织调配；气站可在本站授权范围内创建、维护和提交服务人员审核。服务人员通过 App 自主注册时，后台应展示申请来源、角色、材料、审核意见和生效记录。
|
## 4. 登录、账户与权限
|
||||||
- 平台不得直接替服务人员完成工单；改派、取消、强制下线和资质豁免必须记录原因、审批依据和受影响任务。
|
|
||||||
- 安装维修与安检等安全相关角色的资质、培训、每日培训、上/下班和违规记录应成为派单前置校验；配送任务还应校验配送点、班次、车辆/库存能力。后台可查看授权设备、打卡异常、培训未完成和离线补传异常，但不得替代服务人员提交现场事实。
|
|
||||||
|
|
||||||
### 3.4 用户统一管理
|
### 4.1 登录与个人账户
|
||||||
|
|
||||||
后台提供用户 360 视图，服务于客服、安全处置、订单履约、投诉和合规响应。气站可管理本站服务范围内的用户服务关系、线下建档和服务协同；用户本人及其家庭/设备授权关系是数据访问的基础，工作人员仅能在任务或职责范围内访问必要信息。
|
- 管理员使用用户名和密码登录。
|
||||||
|
- 停用账户不得登录；密码使用 bcrypt 校验。
|
||||||
|
- 登录成功返回 JWT、账户 `identity`、显示名称和角色编码。
|
||||||
|
- `Authorization` 请求头当前直接传 JWT 原始值，不使用 `Bearer` 前缀。
|
||||||
|
- 已登录账户可查看个人资料、角色和菜单编码。
|
||||||
|
- 修改密码必须校验当前密码，新密码不少于 12 位。
|
||||||
|
- 系统启动时幂等创建 `root` 管理账户；root 初始密码优先读取环境变量 `HEQI_PLATFORM_ROOT_PASSWORD`。
|
||||||
|
|
||||||
| 管理项 | 要求 |
|
### 4.2 RBAC 与数据能力
|
||||||
| --- | --- |
|
|
||||||
| 账户与身份 | 用户编号、手机号、注册来源、实名状态、登录状态、账号状态、协议同意版本、注销状态；手机和证件类信息默认脱敏 |
|
|
||||||
| 家庭与地址 | 默认地址、服务区域、地址历史、家庭成员/设备授权关系、定位授权状态；地址变更保留历史订单的快照 |
|
|
||||||
| 设备与安全 | 已绑定设备、在线状态、遥测摘要、控制历史、安全事件、安检/整改、安装维修记录和视频/图片证据访问权限 |
|
|
||||||
| 交易与服务 | 购物车、订单、支付/退款、合同、优惠券、预约、配送/安装记录、售后、投诉、客服会话和服务评价 |
|
|
||||||
| 钱包与风控 | 余额、充值、消费、退款、异常支付、限制原因；财务明细按财务权限查看，客服只看处理所需状态 |
|
|
||||||
| 账户处置 | 冻结登录、限制下单、限制设备控制、重置安全凭证、合并重复账户、注销申请处理；各动作必须区分原因、时效、影响范围和申诉入口 |
|
|
||||||
|
|
||||||
### 3.5 主体关系与跨组织协同
|
- `root` 角色拥有全部平台菜单能力。
|
||||||
|
- 非 root 账户必须关联处于启用状态的平台角色，并按角色菜单逐请求鉴权。
|
||||||
|
- 创建工作人员、安装人员、配送人员和运维人员是相互独立的菜单能力。
|
||||||
|
- 工作人员资质权限跟随所属人员角色，不能凭任一人员菜单访问其他类型人员资质。
|
||||||
|
- 创建配送订单使用独立的 `gasorder_create` 权限，不因拥有订单列表权限自动获得。
|
||||||
|
- 合同气瓶、合同修订、订单明细、分配记录、状态记录和确认记录等隐藏资源继承所属主菜单权限。
|
||||||
|
- 气站、配送点、人员和用户菜单可读取其详情内的钱包摘要；提现菜单可读取钱包信息用于审核。
|
||||||
|
- 角色的定位范围只允许 `standard`（脱敏坐标）或 `precise`（精确坐标）。root 默认使用精确坐标。
|
||||||
|
- 前端菜单隐藏只负责展示，最终权限由后端中间件执行。
|
||||||
|
|
||||||
```mermaid
|
## 5. 首页与报表
|
||||||
flowchart TB
|
|
||||||
P[平台总后台] --> GS[可燃气体站]
|
首页从真实数据库聚合以下指标：
|
||||||
P --> DP[配送点]
|
|
||||||
P --> SP[服务人员]
|
- 启用气站、启用配送点、在岗工作人员、启用用户和启用智能气阀数量。
|
||||||
P --> U[用户]
|
- 生效配送合同数量。
|
||||||
GS --> O[商品、服务订单、站点库存]
|
- 今日配送订单数量与今日应付金额。
|
||||||
DP --> D[配送任务、配送库存、配送员]
|
- 待受理客服工单数量。
|
||||||
SP --> T[安装维修、安检、配送任务]
|
- 累计支付成功金额。
|
||||||
U --> E[设备、地址、订单、安全事件]
|
- 配送订单状态分布、智能气阀状态分布、支付渠道实收金额。
|
||||||
O --> T
|
- 最近 7 个自然日的订单数量和订单金额趋势；无数据日期补零。
|
||||||
D --> T
|
|
||||||
T --> E
|
首页快捷入口根据当前角色菜单过滤。统计报表页复用同一真实汇总接口，不生成虚构报表数据，不提供报表配置或导出。
|
||||||
|
|
||||||
|
## 6. 已实现功能域
|
||||||
|
|
||||||
|
当前资源契约共 47 个资源。下表中的路径均相对于 `/heqi/platform/v1`。
|
||||||
|
|
||||||
|
### 6.1 机构管理
|
||||||
|
|
||||||
|
| 资源 | 路径 | 模式 | 已实现能力 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| 气站 | `/gas_basic` | 可写 | 新增草稿、详情、编辑、审核、启停、归档；管理气站账户和钱包 |
|
||||||
|
| 气站账户 | `/gas_account` | 可写 | 账号新增、编辑、启停和归档；必须关联气站 |
|
||||||
|
| 配送点 | `/delivery_basic` | 可写 | 新增、编辑、启停和归档；可关联气站；管理配送点账户和钱包 |
|
||||||
|
| 配送点账户 | `/delivery_account` | 可写 | 账号新增、编辑、启停和归档；必须关联配送点 |
|
||||||
|
|
||||||
|
气站创建后为草稿状态。气站审核通过后进入启用，审核不通过进入停用且必须填写理由；只有已启用或已停用气站可继续切换启停状态。审核过程写入独立审核记录。
|
||||||
|
|
||||||
|
### 6.2 工作人员管理
|
||||||
|
|
||||||
|
| 资源 | 路径 | 模式 | 已实现能力 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| 工作人员 | `/staff_account` | 可写 | 新增、编辑、启停、归档、查看钱包 |
|
||||||
|
| 人员资质 | `/staff_credential` | 可写 | 新增、编辑、启停和归档 |
|
||||||
|
|
||||||
|
工作人员支持安装人员 `installer`、配送人员 `delivery`、运维人员 `operations` 三种角色，可关联气站或配送点，并记录在岗/离岗状态。前端按角色提供独立列表和新增入口；后端按菜单和人员实际角色校验详情、修改及资质访问。
|
||||||
|
|
||||||
|
### 6.3 用户管理
|
||||||
|
|
||||||
|
| 资源 | 路径 | 模式 | 已实现能力 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| 用户账户 | `/user_account` | 可写 | 新增、编辑、启停、归档、查看钱包 |
|
||||||
|
| 用户地址 | `/user_address` | 可写 | 新增、编辑、默认地址、启停和归档 |
|
||||||
|
| 用户服务关系 | `/user_service_relation` | 可写 | 维护用户与气站、配送点、工作人员的关系 |
|
||||||
|
|
||||||
|
用户页面同时提供配送合同入口。当前后台可直接维护用户、地址和服务关系，但尚未实现邀请二维码注册、服务关系审批和完整历史时间线。
|
||||||
|
|
||||||
|
### 6.4 智能气阀管理
|
||||||
|
|
||||||
|
| 资源 | 路径 | 模式 | 已实现能力 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| 类型 | `/product_type` | 可编辑 | 类型新增、编辑和启停 |
|
||||||
|
| 库房 | `/product_warehouse` | 可编辑 | 库房新增、编辑和启停 |
|
||||||
|
| 智能气阀 | `/product_info` | 可编辑 | 档案新增、编辑、启停和专用生命周期流转 |
|
||||||
|
| 检修记录 | `/product_repair` | 可编辑 | 检修记录新增、编辑和状态调整 |
|
||||||
|
| 归属记录 | `/product_owner` | 只读 | 查询每次归属变更的动作、操作者、原因和时间 |
|
||||||
|
|
||||||
|
智能气阀必须关联类型，可选关联库房、气站、配送点或用户。归属组合由后端校验，不允许形成非法多重归属。生命周期支持待处理、在库、运输中、使用中、维修中和已报废；状态变化使用 `/product_info/:identity/lifecycle`，不能通过通用编辑直接改写。归属变化自动追加归属记录。
|
||||||
|
|
||||||
|
### 6.5 配送合同
|
||||||
|
|
||||||
|
| 资源 | 路径 | 模式 | 已实现能力 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| 配送合同 | `/gasorder_contract` | 受管 | 创建、草稿编辑、启用、续签、终止 |
|
||||||
|
| 合同气瓶 | `/gasorder_contract_product` | 仅追加 | 绑定气瓶、按理由解绑 |
|
||||||
|
| 合同修订 | `/gasorder_contract_revision` | 只读 | 查询启用、续签和终止形成的版本记录 |
|
||||||
|
|
||||||
|
合同关联用户和气站，可选关联配送点，记录合同编号、条款、附件、默认配送费及有效期。合同生命周期为草稿、生效、过期、终止。只有符合当前状态的专用动作可执行，启用、续签、终止和解绑均记录原因及操作者。
|
||||||
|
|
||||||
|
合同气瓶必须属于合同用户、处于可用状态且未报废；订单只能使用有效合同中仍绑定的气瓶。
|
||||||
|
|
||||||
|
### 6.6 气体配送订单
|
||||||
|
|
||||||
|
| 资源 | 路径 | 模式 | 已实现能力 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| 配送订单 | `/gasorder_basic` | 仅追加 | 创建及专用状态动作 |
|
||||||
|
| 订单明细 | `/gasorder_item` | 只读 | 查询合同气瓶、数量和金额快照 |
|
||||||
|
| 分配记录 | `/gasorder_assign` | 只读 | 查询配送点和工作人员分配历史 |
|
||||||
|
| 状态记录 | `/gasorder_status` | 只读 | 查询每次状态变化及原因 |
|
||||||
|
| 运行轨迹 | `/gasorder_track` | 只读 | 查询订单轨迹主记录 |
|
||||||
|
| 轨迹点 | `/gasorder_track_point` | 只读 | 查询轨迹节点或定位点 |
|
||||||
|
| 确认记录 | `/gasorder_confirm` | 只读 | 查询签收类型、人员和凭证 |
|
||||||
|
| 支付记录 | `/gasorder_payment` | 只读 | 查询配送订单支付事实 |
|
||||||
|
|
||||||
|
创建订单时必须提交唯一请求号、有效合同、创建方、用户地址、合同气瓶集合、联系人和联系方式。后端根据合同价格和默认配送费计算订单金额，不接受前端自行决定最终金额。
|
||||||
|
|
||||||
|
订单状态机如下：
|
||||||
|
|
||||||
|
```text
|
||||||
|
已创建 -> 已分配 -> 充装中 -> 已就绪 -> 配送中 -> 待确认 -> 已完成
|
||||||
|
└------> 已取消
|
||||||
|
充装中/已就绪/配送中/待确认 -> 异常 -> 恢复到异常前状态
|
||||||
```
|
```
|
||||||
|
|
||||||
- 站点、配送点、服务人员和用户都使用平台分配的全局唯一编号；历史数据保存业务发生时的组织和地址快照。
|
- 分配时必须选择启用配送点和处于启用、在岗状态的工作人员。
|
||||||
- 跨组织协作通过任务、调拨、结算和事件记录实现，不允许任一系统直接修改另一主体的核心主档或资金流水。
|
- 开始充装前必须已完成配送点分配。
|
||||||
- 组织合并、区域调整、服务人员调动、用户设备转移均需要影响评估，至少校验未完成任务、在途库存、安全事件、余额和结算状态。
|
- 每个状态动作要求当前状态合法，并追加状态记录。
|
||||||
|
- 完成订单必须处于待确认状态，并提交确认类型、收件人和可选凭证。
|
||||||
|
- 异常状态保留异常前状态，恢复时回到原状态。
|
||||||
|
- 通用资源编辑和状态字段直改不开放。
|
||||||
|
|
||||||
### 3.6 邀请注册二维码与配送轨迹治理
|
### 6.7 电商平台管理
|
||||||
|
|
||||||
| 管理项 | 平台要求 |
|
| 资源 | 路径 | 模式 | 已实现能力 |
|
||||||
| --- | --- |
|
| --- | --- | --- | --- |
|
||||||
| 邀请二维码 | 查看气站/配送点二维码的归属、类型、服务区域、适用活动、有效期、次数、状态、扫码/注册/首单转化及异常拦截；平台可按权限停用、冻结或重新生成，不得直接暴露令牌明文、用户隐私或接口密钥 |
|
| 商品分类 | `/ec_category` | 可写树 | 分类新增、编辑、排序、启停和归档 |
|
||||||
| 服务关系 | 查看用户与气站/配送点的建立来源、二维码归因、生效时间、历史变更和确认记录；重复扫码不重复建档，变更关系须保留原关系和影响评估 |
|
| 商品 | `/ec_product` | 可写 | 商品编码、名称、售价、库存及状态管理 |
|
||||||
| 轨迹运营 | 按订单、组织、配送员、区域、时间和异常类型查看轨迹质量、时效和任务事件；用户端只读简化轨迹，完整轨迹遵循组织边界 |
|
| 商品属性 | `/ec_product_attribute` | 可写 | 商品属性和值管理 |
|
||||||
| 精确轨迹访问 | 地图回放、精确坐标和轨迹导出须申请用途、审批期限、字段范围和水印；记录访问人、对象、用途、时间、导出结果及二次传播责任 |
|
| 商品图片 | `/ec_product_image` | 可写 | 图片地址、排序和封面管理 |
|
||||||
|
| 购物车 | `/ec_cart` | 只读 | 查询购物车事实 |
|
||||||
|
| 商城订单 | `/ec_order` | 只读 | 查询商城订单 |
|
||||||
|
| 商城订单明细 | `/ec_order_item` | 只读 | 查询商品和成交快照 |
|
||||||
|
| 商品评价 | `/ec_review` | 只读 | 查询评分和评价 |
|
||||||
|
|
||||||
## 4. 安全运营中心
|
平台当前只维护商品主数据。购物车、商城订单、订单明细和评价不允许平台后台通用新增、编辑、状态变更或删除。
|
||||||
|
|
||||||
- 实时显示设备离线、低电量、压力/温度异常、人工检查不合格等事件，按等级、超时、是否已关阀和责任方排序。
|
### 6.8 钱包与提现
|
||||||
- 管理告警规则版本、阈值、持续时间、适用设备型号、自动关阀、消息模板、静默期和灰度范围。
|
|
||||||
- 触发后生成事件、通知、责任任务和升级链路。对强制开阀、降级、关闭高风险事件要求二次确认和完整审计。
|
|
||||||
- 用户端首次登录或安全宣教更新后的强制阅读内容、展示范围、版本、频率和阅读确认由平台配置；紧急告警不得被宣教弹窗阻断。
|
|
||||||
|
|
||||||
## 5. 平台与其他 Web 系统的权责
|
| 资源 | 路径 | 模式 | 已实现能力 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| 钱包 | `/wallet_basic` | 只读 + 动作 | 按拥有者查询或幂等创建、后台充值、启用/停用/冻结 |
|
||||||
|
| 银行卡 | `/wallet_bank` | 只读 | 查询脱敏银行卡信息 |
|
||||||
|
| 钱包支付 | `/wallet_payment` | 只读 | 查询钱包支付记录 |
|
||||||
|
| 钱包流水 | `/wallet_record` | 只读 | 查询不可变余额流水 |
|
||||||
|
| 退款 | `/wallet_refund` | 只读 | 查询退款记录 |
|
||||||
|
| 提现 | `/wallet_apply_cash` | 只读 + 动作 | 审核通过、审核驳回、标记处理完成 |
|
||||||
|
|
||||||
- 平台总后台主责全局规则、跨组织协调、财务结算、全局设备与安全、主数据、审计。
|
钱包拥有者类型限定为气站、配送点、工作人员或用户。账户号等敏感字段在列表和非精确权限下脱敏。
|
||||||
- 可燃气体站管理系统主责站点经营、服务订单和站内库存。
|
|
||||||
- 配送点管理系统主责末端配送资源、调度和配送库存。
|
|
||||||
- 生产管理系统主责设备生产、质检、追溯和出厂入网。
|
|
||||||
- API 中心管理系统主责开放 API 产品与调用方治理；不拥有业务数据的主编辑权。
|
|
||||||
|
|
||||||
## 6. 权限、审核与审计要求
|
后台充值必须携带唯一请求号、金额、是否进入可提现余额、原因和备注；后端在事务中更新余额并追加钱包流水，重复请求不得重复入账。
|
||||||
|
|
||||||
| 场景 | 权限与审核要求 |
|
提现流程为：
|
||||||
| --- | --- |
|
|
||||||
| 新增/变更可燃气体站、配送点 | 运营初审 + 平台管理员/合规复审；结算主体、服务区域、证照变更必须留存附件和生效时间 |
|
|
||||||
| 服务人员准入、角色授予、资质豁免 | 人员运营审核；安全相关角色由安全主管复核；资质豁免必须有到期时间 |
|
|
||||||
| 用户冻结、限制设备控制、账户合并/注销 | 客服或风控发起，按风险级别审批；不得影响紧急安全通知和法定留存数据 |
|
|
||||||
| 分账比例、结算、提现、退款 | 财务角色隔离；高金额或异常操作双人复核；审核人与申请人不得为同一人 |
|
|
||||||
| 组织/人员/用户数据导出 | 按数据范围、字段级脱敏和审批策略控制；记录导出人、用途、数据量、时间和文件去向 |
|
|
||||||
| 高风险安全操作 | 自动关阀规则、强制开阀、风险降级、关闭高风险事件均需二次确认、操作理由和不可篡改审计 |
|
|
||||||
|
|
||||||
所有新增、编辑、审批、冻结、解冻、归档、导入、导出和跨组织调配均须记录操作者、角色、组织上下文、请求时间、IP/设备、前后值、原因、审批流和关联业务对象。审计日志与业务数据分离存储，普通运营账号无删除权限。
|
```text
|
||||||
|
待处理 -> 已通过 -> 已完成
|
||||||
|
└-> 已驳回
|
||||||
|
```
|
||||||
|
|
||||||
|
驳回必须填写原因；完成处理必须填写第三方流水号，可记录回调信息。申请人不能通过通用更新直接改变提现状态。
|
||||||
|
|
||||||
|
### 6.9 财务管理
|
||||||
|
|
||||||
|
| 资源 | 路径 | 模式 | 已实现能力 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| 支付记录 | `/fin_payment` | 只读 | 查询支付渠道、金额和支付状态 |
|
||||||
|
| 财务结算 | `/fin_settlement` | 可写 | 结算单新增、编辑、启停和归档 |
|
||||||
|
| 财务对账 | `/fin_reconciliation` | 只读 | 查询渠道账单和差异 |
|
||||||
|
|
||||||
|
结算单记录结算编号、主体类型、主体 `identity` 和结算周期。支付与对账是外部或异步形成的事实，当前平台只提供查询。
|
||||||
|
|
||||||
|
### 6.10 内容与客服
|
||||||
|
|
||||||
|
| 资源 | 路径 | 模式 | 已实现能力 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| 内容 | `/cms_content` | 可写 | 内容类型、标题、正文、版本和发布状态管理 |
|
||||||
|
| 客服工单 | `/cs_ticket` | 可写 | 用户、工单号、分类、优先级和状态管理 |
|
||||||
|
|
||||||
|
客服工单必须关联用户。首页将处于待受理状态的客服工单纳入待办指标。当前尚未实现客服会话、自动分派、SLA 升级和消息触达。
|
||||||
|
|
||||||
|
### 6.11 平台管理
|
||||||
|
|
||||||
|
| 资源 | 路径 | 模式 | 已实现能力 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| 平台账户 | `/platform_account` | 可写 | 账户新增、编辑、启停和归档 |
|
||||||
|
| 平台角色 | `/platform_role` | 可写 | 角色新增、编辑、启停、归档和菜单分配 |
|
||||||
|
| 平台菜单 | `/platform_menu` | 只读树 | 查询系统初始化的菜单结构 |
|
||||||
|
|
||||||
|
平台账户必须关联角色编码。系统角色和 root 账户受保护，不能通过普通管理动作破坏。角色菜单通过 `/platform_role/:identity/menu` 整体读取和替换，菜单自身由系统初始化，不在后台任意增删改。
|
||||||
|
|
||||||
|
## 7. 通用页面与接口行为
|
||||||
|
|
||||||
|
- 列表资源提供分页、字段筛选、状态展示、详情和关联资源选择。
|
||||||
|
- 树资源用于商品分类和平台菜单层级展示。
|
||||||
|
- 关联选择器提交关联资源 `identity`，后端解析为内部自增外键。
|
||||||
|
- 密码字段只用于创建或显式更新，不在详情与列表返回明文。
|
||||||
|
- 所有资源响应经过统一响应封装；前端统一处理登录失效和错误提示。
|
||||||
|
- 业务动作在详情页按当前业务状态显示；即使前端未隐藏，后端仍必须拒绝非法状态转换。
|
||||||
|
- 路由、资源模式和页面能力由后端资源契约校验，任一层缺失时契约审计失败。
|
||||||
|
|
||||||
|
## 8. 当前未实现范围
|
||||||
|
|
||||||
|
以下能力在总体规划中存在，但当前平台前后端没有完整可验收实现：
|
||||||
|
|
||||||
|
- 安全事件中心、告警规则、自动关阀审批、安检整改和复检。
|
||||||
|
- 设备遥测实时页面、设备命令下发、命令回执和 MQTT 在线状态。
|
||||||
|
- 气站/配送点邀请二维码、扫码归因和服务关系变更审批。
|
||||||
|
- 配送员实时定位采集、地图回放、精确轨迹导出审批和轨迹异常识别。
|
||||||
|
- 用户 360、跨组织协同时间线和完整敏感访问审计。
|
||||||
|
- 文件上传、对象存储签名访问、病毒检测和证据哈希。
|
||||||
|
- 支付回调接入、自动对账、自动打款、电子发票和电子合同第三方签署。
|
||||||
|
- 全局安全地图、运营规则中心、通知模板、消息任务和触达回执。
|
||||||
|
- 独立审计中心、审批中心、导出审计和不可变操作日志查询页面。
|
||||||
|
- 生产管理系统、气站管理系统、配送点管理系统、API 中心和两类 Flutter App。
|
||||||
|
- 报表配置、报表导出、定时生成和跨维度 BI。
|
||||||
|
|
||||||
|
新增以上能力前，必须先确认主责系统、数据实体、权限、契约和验收口径，不能直接扩展通用 CRUD 页面冒充业务闭环。
|
||||||
|
|
||||||
|
## 9. 现状验收标准
|
||||||
|
|
||||||
|
1. 匿名用户只能访问健康检查和登录；受保护资源缺少有效 JWT 时被拒绝。
|
||||||
|
2. 非 root 角色只能访问已分配菜单及其明确依赖资源，不能通过猜测路径访问同级资源。
|
||||||
|
3. 47 个资源的后端契约、实际路由、前端资源定义和页面加载关系一致。
|
||||||
|
4. 所有表保留自增 `id` 主键；主资源通过 UUID V7 `identity` 对外访问，前端不依赖内部 ID。
|
||||||
|
5. 气站必须先审核再启停，驳回原因和审核人可追溯。
|
||||||
|
6. 智能气阀归属和生命周期变更合法，并自动记录归属历史。
|
||||||
|
7. 合同启用、续签、终止和气瓶解绑只能在合法状态执行，并生成修订或操作记录。
|
||||||
|
8. 配送订单只能沿规定状态机流转；分配、异常、恢复、取消和完成均生成过程记录。
|
||||||
|
9. 钱包充值幂等、余额与流水在同一事务更新；提现只能按审核状态机处理。
|
||||||
|
10. 只读与仅追加资源不存在通用更新、状态修改或删除路由。
|
||||||
|
11. 首页指标来自数据库真实聚合，金额口径和最近 7 日补零正确。
|
||||||
|
12. 修改后端模型或路由后，`contract:sync`、`contract:check`、后端测试和前端构建均通过。
|
||||||
|
|||||||
Reference in New Issue
Block a user