feat(platform): load authorized menus from backend

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

@@ -1,318 +0,0 @@
-# 平台总后台需求分析
-
-## 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` 自增主键，作为物理主键和内部关联键。
-- 平台后台管理的平台、气站、配送、员工和业主账号在初始化、创建和修改密码时仅校验密码不少于 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` 开头；除登录和健康检查外，均要求原始 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` | `/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 组织准入与跨组织变更
-
-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。
-- 智能瓶阀安全事件具备分级、派发、升级、处置、复核和审计闭环。
-- 所有高风险操作、资金审批、跨组织变更及敏感导出均可按操作人、对象、时间和理由追溯。

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

@@ -76,7 +76,7 @@
 - 登录成功返回 JWT、账户 `identity`、显示名称和角色编码。
 - `Authorization` 请求头当前直接传 JWT 原始值，不使用 `Bearer` 前缀。
 - 已登录账户可查看个人资料、角色和菜单编码。
-- 修改密码必须校验当前密码，新密码不少于 12 位。
+- 修改密码必须校验当前密码，新密码不少于 6 位。
 - 系统启动时幂等创建 `root` 管理账户；root 初始密码优先读取环境变量 `HEQI_PLATFORM_ROOT_PASSWORD`。
 
 ### 4.2 RBAC 与数据能力
@@ -198,7 +198,7 @@
 | 资源 | 路径 | 模式 | 已实现能力 |
 | --- | --- | --- | --- |
 | 商品分类 | `/ec_category` | 可写树 | 分类新增、编辑、排序、启停和归档 |
-| 商品 | `/ec_product` | 可写 | 商品编码、名称、售价、库存及状态管理 |
+| 商品管理 | `/ec_product` | 可写 | 商品编码、名称、售价、库存及状态管理 |
 | 商品属性 | `/ec_product_attribute` | 可写 | 商品属性和值管理 |
 | 商品图片 | `/ec_product_image` | 可写 | 图片地址、排序和封面管理 |
 | 购物车 | `/ec_cart` | 只读 | 查询购物车事实 |
@@ -271,24 +271,6 @@
 - 业务动作在详情页按当前业务状态显示；即使前端未隐藏，后端仍必须拒绝非法状态转换。
 - 路由、资源模式和页面能力由后端资源契约校验，任一层缺失时契约审计失败。
 
-## 8. 当前未实现范围
-
-以下能力在总体规划中存在，但当前平台前后端没有完整可验收实现：
-
-- 安全事件中心、告警规则、自动关阀审批、安检整改和复检。
-- 设备遥测实时页面、设备命令下发、命令回执和 MQTT 在线状态。
-- 气站/配送点邀请二维码、扫码归因和服务关系变更审批。
-- 配送员实时定位采集、地图回放、精确轨迹导出审批和轨迹异常识别。
-- 用户 360、跨组织协同时间线和完整敏感访问审计。
-- 文件上传、对象存储签名访问、病毒检测和证据哈希。
-- 支付回调接入、自动对账、自动打款、电子发票和电子合同第三方签署。
-- 全局安全地图、运营规则中心、通知模板、消息任务和触达回执。
-- 独立审计中心、审批中心、导出审计和不可变操作日志查询页面。
-- 生产管理系统、气站管理系统、配送点管理系统、API 中心和两类 Flutter App。
-- 报表配置、报表导出、定时生成和跨维度 BI。
-
-新增以上能力前，必须先确认主责系统、数据实体、权限、契约和验收口径，不能直接扩展通用 CRUD 页面冒充业务闭环。
-
 ## 9. 现状验收标准
 
 1. 匿名用户只能访问健康检查和登录；受保护资源缺少有效 JWT 时被拒绝。

docs/06-气站管理系统需求.md

@@ -1,87 +1,217 @@
-# 气站管理系统需求
+# 气站管理系统需求（规划基线）
 
-## 1. 定位与使用者
+## 1. 文档目的
 
-供气站站长、站内运营、仓管、客服和站点调度人员使用的 Web 管理系统。系统在平台配置的组织、区域、商品和结算政策范围内运行，管理本站日常经营，并可创建和管理归属本站的配送点、服务人员和用户；不能修改全局安全阈值、跨站资金或其他站点数据。
+本文定义气站管理系统的业务范围、角色权限、数据边界、核心流程和规划验收标准，作为后续 `frontend/gas_admin` 及对应后端能力的规划基线。
 
-## 2. 功能范围
+当前仓库尚未实现气站管理系统，本文描述的能力不得认定为已交付，也不得为了复用页面而并入平台总后台。后续实现完成后，应以实际路由、资源契约、权限、状态机和测试反向更新本文。
 
-| 模块 | 功能 | 关键规则 |
+## 2. 系统定位与边界
+
+气站管理系统是气站日常经营工作台，面向站长、站内运营、仓管、订单客服、站点调度和站点财务人员，主责本站库存、燃气配送订单、配送协同、客户服务、邀请注册和经营对账。
+
+气站管理系统不承担以下主责：
+
+- 不创建、审核、冻结或注销平台全局用户账户。
+- 不创建服务人员全局账号，不授予安装维修、安检等安全角色，不审批实名、资质和培训结论。
+- 不创建、迁移、冻结或归档配送点组织主体，不修改平台组织主数据。
+- 不维护电商商品、分类、购物车、商城订单、评价或营销活动。
+- 不维护平台安全规则、设备控制策略或生产质量事实。
+- 不审核提现、修改钱包余额和资金流水、确认平台实际打款或调整平台分账政策。
+- 不查看其他气站及其配送点、人员、用户、订单、库存和经营数据。
+- 不直接关闭平台安全事件、解除安全关阀限制或代替现场人员补造履约证据。
+
+气站需要新增配送点、关联人员、变更人员角色、扩大服务区域、迁移用户服务关系或执行跨站调拨时，只能向平台发起申请，不得在本系统直接生效。
+
+## 3. 角色与权限
+
+### 3.1 角色职责
+
+| 角色 | 可用能力 | 明确禁止 |
 | --- | --- | --- |
-| 站点与人员 | 站点资料、营业时间、服务区、站内账号、服务人员归属与排班 | 账号与数据仅限本组织；跨站调配需平台审批 |
-| 配送点管理 | 创建、编辑、启停本站配送点；负责人、覆盖区域、服务能力、配送仓和配送人员 | 配送点自动归属本站；编码全局唯一；跨站迁移、删除和超范围区域须平台审批 |
-| 工作人员管理 | 创建、导入或审核 App 自主注册的配送员、安装维修员、安检员；角色、资质、培训、打卡、服务范围、接单状态与绩效 | 仅限本站人员；安全相关角色须平台/安全主管审核后可接单；不能授予超出站点授权的角色 |
-| 营销 | 满减券、折扣券、发放、核销、适用范围与统计 | 受平台营销政策和预算控制，券核销可追溯 |
-| 订单与服务 | 订单、安装/维修/安检任务、预约、异常、售后、核销 | 只处理本站订单；高风险安全事件自动同步平台总后台 |
-| 配送轨迹 | 查看本站配送订单的状态时间线、配送轨迹、预计送达、异常与签收证据 | 仅查看本站关联任务；精确位置、回放和导出遵循权限与审计规则 |
-| 用户管理 | 创建/导入线下用户、查看本站用户、地址、设备摘要、服务记录、回访、投诉协同 | 仅限本站服务区及关联订单/设备用户；敏感信息脱敏展示，访问行为审计 |
-| 邀请注册二维码 | 创建、下载、预览、分享、停用和统计气站邀请二维码 | 二维码仅表达受签名的邀请码/链接，不包含手机号、地址等个人信息；扫码成功自动建立本站服务关系 |
-| 对账结算 | 订单、支付、退款、佣金、库存、服务费对账；提现申请 | 差异项不可结算；实际打款由平台财务确认 |
+| 站长 | 查看本站经营概览、审批本站普通经营调整、发起组织和跨站协同申请 | 创建平台主体、授予安全角色、跨站调度、资金终审、修改全局安全规则 |
+| 站内运营 | 维护本站预约容量、服务公告和邀请活动，处理本站燃气配送订单与客户协同 | 维护电商商品或营销活动、直接调整库存余额、查看其他气站数据 |
+| 仓管员 | 执行本站入库、出库、调拨交接、盘点、退回和损耗登记 | 修改订单金额、人员权限、质检结论、资金或安全事件 |
+| 订单客服 | 查看本站订单和必要用户信息，处理预约、售后、投诉及回访 | 编辑用户全局账户、查看完整资金流水、控制设备、修改安全判定 |
+| 站点调度 | 向已关联配送点发布任务需求，协调本站服务任务和异常 | 直接操作配送员现场状态、跨气站派单、补造签收和定位事实 |
+| 站点财务 | 查看本站订单、退款、服务费和结算单，提交对账异议与提现申请 | 审核本人申请、修改流水、调整分账比例、确认平台打款 |
 
-## 3. 配送点管理
+配送员、安装维修员和安检员不使用气站 Web 后台，其接单、定位、检查、安装、维修和取证均在服务端 App 完成，只能访问分配给本人的任务。
 
-气站可在授权的服务区域和配送点数量上限内创建配送点，并负责本站配送点的日常资料和资源维护。创建后，配送点同时出现在配送点管理系统中，但只有本站及平台授权人员可查看和编辑。
+### 3.2 权限规则
 
-| 功能 | 需求与规则 |
+- 服务端必须同时校验角色、气站归属、资源归属、业务状态和数据范围。
+- 站长不自动拥有仓管、财务、客服和安全相关操作权限；角色可组合，但能力独立授权。
+- 库存报损、敏感导出、跨组织协同和高风险售后按阈值进入复核。
+- 精确定位、完整证据和敏感用户信息仅向履行当前职责所必需的角色开放。
+- 前端菜单隐藏和按钮禁用不构成权限控制。
+
+## 4. 技术与数据约定
+
+- 每张表包含 `id bigint` 自增主键、`created_at` 和 `updated_at`。
+- 主表及可独立访问、跨系统引用或审计定位的明细包含 UUID V7 `identity`。
+- HTTP、事件、审计和前端统一使用 `identity`，不得暴露或接受数据库内部 ID。
+- 金额使用最小货币单位整数；订单最终金额、退款和结算结果由服务端计算或读取权威事实。
+- 订单、支付、库存流水、结算、服务记录和安全协同记录不得物理删除。
+- 通用记录状态和订单、库存、售后等业务状态分离；业务状态只能通过专用动作流转。
+- 写操作携带幂等键；离线或异步数据保留原始业务时间和服务端接收时间。
+
+## 5. 规划功能域
+
+### 5.1 气站资料与经营设置
+
+气站只读展示平台维护的组织编码、主体名称、证照状态、所属区域、服务区域和组织状态。
+
+站长可维护本站营业时段、值班联系方式、预约容量、临时接单状态和服务公告。主体名称、证照、地址、服务区域、冻结和归档等组织主数据变更必须向平台提交申请。
+
+| 能力 | 规则 |
 | --- | --- |
-| 创建配送点 | 填写配送点名称、负责人、地址/坐标、营业时间、覆盖区域、配送能力、配送仓和联系方式；平台生成全局唯一配送点编号 |
-| 审核与启用 | 首个配送点、扩大服务区域、增加高风险商品配送能力等场景进入平台审核；审核通过后才可参与自动派单 |
-| 配送资源 | 配置车辆/工具、日配送上限、预约窗口、可配送商品、配送人员和库存仓；配置变更保留生效时间和历史版本 |
-| 运营管理 | 查看待配送、配送中、签收、异常、超时、配送员负载、库存和成本；可发起改派、暂停接单和恢复接单 |
-| 生命周期 | 草稿 -> 待审核 -> 启用 -> 暂停接单/冻结 -> 归档；存在在途订单、库存或未结算款项时不得归档 |
+| 营业设置 | 在平台允许范围内维护营业时段、预约容量和暂停接单原因 |
+| 服务能力 | 查看平台授予的配送、安装维修和安检能力，不得自行扩权 |
+| 站内账号 | 查看已关联本站的后台账号和角色；新增、冻结及角色变更走平台申请 |
+| 组织变更 | 地址、区域、主体、冻结、归档和跨站迁移均由平台审核 |
 
-## 4. 服务人员管理
+### 5.2 站内库存
 
-气站可为本站创建和维护服务人员，统一管理配送、安装维修和安检三类角色。人员登录服务端 App 后只看到本角色、本站和本人服务区域内的任务。
+| 资源 | 能力 | 关键规则 |
+| --- | --- | --- |
+| 入库 | 接收生产交付、退回或经批准的跨站调拨 | 必须关联来源、批次、交接和质检状态 |
+| 出库 | 按订单、配送点调拨或批准的业务单据出库 | 无有效业务单据不得出库 |
+| 配送点调拨 | 向已归属本站的配送点创建调拨需求并确认交接 | 配送点接收后由配送点库存主责 |
+| 退回与损耗 | 登记拒收、货损、空瓶、维修和报废去向 | 超阈值损耗需复核，不得覆盖原流水 |
+| 盘点 | 创建盘点、记录实盘、差异和处理申请 | 库存余额不可直接编辑 |
 
-| 功能 | 需求与规则 |
+库存变化必须由不可变流水驱动，并保留设备/气瓶、批次、数量、来源、去向、操作者和业务依据。
+
+### 5.3 配送点协同
+
+气站只能查看平台已归属本站的配送点及其服务能力、接单状态、容量和履约汇总。
+
+- 向已启用配送点发布本站配送需求和预约约束。
+- 查看配送点确认、任务分配、配送进度、异常和交接结果。
+- 暂停向存在容量、库存或质控风险的配送点继续派发本站任务，并提交处理原因。
+- 新增配送点、修改主体资料、扩大覆盖区域、冻结、归档和跨站迁移只能向平台申请。
+- 气站不能直接登录配送点后台代替调度，也不能修改配送员 App 产生的接单、定位和签收事实。
+
+### 5.4 人员协同
+
+| 能力 | 规则 |
 | --- | --- |
-| 创建、导入与自主申请 | 录入实名资料、联系方式、紧急联系人、所属配送点/站点、服务区域和入职信息；接收 App 自主注册申请并审核角色、材料与来源；手机号重复时提示关联现有人员或提交平台合并申请 |
-| 角色配置 | 可授予配送员、安装维修员、安检员角色；分别维护证书、培训、技能、保险、设备/车辆能力和到期时间 |
-| 审核与生效 | 配送角色可按平台规则自动/人工审核；安装维修、安检等安全相关角色须平台或安全主管审核通过后才能接收任务 |
-| 作业前置与调度 | 查看每日培训、上/下班、授权设备、定位权限和离线补传异常；设置班次、最大负载、预约时段和服务区域；任一作业前置不满足时不可派单或开始任务 |
-| 绩效与处置 | 查看任务、时效、评分、投诉、违规、收益和分账；可发起冻结、离职、调动申请，最终生效遵循平台审批规则 |
+| 人员名册 | 只显示已由平台关联本站或本站配送点的人员 |
+| 作业能力 | 查看角色、资质、培训、服务区域、在岗和可接单校验结果 |
+| 任务协调 | 只能选择已授权且满足作业前置的人员或向配送点发布需求 |
+| 绩效视图 | 查看与本站任务相关的时效、质量、投诉和异常，不展示无关个人数据 |
+| 人员变更 | 新增、角色授予、资质审批、冻结、离职和跨站调动只能发起平台申请 |
 
-## 5. 用户管理
+气站不得自行把资质改为有效，不得授予安装维修、安检等安全角色，也不得绕过配送点直接修改人员现场任务状态。
 
-气站管理与本站服务相关的用户，不取代用户自主注册和平台全局账户管理。气站可为线下客户建档/邀请注册，并维护服务关系、地址、设备和订单协同信息。
+### 5.5 燃气配送订单与服务
 
-| 功能 | 需求与规则 |
+- 查看和处理归属本站的燃气配送订单、配送需求、安装维修需求、预约、售后和投诉。
+- 后端依据有效合同、气瓶、库存和服务费规则读取或计算订单金额，不接受前端自行决定最终金额。
+- 订单取消、售后和异常处理遵循专用状态机，并保留原因、审批和前后状态。
+- 气站可向配送点发布履约需求，但配送点内部人员分配由配送点主责。
+- 安装、维修、安检、随瓶检查、签收和现场收款确认以服务端 App 事实为准。
+- 高风险安全问题必须上报平台安全域；气站可以协同处置，但不能改变风险等级、关闭事件或解除设备控制限制。
+
+### 5.6 客户服务视图
+
+气站只管理与本站经营和服务相关的客户关系，不拥有用户全局账户控制权。
+
+- 查看本站订单所需的联系人、脱敏手机号、服务地址、预约、售后和投诉记录。
+- 查看影响本站服务的设备、安全限制和服务关系摘要。
+- 创建本站回访、客服联系记录和经授权的服务通知。
+- 服务通知必须符合用户授权和平台频控。
+- 资料错误、重复用户、关系解除和注销只能提交平台处理申请。
+
+气站不得创建或编辑用户全局账户、冻结登录、查看完整钱包和支付流水、修改其他气站服务关系或直接限制设备控制。
+
+### 5.7 邀请注册
+
+气站可在平台授权的服务区域内创建和管理本站邀请注册二维码，用于门店展示、社区服务和线下客户注册。
+
+| 能力 | 规则 |
 | --- | --- |
-| 创建与关联 | 为线下客户创建待激活档案或发送注册邀请；填写姓名、手机号、服务地址和来源。已存在的平台用户只允许关联本站服务关系，不得重复建账号 |
-| 用户列表 | 按服务区、设备状态、订单、安检状态、投诉、活跃度和注册来源筛选本站用户；用户编号为平台全局唯一编号 |
-| 用户 360 | 查看经授权的地址、设备摘要、安全事件、安检整改、订单、预约、售后和客服记录；支付完整流水、其他站点服务数据按权限隐藏 |
-| 服务运营 | 创建预约、发起安检/维修/配送需求、回访、处理投诉、发送站点公告或营销触达；营销须遵守用户授权与平台频控策略 |
-| 账户处置 | 可发起资料纠错、重复用户合并、服务关系解除、风险标记和注销协办；冻结登录、限制设备控制、正式注销由平台按权限审批 |
+| 创建邀请 | 配置本站、服务区域、有效期、使用次数和邀请来源 |
+| 二维码操作 | 生成、预览、下载、复制注册链接、停用和重新生成 |
+| 注册处理 | 新用户完成平台统一注册；已有用户登录确认后只建立本站服务关系 |
+| 范围校验 | 地址超出本站服务区域时不得建立错误归属 |
+| 统计 | 查看扫码、注册、服务关系建立和失败原因，不展示无关用户隐私 |
 
-### 5.1 气站邀请注册二维码
+二维码只承载平台签名、可撤销且可过期的邀请码或短链接，不包含管理员账号、用户资料或接口密钥。重复扫码不得覆盖既有服务关系；服务关系变更必须提示影响并取得用户确认。
 
-气站可为线下推广、门店展示、业务员推广或特定服务区域创建邀请注册二维码。用户使用用户端 App 或手机浏览器扫码后，进入注册/登录和服务地址确认流程；完成后自动建立用户与该气站的服务关系。
+### 5.8 对账、结算与提现申请
 
-| 配置项 | 说明 |
-| --- | --- |
-| 邀请类型 | 通用站点码、活动码、业务员专属码、服务区域码；专属码可用于归因和绩效统计 |
-| 有效范围 | 关联气站、可选服务区域、可选商品/活动、最大使用次数、有效期和适用注册来源 |
-| 二维码操作 | 生成、预览、下载 PNG/SVG、复制注册链接、停用、重新生成和查看扫码/注册/转化统计 |
-| 扫码结果 | 新用户注册后建档；已有平台用户登录确认后建立服务关系；服务地址不在范围内时提示并不得错误归属 |
-| 使用状态 | 草稿 -> 启用 -> 已过期/已用尽/已停用；已停用二维码不可注册，历史归因数据保留 |
+- 查看本站燃气配送订单、支付、配送服务费、库存交接和平台结算快照。
+- 按结算周期核对业务事实并提交差异、凭证和处理意见。
+- 查看平台生成的结算单及异议处理状态。
+- 在满足余额、实名、风控和未决差异条件时提交本站提现申请。
 
-二维码由平台生成带签名的短期或可撤销邀请令牌，不能把气站管理员账号、用户资料或可直接调用接口的固定密钥编码到二维码中。用户注册、服务关系建立和归因均需记录二维码 ID、来源、时间和结果。
+站点财务不得创建或修改资金流水、调整钱包余额、审核本站提现、调整分账比例或确认实际打款。
 
-## 6. 站点与配送点协作
+### 5.9 经营报表
 
-- 站点创建或确认需配送的任务，向配送点发布履约需求；配送点确认人员和配送计划后回传状态。
-- 商品从站点仓转至配送点仓时，创建调拨单、出入库和签收记录；在途库存独立核算。
-- 配送异常、货损、拒收、退货回流均必须同步订单、库存和资金待处理状态。
-- 站点可查看本站任务的配送轨迹质量、随瓶安检、气瓶扫码/蓝牙识别、收款确认、空瓶回收与异常对账状态；现场原始证据只能由服务端 App 提交，后台不得补录为已完成。
+气站可查看本站范围内的燃气配送订单数量与金额、库存周转、配送时效、售后、投诉、邀请转化和结算差异。
 
-## 7. 数据边界、审核与审计
+报表不得包含其他气站明细、平台总账、无关用户隐私或完整人员收入。导出按权限和用途审计，金额口径应与订单及资金事实一致。
 
-- 气站只能创建和管理归属本站、处于本站服务区内的配送点、服务人员和用户服务关系；平台总后台保留全局查看、审核、冻结、跨组织调配和主数据纠错权。
-- 配送点、人员、用户均使用平台全局唯一编号。气站删除操作采用归档/停用，不得物理删除历史订单、设备、安全事件、库存或资金记录。
-- 新建主体、资料修改、角色授予、用户关联、派单、改派、冻结/解冻、导入/导出均记录操作人、站点、前后值、原因、时间和关联对象；敏感字段显示和导出受权限控制。
-- 跨站点调拨库存、转移配送点、调动服务人员、迁移用户服务关系，须由源站、目标站和平台按流程确认，并校验未完成任务、在途库存、安全事件与结算状态。
+## 6. 核心流程
 
-## 8. 扩展能力
+### 6.1 订单至配送
 
-- 客户分群、区域促销、订阅式巡检、门店自提、站点经营报表、库存采购与供应商协同。
+```text
+接收本站燃气配送订单 -> 校验合同、气瓶、库存和预约
+-> 生成配送需求 -> 选择已归属本站的配送点
+-> 配送点调度与 App 履约 -> 签收/异常 -> 库存与对账
+```
+
+- 无可用配送点、库存不足或超出服务区域时进入待协调，不得伪造已分配。
+- 气站只能查看配送进度和处理上级协同事项，不能代替配送点指定普通配送员。
+- 配送异常、拒收、货损和退回必须同步订单、库存和待对账状态。
+
+### 6.2 库存调拨
+
+```text
+创建本站业务调拨单 -> 站内仓出库 -> 在途
+-> 配送点核对接收 -> 差异确认 -> 双方库存流水完成
+```
+
+跨气站调拨必须经平台审批；源站、目标站和平台确认前，不得直接改变目标库存余额。
+
+### 6.3 售后与安全协同
+
+```text
+用户诉求/履约异常 -> 气站受理 -> 判断普通售后或安全问题
+-> 普通售后按订单流程处理
+-> 安全问题上报平台并协同现场任务 -> 等待平台结论
+```
+
+气站不能把未处理的安全问题降级为普通售后，也不能因订单完成而关闭安全事件。
+
+## 7. 审计与安全
+
+- 邀请创建与停用、订单动作、库存交接、调拨、售后、对账异议、提现申请和敏感导出必须审计。
+- 手机号、地址、证件、定位、照片、视频、合同和资金信息按最小权限脱敏或受控访问。
+- 气站数据范围至少包含 `gas_basic_identity`、资源归属和订单/任务关系校验。
+- 所有气站角色均不能修改原始支付、钱包流水、现场证据、轨迹、安全事件和设备命令事实。
+- 跨站、跨配送点、组织主数据和高风险业务操作必须记录申请人、审批人、原因、前后状态和结果。
+- 离线补传保留原始采集时间、服务端接收时间、操作者、任务、来源、完整性标记和幂等键。
+
+## 8. 未实现范围
+
+当前仓库不存在 `frontend/gas_admin` 及其独立业务实现。站内库存、配送协同、燃气配送订单、客户服务、邀请注册、站点对账和提现申请均属于规划能力。
+
+电商、全局组织管理、人员与用户账号、跨站调配、平台资金审核、全局安全规则、设备控制和生产质量不属于气站后台建设范围。
+
+## 9. 规划验收标准
+
+1. 所有页面和接口只返回当前气站及其业务范围内的数据。
+2. 气站不能创建全局用户、人员或配送点主体，不能授予安全角色或修改资质结论。
+3. 气站邀请二维码只能在授权服务区域内生效，不能重复创建用户或覆盖既有服务关系。
+4. 库存变化由入库、出库、调拨、退回和盘点流水驱动，余额不可直接编辑。
+5. 配送点内部调度和服务端 App 履约事实不能由气站后台代填或修改。
+6. 用户账户、钱包、支付、安全事件和设备控制限制不能由气站直接修改。
+7. 气站只能提交对账异议和提现申请，不能审核提现、修改资金流水或确认打款。
+8. 跨站调拨、组织主数据、人员角色和用户关系变更必须走平台申请。
+9. 敏感字段和导出按权限控制并完整审计。
+10. 状态机、数据范围、幂等和越权场景具有服务端测试。

docs/07-配送点管理系统需求.md

@@ -1,82 +1,183 @@
-# 配送点管理系统需求
+# 配送点管理系统需求（规划基线）
 
-## 1. 定位与使用者
+## 1. 文档目的
 
-配送点管理系统服务配送点负责人、调度员、仓管和配送质控人员，负责最后一公里配送资源和配送库存。在所属气站及平台授权范围内，配送点还可管理本点服务人员和用户服务关系。它不管理生产批次主档，不处理平台总账，也不调整可燃气体安全规则。
+本文定义配送点管理系统的业务范围、角色权限、数据边界、核心流程和验收口径，作为后续 `frontend/delivery_admin` 及对应后端能力的规划基线。
 
-## 2. 功能范围
+当前仓库尚未实现配送点管理系统，本文描述的能力不得认定为已交付，也不得为了复用页面而塞入平台总后台。后续落地时应以实际路由、资源契约、权限和测试反向更新本文。
 
-| 模块 | 功能 |
+## 2. 系统定位与边界
+
+配送点管理系统是气站下属配送组织的日常履约工作台，面向配送点负责人、调度员、仓管员和配送质控人员，主责本点配送任务、配送仓库存、人员当班能力、轨迹异常和交接质控。
+
+配送点管理系统不承担以下主责：
+
+- 不创建、审核或注销平台全局用户账户。
+- 不创建服务人员全局账号，不授予安装维修、安检等安全角色，不审批实名、资质或培训结论。
+- 不维护电商商品、分类、购物车、商城订单、评价或营销活动。
+- 不维护合同条款、平台安全规则或设备控制策略。
+- 不审核提现、修改资金流水、计算平台分账或确认实际打款。
+- 不管理生产型号、生产批次、出厂质检、设备证书或固件发布。
+- 不查看其他配送点、其他气站或与本点履约无关的用户和人员数据。
+
+配送点需要新增人员、变更人员角色、调整覆盖区域、解除用户服务关系或执行跨点调拨时，只能向所属气站或平台发起申请，不得在本系统直接生效。
+
+## 3. 角色与权限
+
+### 3.1 角色职责
+
+| 角色 | 可用能力 | 明确禁止 |
+| --- | --- | --- |
+| 配送点负责人 | 查看本点运营概览、安排本点班次、管理本点邀请、审批本点普通改派和库存盘点差异、发起组织变更申请 | 创建平台账号、授予安全角色、跨点调度、资金审核、修改安全规则 |
+| 调度员 | 查看本点可调度人员、分配与改派配送任务、处理时效和轨迹异常 | 修改人员身份/资质、补造现场证据、修改订单金额、调度其他配送点人员 |
+| 仓管员 | 执行本点调拨接收、入库、拣货、出库、退回、盘点和损耗登记 | 修改订单状态、质检结论、资金数据或其他仓库存 |
+| 配送质控人员 | 查看本点签收、拒收、货损、随瓶安检和轨迹质量，提交复核结论 | 修改原始照片、视频、签名、定位或收款事实，直接关闭平台安全事件 |
+
+配送员不使用 Web 配送点后台，其接单、定位、扫码、随瓶安检、签收和现场取证均在服务端 App 完成，只能访问分配给本人的任务。
+
+### 3.2 权限规则
+
+- 权限必须由服务端同时校验角色、配送点归属、任务归属和数据状态。
+- 配送点负责人不能自动获得仓管、调度或质控的全部操作能力；角色可组合，但每项能力独立授权。
+- 高风险改派、跨点支援、库存报损、精确轨迹回放和敏感数据导出需要上级授权或审批。
+- 前端菜单隐藏和按钮禁用不构成权限控制。
+
+## 4. 技术与数据约定
+
+- 每张表包含 `id bigint` 自增主键、`created_at` 和 `updated_at`。
+- 主表及需要被接口单独访问的明细表包含 UUID V7 `identity`。
+- HTTP、事件、审计和前端只使用 `identity`；不得暴露数据库内部 ID。
+- 金额使用最小货币单位整数。配送点只能读取订单和结算快照，不得自行重算最终应收、人员收益或平台分账。
+- 订单、任务、库存流水、轨迹、签收证据和质控结论不得物理删除。
+- 现场证据由服务端 App 产生，后台只能查看、标记异常或提交复核，不得代替现场人员补录为已完成。
+
+## 5. 规划功能域
+
+### 5.1 配送点资料
+
+配送点仅查看平台或气站维护的组织编码、所属气站、地址、覆盖区域、联系人、营业状态和能力上限。
+
+本点负责人可维护营业时段、值班联系方式、预约容量和临时接单状态。地址、覆盖区域、主体归属、组织冻结和归档等主数据变更必须发起申请，由所属气站或平台审核生效。
+
+### 5.2 当班人员与能力
+
+| 能力 | 规则 |
 | --- | --- |
-| 配送点基础资料 | 配送点地址、覆盖区域、营业时段、车辆、容量、联系人和状态 |
-| 工作人员管理 | 创建、导入或审核 App 自主注册的配送员、安装维修员、安检员的本站/本点归属、资质、培训、打卡、班次、可接单状态、负载、评分和异常率；安全相关角色须经平台审核后生效 |
-| 用户管理 | 创建线下用户待激活档案、邀请注册、管理本点服务用户、地址、配送偏好、订单、预约、回访与投诉协同 |
-| 邀请注册二维码 | 创建、下载、分享、停用和分析本点邀请注册二维码；扫码注册后自动建立本点用户服务关系 |
-| 订单调度 | 接收站点/平台配送需求，自动分单、人工改派、预约、路线、配送轨迹、时效预警 |
-| 配送仓 | 调拨入库、出库、拣货、交接、在途、盘点、退回、损耗与批次追溯 |
-| 履约质控 | 到达/签收证据、异常审核、拒收/货损、客服协同、配送服务评分 |
-| 运营对账 | 按配送任务核算服务费、人员收益、车辆成本、库存差异和站点结算数据 |
+| 人员名册 | 只显示已由气站或平台关联至本点的人员，不提供创建账号、删除账号或授予角色功能 |
+| 当班状态 | 查看上/下班、可接单、当前负载、定位可用性和任务占用情况 |
+| 班次安排 | 在人员已授权角色、有效资质和服务区域内安排本点班次 |
+| 作业前置 | 只读展示培训、资质、车辆、工具和授权设备校验结果；不允许配送点人员自行改为“已通过” |
+| 组织变更 | 离职、冻结、角色变更、跨点支援和调动只能发起申请，由气站或平台处理 |
 
-## 3. 服务人员管理
+配送点不能查看人员完整身份证件、银行卡、平台级违规档案或与本点任务无关的个人信息。
 
-配送点可在平台与所属气站配置的角色、服务区域和人员数量上限内，创建、维护和调度本点服务人员。人员使用服务端 App 时，只能看到本人角色、本点/本站和授权服务区域内的任务。
+### 5.3 配送任务调度
 
-| 功能 | 需求与规则 |
+- 接收所属气站或平台下发至本点的待配送任务。
+- 按覆盖区域、预约窗口、人员当班状态、配送角色、车辆能力、当前负载、库存和风险限制进行分配。
+- 普通改派仅限本点已授权且在岗人员，必须填写原因并保留原分配记录。
+- 跨点改派、超区域履约和高风险任务转移只能发起上级协调申请。
+- 配送点不得创建交易订单、改写订单最终金额或跳过订单状态机。
+- 配送任务状态以服务端校验和 App 履约事实为准，后台不能直接把任务改为已到达、已签收或已完成。
+
+### 5.4 配送仓
+
+| 资源 | 能力 | 关键规则 |
+| --- | --- | --- |
+| 调拨接收 | 核对所属气站发出的调拨单并确认收货差异 | 不得自行创建跨气站调拨 |
+| 入库与批次 | 记录实收数量、批次、扫码结果和异常 | 来源批次只读，不得修改生产事实 |
+| 拣货与出库 | 按已分配配送任务拣货、复核和交接 | 无有效任务不得出库 |
+| 在途与退回 | 跟踪配送员交接、拒收、空瓶和货损退回 | 在途记录不可覆盖或删除 |
+| 盘点与损耗 | 创建盘点、登记差异和损耗原因 | 超阈值差异需负责人及所属气站复核 |
+
+库存扣减、回流和冻结必须由订单、任务和交接事实驱动，不能由页面任意修改库存余额。
+
+### 5.5 履约与轨迹质控
+
+- 查看本点任务的分配、接单、出发、位置上报、到达、签收、异常、改派和取消时间线。
+- 识别长时间无位置、偏离授权区域、异常速度、轨迹中断和签收前未到达等异常。
+- 查看气瓶/设备扫码、随瓶安检、照片/视频、用户签名或签收码、收款确认和空瓶回收完成情况。
+- 质控人员可标记材料缺失、数据冲突或疑似造假，并退回任务补充合法证据或上报气站/平台。
+- 改派后旧任务轨迹只读保留，新任务单独采集，不覆盖原责任人和时间线。
+- 精确坐标、完整回放和导出按最小权限控制并记录用途；普通仓管和无关人员不得访问。
+
+### 5.6 用户履约视图
+
+配送点只读取完成本点任务所必需的用户信息：
+
+- 当前任务联系人、脱敏手机号、配送地址、预约时段和交接要求。
+- 与本点任务相关的订单、售后、投诉和配送偏好。
+- 会影响本次履约的设备或安全限制摘要。
+
+配送点不得创建或编辑用户全局账户、查看完整钱包和支付流水、修改用户地址主档、冻结账号、注销用户或直接变更服务关系。发现资料错误时只能提交纠错或关系变更申请。
+
+### 5.7 邀请注册
+
+配送点可在平台和所属气站授权的服务区域内创建和管理本点邀请注册二维码，用于社区服务、自提点和线下客户注册。
+
+| 能力 | 规则 |
 | --- | --- |
-| 创建、关联与自主申请 | 录入姓名、手机号、实名资料、紧急联系人、服务区域、所属气站/配送点和入职信息；审核 App 自主注册申请的角色、材料与来源；已有平台人员可申请关联到本点，不重复创建账号 |
-| 角色与能力 | 配置配送、安装维修、安检角色，以及车辆、工具、技能、证书、培训、保险和有效期；角色能力独立生效 |
-| 审核与启用 | 配送角色按平台规则审核；安装维修和安检等安全相关角色必须经平台或安全主管审核后才可接收对应任务 |
-| 作业前置与调度 | 查看每日培训、上/下班、授权设备、定位权限和离线补传异常；设置班次、最大负载、预约窗口、服务区域和可服务商品/设备型号；任一作业前置不满足时不可派单或开始任务 |
-| 绩效与处置 | 查看任务时效、签收/完工质量、评分、投诉、违规、收益和分账；可发起离职、冻结、跨点支援或调动申请，最终生效按气站/平台审批规则执行 |
+| 创建邀请 | 配置本配送点、所属气站、服务区域、有效期、使用次数和邀请来源 |
+| 二维码操作 | 生成、预览、下载、复制注册链接、停用和重新生成 |
+| 注册处理 | 新用户完成平台统一注册；已有用户登录确认后只建立本点服务关系 |
+| 范围校验 | 地址不在本点配送范围时不得建立错误归属 |
+| 统计 | 查看扫码、注册、服务关系建立和失败原因，不展示无关用户隐私 |
 
-## 4. 用户管理
+二维码只承载平台签名、可撤销且可过期的邀请码或短链接，不包含配送点账号、用户资料、库存或接口密钥。重复扫码不得覆盖既有服务关系；已有关系变更必须提示影响并取得用户确认。
 
-配送点管理的是与本点履约相关的用户及其服务关系，不拥有平台全局用户账户的完全控制权。用户可自主注册；配送点也可为线下客户创建待激活档案或发送注册邀请。
+### 5.8 对账视图
 
-| 功能 | 需求与规则 |
-| --- | --- |
-| 创建与关联 | 录入姓名、手机号、服务地址、来源和配送偏好；手机号对应已有平台账户时，只建立服务关系，不得创建重复账户 |
-| 用户列表 | 按配送区域、订单状态、预约时间、设备/安全提示、服务频次、投诉和来源筛选；仅展示本点服务范围内用户 |
-| 用户服务视图 | 查看完成配送所需的地址、联系人、订单、预约、交接要求、售后和投诉记录；手机号、地址、设备和资金数据按字段权限脱敏 |
-| 服务运营 | 创建配送预约、联系记录、回访、配送异常、售后协同和经授权的服务通知；营销触达必须取得用户授权并遵守平台频控 |
-| 账户处置 | 可发起资料纠错、重复用户合并、服务关系解除和风险标记；账号冻结、设备控制限制和正式注销由平台审批处理 |
+- 按本点任务查看订单金额快照、配送服务费快照、库存交接和异常差异。
+- 对缺少签收、货损、拒收、收款不一致或库存不平的任务提交对账异议。
+- 查看所属气站或平台生成的结算结果及异议处理状态。
 
-### 4.1 配送点邀请注册二维码
+配送点不得创建资金流水、调整余额、审核提现、确认打款或修改分账比例。
 
-配送点可在授权服务区域内创建邀请注册二维码，用于配送员推广、社区活动、自提点或线下客户建档。用户扫码后完成注册/登录和地址确认，系统将用户服务关系归属到该配送点，并可按规则同时关联所属气站。
+## 6. 核心流程
 
-| 配置项 | 说明 |
-| --- | --- |
-| 邀请类型 | 通用配送点码、配送员专属码、社区/自提点码、活动码；专属码用于邀请来源和绩效归因 |
-| 有效范围 | 关联配送点、所属气站、可选覆盖区域、最大使用次数、有效期、适用活动和可配送服务 |
-| 二维码操作 | 生成、预览、下载 PNG/SVG、复制注册链接、停用、重新生成和查看扫码/注册/首单转化统计 |
-| 扫码结果 | 新用户进入注册；已有用户登录确认后建立服务关系；地址不在配送范围时提示用户选择有效配送点或联系气站 |
-| 归属规则 | 用户通过配送点码注册时，配送点为默认履约服务点；后续变更遵循服务区域、订单和用户确认规则，不因重复扫码覆盖原服务关系 |
+### 6.1 调度与履约
 
-二维码使用平台签名的邀请码或短链接，令牌可过期、达到次数上限或被配送点/平台停用。二维码中不得包含用户隐私、人员账号、库存或接口密钥；扫码、注册、服务关系建立、归因和异常拦截均须审计。
+```text
+接收配送需求 -> 校验本点范围和库存 -> 选择已授权当班配送员
+-> 分配任务 -> App 接单与履约 -> 签收/异常 -> 质控检查 -> 回传气站
+```
 
-## 5. 调度规则
+- 校验失败时进入待协调，不得通过手工改状态绕过。
+- 配送员未接单、定位异常或超时，可在本点范围内回收并改派。
+- 现场不合格或触发安全规则时必须上报安全事件，配送点不能自行解除设备或订单限制。
 
-- 分单同时考虑覆盖区域、预约窗口、配送员上班状态、车辆/载重、技能、当前负载、库存可用性和风险等级。
-- 高优先级安全相关配送任务可插单，但应记录影响订单、调度人或规则版本。
-- 配送员未在时限内接单、长期无定位/无进度、异常率超过阈值时触发回收、改派或人工干预。
-- 签收成功才扣减配送点实际库存；发生拒收或货损时先冻结对应库存与结算，待审核后再回流或报损。
-- 配送完成前，调度审核视图必须显示到达校验、气瓶扫码/蓝牙识别、随瓶安检、照片/视频、签收、收款确认和空瓶回收的完成或异常状态；后台只能审核异常，不能补造现场证据。
+### 6.2 库存交接
 
-### 配送轨迹管理
+```text
+气站调拨出库 -> 配送点核对接收 -> 任务拣货 -> 配送员交接
+-> 签收扣减 / 拒收退回 / 货损冻结 -> 盘点与对账
+```
 
-- 调度员可在配送任务详情查看轨迹地图和事件时间线：分配、接单、出发、位置点、到达、签收、异常、改派和取消；支持按订单、配送员、配送区域、时间筛选。
-- 轨迹点显示定位时间、接收时间、坐标、精度、来源、任务状态和异常标记。系统识别长时间无位置、偏离服务区域、异常速度、轨迹中断和签收前未到达等情况，并创建调度提醒。
-- 轨迹仅用于订单履约、时效分析、客户争议和安全管理。配送点管理员只能查看本点任务；导出、回放和精确坐标访问受权限、审批和审计控制。
-- 改派后旧任务轨迹只读保留，新任务独立采集；订单页面按时间串联两段任务，确保轨迹和责任人可追溯。
+每次交接均保留操作者、时间、任务、批次、数量、来源、去向和差异原因。
 
-## 6. 数据边界、审核与审计
+## 7. 审计与安全
 
-- 配送点只能管理归属本点的服务人员，以及本点覆盖区域、订单或预约关联的用户服务关系；不得查看其他配送点、气站或平台无关用户的数据。
-- 人员、用户、配送点均使用平台全局唯一编号。删除采用停用、归档或解除服务关系，不能物理删除历史订单、签收证据、资金、设备或安全记录。
-- 新增/编辑人员、授予角色、变更班次、用户建档/关联、派单/改派、导入/导出、冻结/解冻等操作，必须记录操作人、配送点、前后值、原因、时间和关联业务对象。
-- 跨配送点调动人员、转移用户服务关系、调拨库存或改变配送区域，须由源配送点、目标配送点、所属气站和平台按权限审批，并校验未完成任务、在途库存、投诉、结算和安全事件。
+- 邀请创建与停用、派单、改派、班次调整、库存交接、盘点差异、质控结论、敏感查看和导出必须审计。
+- 手机号、地址、定位、照片、视频和签名按最小权限脱敏或受控访问。
+- 离线补传保留原始采集时间、服务端接收时间、操作者、任务、来源、完整性标记和幂等键。
+- 任何配送点角色都不能修改原始轨迹、签名、支付、资金流水、安全事件或设备命令事实。
+- 数据范围至少同时包含 `delivery_basic_identity` 和任务归属校验，禁止仅依靠前端筛选。
 
-## 7. 扩展能力
+## 8. 未实现范围
 
-- 路线优化、电子围栏、车辆温湿度/位置、智能柜、自提点、众包配送和配送能力预测。
+当前仓库不存在 `frontend/delivery_admin` 及其独立业务实现。配送点后台、配送仓、调度、质控和本点对账均属于规划能力。
+
+电商、全局用户管理、人员账号与资质审批、跨点调配、平台资金审核、全局安全规则和生产追溯不属于配送点后台建设范围。
+
+## 9. 规划验收标准
+
+1. 所有页面和接口只返回当前配送点及其任务范围内的数据。
+2. 配送点不能创建全局人员或用户账号，不能授予安全角色或修改资质结论。
+3. 配送点邀请二维码只能在授权范围内生效，不能重复创建用户或覆盖既有服务关系。
+4. 调度只能选择已关联本点、角色有效、资质有效且在岗的配送员。
+5. 后台不能补造到达、签收、定位、照片、视频、扫码和收款事实。
+6. 跨点改派、跨区域履约和组织主数据变更必须走上级申请。
+7. 库存变化由调拨、任务和交接流水驱动，余额不可直接编辑。
+8. 配送点只能提出对账异议，不能修改资金流水、分账或提现状态。
+9. 敏感字段、精确轨迹和导出按权限控制并完整审计。
+10. 状态机、数据范围、幂等和越权场景具有服务端测试。

docs/08-生产管理系统需求.md

@@ -1,42 +1,194 @@
-# 生产管理系统需求
+# 生产管理系统需求（规划基线）
 
-## 1. 定位与使用者
+## 1. 文档目的
 
-生产管理系统用于智能瓶阀及关联配件的生产、质量、设备身份和出厂追溯。使用者包括生产计划员、产线操作员、质检员、仓管、售后质量人员和生产管理员。系统将合格设备安全地登记到 IoT 平台，但不承担用户绑定、订单履约和平台安全运营。
+本文定义生产管理系统的职责边界、角色权限、数据模型原则、生产与质检流程、设备身份安全和规划验收标准，作为后续 `frontend/product_admin` 及对应后端能力的规划基线。
 
-## 2. 功能范围
+当前仓库尚未实现生产管理系统。本文描述的是目标能力，不代表现有平台总后台已经交付，也不得通过在平台后台增加通用 CRUD 页面冒充生产闭环。
 
-| 模块 | 功能 | 关键规则 |
+## 2. 系统定位与边界
+
+生产管理系统主责智能瓶阀及关联配件的型号执行、生产计划、工序、序列号、设备身份注入、质量检验、成品仓储、出厂和质量追溯。
+
+生产管理系统不承担以下主责：
+
+- 不创建或管理用户、气站、配送点和服务人员账号。
+- 不建立用户设备绑定，不处理商城订单、配送任务、用户钱包或支付。
+- 不处理平台告警运营、安检整改、远程开关阀或设备控制授权。
+- 不修改平台已发布的安全规则、商品价格、合同或结算政策。
+- 不直接向气站或配送点业务库写库存事实，只通过出厂/调拨契约交付。
+- 不允许任何生产角色查看与生产质量无关的用户隐私、交易和定位数据。
+
+设备型号、IoT 能力定义、固件正式发布和设备召回策略需要平台设备/安全主责方审批；生产系统负责执行已批准版本并形成可追溯事实。
+
+## 3. 角色与权限
+
+### 3.1 角色职责
+
+| 角色 | 可用能力 | 明确禁止 |
 | --- | --- | --- |
-| 产品与物料 | 设备型号、BOM、硬件/固件版本、供应商、物料批次 | 设备模型与 IoT 能力由平台审核后发布 |
-| 生产计划 | 工单、产线、工序、产量、人员、进度与异常 | 生产工单与设备序列号可关联 |
-| 设备身份 | 序列号、二维码、设备证书、密钥注入、MAC/模组信息 | 一机一档；密钥不以明文导出，启用轮换和吊销 |
-| 质量检验 | 来料、过程、出厂检验，压力/密封/通信/开关测试，缺陷与返工 | 未通过出厂检验的设备不得激活或流入销售库存 |
-| 固件管理 | 固件版本、兼容型号、签名、测试、灰度、回滚和升级记录 | 固件发布需审批；生产烧录与在线 OTA 记录可追溯 |
-| 仓储与出厂 | 成品入库、批次、出库、调拨至可燃气体站/配送点、召回 | 流转记录保留生产批次、质检结论与接收方 |
-| 售后质量 | RMA、故障代码、失效分析、批次质量趋势、召回任务 | 可回溯到设备、批次、固件和供应商 |
+| 生产管理员 | 维护本生产单位、产线、班组和本单位角色分配，查看本单位综合进度 | 修改平台全局型号、批准自己提交的高风险发布、查看用户/订单/资金 |
+| 生产计划员 | 根据已批准型号/BOM 创建生产计划和工单、排产、调整数量与计划时间 | 修改 BOM 已发布版本、填写质检结论、放行设备、接触设备私钥 |
+| 产线操作员 | 执行分配工序、扫码领料、记录产量、设备序列号和工序异常 | 修改计划、跳过工序、填写最终质检、报废后恢复设备 |
+| 质检员 | 执行来料、过程和出厂检验，记录原始结果、缺陷和复检 | 修改生产原始记录、批准本人提交的让步放行、删除不合格结果 |
+| 仓管员 | 执行物料和成品收发、库位、盘点、出库交接 | 修改质检结果、将未放行设备转为可出库、修改设备身份状态 |
+| 身份注入操作员 | 在受控工位执行序列号绑定、证书申请和安全注入 | 查看或导出明文私钥、批量复用凭证、批准证书策略 |
+| 售后质量人员 | 处理 RMA、故障归因、批次趋势和召回执行 | 远程控制用户设备、修改用户订单、删除历史质量结论 |
 
-## 3. 设备入网流程
+### 3.2 职责分离
+
+- 计划创建、生产执行、质检判定、成品放行和出库不得由单一普通角色包办。
+- 同一质检员不能单独批准本人发起的让步接收或重大缺陷关闭。
+- 固件签名、设备证书策略、批量吊销和召回发布属于高风险能力，需要独立审批。
+- 生产管理员仅管理本生产单位，不自动拥有平台设备、安全或 IoT 管理权限。
+- 前端按钮、扫码枪配置和工位网络隔离不能替代服务端权限与状态校验。
+
+## 4. 技术与数据约定
+
+- 每张表包含 `id bigint` 自增主键、`created_at` 和 `updated_at`。
+- 主表及可独立访问、跨系统引用或审计定位的明细包含 UUID V7 `identity`。
+- HTTP、事件、日志和跨系统同步使用 `identity`，不暴露内部自增 ID。
+- 设备序列号、生产工单号、批次号、检验单号和 RMA 编号是唯一业务编号，但不能替代物理主键和 `identity`。
+- 生产数量使用整数；测试值必须记录数值、单位、上下限、仪器、校准状态和采集时间。
+- 工序记录、检验原始值、设备身份注入、证书状态、出厂记录和召回记录属于事实数据，不允许物理删除或覆盖。
+- 所有写操作具备幂等键；扫码、自动测试台和离线工位补传必须保留原始采集时间与服务端接收时间。
+
+## 5. 规划功能域
+
+### 5.1 产品执行基线
+
+生产系统读取平台已批准的设备型号、硬件版本、IoT 能力和安全约束，并维护生产执行所需的版本化 BOM、工艺路线、检验规范和包装规范。
+
+| 能力 | 规则 |
+| --- | --- |
+| 型号引用 | 只能选择平台已批准且处于可生产状态的型号 |
+| BOM 版本 | 草稿可编辑；发布后不可覆盖，只能创建新版本 |
+| 工艺路线 | 工序顺序、必做项、工位能力和返工路径版本化 |
+| 检验规范 | 测试项目、上下限、抽检规则和判定规则版本化 |
+| 变更控制 | BOM、工艺和检验规范变更需评审、生效时间和影响批次 |
+
+普通操作员、仓管员和质检员不能发布型号、BOM 或工艺版本。
+
+### 5.2 物料与供应批次
+
+- 维护本单位供应商引用、采购批次、到货数量、批号、有效期和质量状态。
+- 来料必须经过规定检验或获得受控放行，才能进入可领料库存。
+- 不合格物料进入隔离状态，不能通过普通库存调整回到可用。
+- 领料、退料、替代料和批次拆并保留生产工单、操作者和审批依据。
+- 供应商主数据和采购结算若由 ERP 主责，生产系统只同步引用，不重复维护财务事实。
+
+### 5.3 生产计划与工单
+
+```text
+已批准型号/BOM -> 创建计划 -> 下达生产工单 -> 领料
+-> 工序执行 -> 过程检验 -> 完工待检 -> 出厂检验
+```
+
+- 工单记录型号、版本、批次、计划数量、产线、工艺路线和检验规范快照。
+- 已下达工单不能直接替换版本；变更需评估已领料、在制品和已生成设备身份。
+- 产线操作员只能执行分配给本工位、当前状态允许的工序。
+- 跳站、超量生产、序列号重复和未授权返工必须被服务端拒绝。
+- 工序异常形成独立记录，不通过修改原始结果掩盖。
+
+### 5.4 设备身份与安全注入
+
+| 能力 | 关键规则 |
+| --- | --- |
+| 序列号生成 | 按批准规则生成且全局唯一，作废后不得复用 |
+| 二维码 | 只承载设备公开标识或受签名内容，不包含私钥和长期管理令牌 |
+| 证书申请 | 每台设备使用独立身份，记录证书序列号、状态和有效期 |
+| 密钥注入 | 在受控工位或 HSM/安全模块内完成，应用和日志不得获得明文私钥 |
+| 身份绑定 | 序列号、模组标识、硬件版本、证书和生产批次一一关联 |
+| 吊销与换证 | 必须记录原因、审批、操作者和同步结果 |
+
+请求成功不代表注入成功。系统必须记录待处理、执行中、成功、失败和待确认状态，并以安全工位或设备回执为准。
+
+### 5.5 质量检验
+
+- 支持来料检验、过程检验、出厂检验、抽检、复检和返工后检验。
+- 检验至少覆盖适用的压力、密封、通信、开关动作、电源、电池温度、传感器和固件版本。
+- 自动测试结果保留原始数据、测试台、软件版本、仪器校准信息、测试时间和操作者。
+- 不合格项记录缺陷代码、严重度、处置、责任批次和证据。
+- 原始结果不可修改；录入错误通过更正记录和复检结果表达。
+- 未完成必检项、存在未关闭致命缺陷或证书注入失败的设备不得出厂放行。
+
+### 5.6 固件生产使用
+
+生产系统只使用平台已批准、签名有效且与型号兼容的固件版本进行烧录。
+
+- 记录烧录工位、固件哈希、签名校验、设备序列号、时间和结果。
+- 产线人员不能上传或发布正式固件，不能关闭签名校验。
+- 灰度 OTA、在线升级策略和用户设备升级由平台 IoT/设备域主责；生产系统只提供生产烧录与质量追溯数据。
+- 发现固件质量问题时，生产系统提交影响批次和设备清单，由平台决定在线处置策略。
+
+### 5.7 成品仓储与出厂
+
+- 只有完成全部生产工序、出厂检验合格、设备身份有效且状态为已放行的设备才能入成品可用库。
+- 入库、移库、盘点、冻结、出库和交接形成不可变库存流水。
+- 出库关联接收组织、交付单、设备清单、批次、质检结论和交接结果。
+- 生产系统记录“生产方已交付”；气站或配送点接收后的经营库存由其主责系统记录，不能由生产系统直接修改。
+- 运输损坏、接收差异和退回进入异常流程，不得覆盖原出厂记录。
+
+### 5.8 售后质量与召回
+
+- RMA 关联设备序列号、故障现象、固件、生产批次、历史检验和处理结论。
+- 失效分析保留拆检、测试、根因、纠正预防措施和责任批次。
+- 批次质量趋势可生成召回建议，但生产系统不能自行远程停用或控制用户设备。
+- 召回范围和风险等级经平台审批后，生产系统负责设备清单、返厂、复检、维修、报废和替换追踪。
+- 历史质量记录、召回前状态和处置证据不得删除。
+
+## 6. 设备入网与平台同步
 
 ```mermaid
 flowchart LR
