platforms/docs/10-技术实现规划.md

# 技术实现规划（多端系统架构）

## 1. 架构原则

首期采用“模块化单体 + 独立 Worker/Iot 进程”形态：核心业务在一个 Go 后端仓中按领域清晰分层，HTTP API、异步 Worker 与 IoT 接入可独立部署和弹性扩缩。该方案能以较低复杂度交付跨域闭环，同时为后续按设备安全、交易、履约、资金和通知拆分服务保留边界。

- 所有管理系统统一使用 Vue 3 + TypeScript，减少多套 Web 技术栈的组件、权限和运维成本。
- `sample/front` 是所有 Vue 管理端的前端工程基线；`sample/server` 是 Go 后端工程基线。新项目应沿用其规范、公共能力和质量要求，不应复制后形成不可维护的分叉。
- 所有外部 API 与事件契约版本化；关键业务事件使用可重放的持久化消息，不能依赖 Redis Pub/Sub 的临时广播语义。
- PostgreSQL 保存交易、设备、安全和资金事实；Redis 仅保存缓存、会话、限流、延迟任务与异步事件流，不替代业务事实库。

## 2. 技术选型

| 层级 | 推荐技术 | 用途 |
| --- | --- | --- |
| 用户端 App | Flutter | 用户设备、安全、商城、订单、钱包、消息和个人中心 |
| 服务端 App | Flutter | 安装维修、安检、配送三类工作台；通过角色与能力包控制模块 |
| 平台总后台 | Vue 3 + TypeScript | 全局治理、运营、财务、安全、审计等高密度管理页面 |
| 可燃气体站管理系统 | Vue 3 + TypeScript | 站点商品、订单、服务、库存与经营管理 |
| 配送点管理系统 | Vue 3 + TypeScript | 调度、配送仓、路线、人员和配送运营工作台 |
| 生产管理系统 | Vue 3 + TypeScript | 生产计划、设备身份、质检、批次、固件和出厂追溯 |
| API 中心管理系统 | Vue 3 + TypeScript | API 产品、调用方、凭证、流量、文档与审计门户 |
| 核心后端 | Go | REST/BFF、领域服务、权限、订单、工单、资金、规则执行 |
| IoT 通道 | MQTT（TLS）+ Go 接入服务 | 设备连接、遥测、命令下发、回执、在线状态；协议适配层屏蔽厂商差异 |
| 关系数据 | PostgreSQL | 事务数据、JSONB 扩展字段、地理空间（PostGIS）、分区表和审计 |
| 缓存与任务 | Redis | 限流、会话、幂等、短期状态、延迟任务；关键事实仍落 PostgreSQL |
| 消息/事件 | Redis Streams + Consumer Group | 遥测流、告警、订单状态、通知、对账异步化；使用消费组、重试、死信与幂等消费者保障可恢复处理 |
| 文件与证据 | S3 兼容对象存储（MinIO/云 OSS） | 商品图、安装/安检证据、签收图片、视频和合同；采用短期签名 URL 与生命周期策略 |
| Web 入口与部署 | Caddy + Shell 脚本 | TLS 终止、反向代理、静态文件、压缩、健康检查与受控发布；配置和脚本纳入版本控制 |
| 可观测性 | OpenTelemetry + Prometheus + Grafana + Loki | 指标、链路、日志、告警与审计关联 |

## 3. 推荐部署拓扑

```mermaid
flowchart LR
  APP[Flutter Apps] --> GW[API Gateway / BFF]
  WEB[Vue 3 管理系统] --> GW
  GW --> CORE[Go Core API]
  CORE --> PG[(PostgreSQL + PostGIS)]
  CORE --> R[(Redis Cache / Streams)]
  CORE --> OSS[Object Storage]
  DEV[智能瓶阀设备] --> MQTT[MQTT TLS 接入]
  MQTT --> IOT[Go IoT Adapter]
  IOT --> R
  R --> WORKER[Go Worker]
  WORKER --> RULE[告警规则、工单、通知、对账]
  CORE --> EXT[支付/合同/短信/地图]
```

### 3.1 运行进程职责

| 进程 | 职责 | 扩缩与可靠性要求 |
| --- | --- | --- |
| `api` | 用户端和五个管理系统的 HTTP API、鉴权、同步业务事务 | 无状态部署；所有写操作支持幂等键、事务和审计 |
| `worker` | 事件消费、告警、派单、推送、对账、超时扫描、轨迹异常识别 | Redis Streams 消费组；重试、死信、幂等消费和可观测的积压告警 |
| `iot` | MQTT 设备会话、协议适配、遥测校验、命令下发与回执 | 保持设备会话一致性；命令/回执持久化；协议版本和设备身份校验 |

关键业务采用“数据库事务 + Outbox 事件表 + Worker 投递”的模式：先在 PostgreSQL 提交业务事实与待投递事件，再异步写入 Redis Streams。这样 Redis 故障或 Worker 重启不会丢失订单、告警、支付或设备命令的业务事实。