-  A[生成序列号和二维码] --> B[安全注入设备身份]
-  B --> C[产线功能与安全测试]
-  C --> D{出厂质检合格}
-  D -->|否| E[返工/报废与原因记录]
-  D -->|是| F[登记设备模型、批次、固件]
-  F --> G[同步平台设备主档并允许激活]
-  G --> H[调拨至站点/配送点或销售库存]
+  A[生成序列号] --> B[绑定硬件与批次]
+  B --> C[安全注入设备身份]
+  C --> D[工序与功能测试]
+  D --> E{出厂检验合格}
+  E -->|否| F[隔离/返工/报废]
+  E -->|是| G[成品放行]
+  G --> H[同步平台设备主档]
+  H --> I{平台确认}
+  I -->|失败| J[异常队列与重试]
+  I -->|成功| K[允许交付和后续激活]
 ```
 
-### 3.1 出厂设备主档同步契约
+向平台同步的最小数据包括：
 
-生产系统向平台设备域同步的最小信息必须包括：设备序列号、二维码状态、设备型号、硬件/固件版本、设备证书状态、生产批次、出厂质检结论、激活资格和同步时间。平台仅允许“质检合格且具备激活资格”的设备进入销售、安装或用户绑定流程。
+- 设备 `identity`、序列号、公开二维码状态和型号。
+- 硬件版本、固件版本、生产工单和生产批次。
+- 设备证书状态与有效期，不包含私钥。
+- 出厂检验结论、放行状态、激活资格和同步时间。
+- 召回、作废、换码、换证和报废状态。
 
-- 设备二维码在出厂、作废、换码、召回时均须同步状态；用户端绑定、服务端 App 安装激活和后台设备查询必须校验该状态。
-- 生产系统不写入用户、订单、服务关系或现场履约事实；发现设备质量问题时通过设备身份、批次和召回任务与平台安全/履约域关联。
-- 同步失败、重复同步、型号/批次不一致或证书失效时进入可追踪异常队列，不得以“已同步”掩盖失败结果。
+同步使用幂等键并记录请求、响应和重试。同步失败、数据冲突或平台未确认时，设备不得被标记为已入网成功。
 
-## 4. 扩展能力
+平台只接受质检合格、身份有效且具备激活资格的设备。生产系统不得同步用户、订单、钱包、服务关系或现场履约事实。
 
-- MES/ERP 集成、供应商质量管理、电子作业指导书、自动测试台、碳足迹、预测性质量分析和召回演练。
+## 7. 审计与安全
+
+- 型号/BOM引用、计划下达、工序执行、返工、检验、放行、注入、出库、RMA 和召回全程审计。
+- 设备私钥不得进入数据库业务字段、接口响应、日志、导出、测试样例或人工下载文件。
+- 身份注入工位采用最小网络权限、设备认证和操作员双重鉴权。
+- 高风险操作记录申请人、审批人、原因、前后状态、设备范围和结果，申请人与最终审批人按规则分离。
+- 自动测试和工位离线补传必须校验幂等、顺序、数据签名和完整性。
+- 生产系统的数据范围至少隔离生产单位、工厂、产线和角色，禁止普通角色跨单位查询。
+
+## 8. 未实现范围
+
+当前仓库不存在 `frontend/product_admin` 及独立生产后端。生产计划、BOM、工艺、设备身份注入、质量检验、成品仓储、RMA 和召回均属于规划能力。
+
+用户绑定、配送履约、平台安全运营、设备远程控制、资金结算和在线 OTA 策略不属于生产管理系统建设范围。
+
+## 9. 规划验收标准
+
+1. 生产角色只能访问所属生产单位、产线和职责范围内的数据。
+2. 计划、执行、质检、放行和出库具备职责分离，普通角色不能一人完成全部高风险环节。
+3. 已发布 BOM、工艺和检验规范不可覆盖，工单保留执行版本快照。
+4. 序列号全局唯一且作废不复用；设备身份、硬件、证书和批次一一对应。
+5. 私钥不以明文进入接口、日志、数据库或导出，注入结果以受控工位回执为准。
+6. 未完成必检项、不合格、身份失败或未获平台确认的设备不能放行、出库或激活。
+7. 原始生产、测试和质检事实不可删除或覆盖，更正和复检形成新记录。
+8. 出厂同步具备幂等、重试、冲突处理和平台确认状态。
+9. 生产系统不能写入用户、订单、资金、服务关系、安全事件或设备控制事实。
+10. 越权、跳站、重复序列号、重复同步、非法放行和密钥泄露场景具有服务端测试。