## 4. 前后端项目标准库

| 基线 | 路径 | 使用要求 |
| --- | --- | --- |
| 前端标准库 | `sample/front` | 五个 Vue 管理系统从该工程统一前端框架、路由、状态管理、请求封装、权限指令、表格表单、主题、错误处理、国际化与测试规范 |
| 后端标准库 | `sample/server` | Go API、Worker、IoT 进程统一沿用配置、日志、错误码、认证、数据库访问、迁移、任务、测试和发布规范 |

业务项目应通过共享包、模板或上游同步机制复用标准库，禁止将标准库目录复制到每个子项目后自行漂移。标准库升级需要记录版本、影响范围、兼容策略和回滚方式。

## 5. 研发目录规划（建议）

```text
platforms/
  docs/                         # 本需求文档集
  apps/
    user_app/                 # Flutter 用户端 App
    service_app/              # Flutter 服务端 App：安装维修、安检、配送能力包
  frontend/
    platform_admin/           # Vue：平台总后台
    gas_admin/                # Vue：气站管理系统
    delivery_admin/           # Vue：配送点管理系统
    product_admin/            # Vue：生产管理系统
    openapi/                  # Vue：API 中心管理系统
    site/                     # HTML：官网land页
  backend/
    api/                      # Go HTTP API、BFF、同步领域事务
    worker/                   # Go 异步任务：派单、告警、通知、对账、超时扫描
    iot/                      # Go MQTT 协议适配、设备命令、遥测与回执
    migrations/               # PostgreSQL 迁移、初始化数据与回滚说明
  contracts/
    openapi/                  # HTTP API 契约及生成配置
    asyncapi/                 # MQTT/Redis Streams 事件契约与 Schema
  deploy/
    caddy/                    # Caddy 配置、站点与证书策略
    scripts/                  # 服务器部署、启停、健康检查、回滚 Shell 脚本
  scripts/                    # 本地开发、生成、编译、质量检查 Shell 脚本
  tests/
    rest/                     # HTTP API 集成与回归测试
    contract/                 # OpenAPI/AsyncAPI 兼容性测试
    e2e/                      # 关键端到端流程
    performance/              # 遥测、订单、轨迹与消息积压压测
```

该结构是后续开发建议，不代表本次创建了任何代码目录或代码文件。

## 6. 后端领域划分

- `identity`：登录、验证码、账号、RBAC、组织、数据范围、协议同意。
- `organization`：气站、配送点、服务区域、人员归属、用户服务关系和邀请注册二维码。
- `device`：设备注册/绑定、设备模型、遥测、命令、在线状态、固件。
- `safety`：规则、告警事件、分级、SLA、整改、安检、复检、升级。
- `catalog`：分类、商品、SKU、库存、优惠券、收藏、购物车。
- `order`：订单、支付、合同、配送、安装、售后、评价。
- `dispatch`：服务人员、区域、班次、任务、派单、导航、配送轨迹与现场取证。
- `wallet`：充值、余额流水、分账、结算、提现、对账。
- `content`：轮播、公告、协议、视频、客服配置。
- `notification`：站内信、推送、短信、语音、模板、触达回执。
- `audit`：不可变操作日志、敏感数据访问记录、导出记录。
- `manufacturing`：设备型号、生产工单、序列号、证书注入、质检、批次、固件和出厂追溯。
- `openapi`：API 产品、调用方应用、凭证、订阅、配额、网关策略、Webhook 和调用审计。

## 7. 工程质量基线

### 7.1 数据模型与命名强制规范

- 每个业务模块的关系表必须使用模块前缀，格式为 `<模块前缀>_<实体名>`，全小写蛇形命名。禁止使用无领域归属的通用表名，如 `users`、`orders`、`records`。
- 文件名、表名、模型名和接口 Schema 必须以同一“模块前缀 + 单数实体词根”为唯一标识；禁止因为语言、层次或集合含义改变实体名称，也禁止使用复数形式造成不一致。

| 模块 | 表前缀 | 典型表 |
| --- | --- | --- |
| 身份与权限 | `idn_` | `idn_account`、`idn_role`、`idn_permission` |
| 组织与服务关系 | `org_` | `org_gas_station`、`org_delivery_point`、`org_service_person`、`org_user_service_relation` |
| 设备与物联网 | `dev_` | `dev_device`、`dev_telemetry`、`dev_command` |
| 安全与安检 | `saf_` | `saf_event`、`saf_rule`、`saf_inspection`、`saf_rectification` |
| 商品与营销 | `cat_` | `cat_product`、`cat_sku`、`cat_coupon`、`cat_cart` |
| 订单与履约 | `ord_` | `ord_order`、`ord_payment`、`ord_service_task`、`ord_delivery_track` |
| 调度与配送 | `dsp_` | `dsp_assignment`、`dsp_shift`、`dsp_delivery_track_point` |
| 钱包与结算 | `wal_` | `wal_ledger`、`wal_settlement`、`wal_withdrawal` |
| 内容与通知 | `cnt_`、`ntf_` | `cnt_article`、`cnt_banner`、`ntf_message`、`ntf_template` |
| 生产与质量 | `mfg_` | `mfg_work_order`、`mfg_batch`、`mfg_quality_check` |
| 开放接口 | `api_` | `api_product`、`api_client`、`api_subscription` |
| 审计与平台任务 | `aud_`、`sys_` | `aud_operation_log`、`sys_outbox_event`、`sys_dead_letter_event` |

- 所有主表必须包含 `identity` 字段，类型为 UUID V7，并作为该表的主键。UUID V7 由应用服务生成，保证时间有序性；禁止使用数据库自增主键、随机 UUID V4 或将业务编号作为主键。
- 引用主表时，外键字段命名为 `<实体名>_identity`，例如 `order_identity`、`service_person_identity`。业务展示编号（订单号、设备编码、站点编码等）应使用独立字段并设置唯一约束，不能替代 `identity`。
- 每个主表还应按需要包含 `created_at`、`updated_at`、`created_by_identity`、`updated_by_identity`、`status`、`version` 等审计/并发字段；资金流水、安全事件、审计日志等不可变记录不得被物理删除。
- 数据库表、字段、索引、约束和枚举必须编写中文注释；注释说明业务含义、取值/单位、脱敏或留存要求。迁移脚本需同步维护注释，禁止只在设计文档中说明。

#### 实体名、文件名、表名、模型名一致性

以 `org_gas_station` 为例，同一业务实体必须按下表命名：

| 产物 | 强制命名 | 禁止示例 |
| --- | --- | --- |
| 数据库表 | `org_gas_station` | `org_gas_stations`、`gas_stations`、`station` |
| Go 模型文件/类型 | `org_gas_station.go` / `OrgGasStation` | `gas_station.go`、`GasStations`、`StationModel` |
| Flutter 模型文件/类型 | `org_gas_station.dart` / `OrgGasStation` | `gas_stations.dart`、`GasStationEntity` |
| Vue 模型文件/类型 | `org_gas_station.ts` / `OrgGasStation` | `gasStation.ts`、`GasStations` |
| OpenAPI/AsyncAPI Schema | `org_gas_station` | `GasStationDto`、`gas_stations` |
| 迁移文件 | `<时间戳>_create_org_gas_station.sql` | `<时间戳>_create_gas_stations.sql` |

- 所有实体一律使用单数：一个 `org_gas_station` 既可表示单个站点模型，也可作为列表返回项的模型名称。列表、批量和分页仅在 API 动词或响应字段表达，例如 `GET /org/gas-station/list`、`items: []`；不改变实体名。
- 关联表使用参与实体的单数词根和明确关系词，例如 `org_user_service_relation`、`idn_account_role_relation`，不得使用 `users_roles`、`user_roles` 等复数或含糊名称。
- 文件目录可以按业务模块组织，但目录名不参与实体命名；模型、迁移、契约、测试文件都必须能从其文件名唯一定位到同名的数据库表和模型。
- 新增实体前应先登记规范名称；重命名须同时修改表、模型、文件、契约、迁移和中文注释，并进行全仓引用检查，禁止仅改其中一层。

### 7.2 代码与模型中文注释规范

- Go、Flutter 和 Vue 代码中的业务类型、领域模型、枚举、公开接口、复杂规则、状态机、金额计算、权限判断和异步事件必须使用中文注释说明业务意图。
- 中文注释应解释“为什么”和业务口径，不重复代码字面含义；对外 API 的字段说明、OpenAPI/AsyncAPI Schema 描述和错误码说明同样必须为中文。
- 模型注释应与数据库注释和接口契约保持一致。需求变更导致字段、状态或规则变化时，代码、迁移、模型和契约注释必须在同一变更中更新。
- 注释中应使用与表名/模型名一致的中文业务名称，例如“气站”对应 `org_gas_station`，不能在同一业务语境混用“站点”“气站信息”“GasStations”等不同实体名。
- 禁止以无意义拼音、英文缩写或临时注释代替业务说明；第三方库、协议标准和专有名词可保留其原文，并在首次出现处附中文解释。

- API 使用 OpenAPI；IoT/事件使用 AsyncAPI 或明确的版本化 Schema；客户端由契约生成类型。
- Redis Streams 的生产者、消费者、重试和死信处理均须有监控；任何消费者可安全重复执行，Redis 不可用时由 Outbox 补偿投递。
- 所有管理端沿用 `sample/front` 的鉴权、数据权限、错误处理和审计埋点；所有 Go 进程沿用 `sample/server` 的配置、日志、迁移和健康检查规范。
- 单元测试覆盖规则、金额、状态机、权限；集成测试覆盖支付回调、设备回执、派单和并发库存；端到端测试覆盖高风险安全闭环。
- CI 必须执行静态检查、依赖漏洞扫描、迁移检查、契约兼容性检查和关键路径自动化测试；CD 必须先执行数据库迁移兼容性检查、健康检查和可回滚发布。