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

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

1. 架构原则

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

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

2. 技术选型

层级	推荐技术	用途
用户端 App	Flutter 3 / Dart 3	首期首页内容、服务归属、商城、订单、合同、工单、钱包、地址和个人中心
服务端 App	Flutter 3 / Dart 3	配送、安装维修、安检三类单角色账号工作台、现场取证与受控离线草稿
平台总后台	Vue 3 + TypeScript	全局治理、运营、财务、安全、审计等高密度管理页面
可燃气体站管理系统	Vue 3 + TypeScript	站点商品、订单、服务、库存与经营管理
配送点管理系统	Vue 3 + TypeScript	调度、配送仓、路线、人员和配送运营工作台
生产管理系统	Vue 3 + TypeScript	生产计划、设备身份、质检、批次、固件和出厂追溯
API 中心管理系统	Vue 3 + TypeScript	API 产品、调用方、凭证、流量、文档与审计门户
核心后端	Go	REST、领域服务、权限、订单、工单、资金、规则执行
IoT 通道	MQTT（TLS）+ Go 接入服务	设备连接、遥测、命令下发、回执、在线状态；协议适配层屏蔽厂商差异
关系数据	PostgreSQL	事务数据、地理空间（PostGIS）
缓存与任务	Redis	限流、会话、幂等、短期状态、延迟任务；关键事实仍落 PostgreSQL
消息/事件	Redis Streams + Consumer Group	遥测流、告警、订单状态、通知、对账异步化；使用消费组、重试、死信与幂等消费者保障可恢复处理
文件与证据	本地存储，S3 兼容对象存储	先本地存储，后期上OSS，包括：商品图、安装/安检证据、签收图片、视频和合同；采用短期签名 URL 与生命周期策略
移动端离线与定位	Flutter 安全存储 + 本地加密数据库 + 地图/定位 SDK	服务端 App 的已分配任务、现场材料和配送轨迹可弱网暂存；保留原始采集时间并按幂等键补传
Web 入口与部署	Caddy + Shell 脚本	TLS 终止、反向代理、静态文件、压缩、健康检查与受控发布；配置和脚本纳入版本控制

3. 推荐部署拓扑

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. 前后端项目标准库

基线	路径	使用要求
前端工程基线	现有 Vue 管理端	Vue 管理系统统一前端框架、路由、状态管理、请求封装、权限指令、表格表单、主题、错误处理、国际化与测试规范
后端工程基线	backend/{api,worker,iot}	Go API、Worker、IoT 进程统一沿用配置、日志、错误码、认证、数据库访问、任务、测试和发布规范

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

4.1 移动端定位、离线与取证基线

• 服务端 App 仅在配送或现场任务执行期间申请并采集定位；必须显式展示定位授权、后台运行、最后更新时间和权限失效状态。用户端仅消费本人订单所需的简化轨迹。
• 已分配任务、轨迹点、照片/视频元数据、签名、扫描结果和收款确认可在弱网下加密暂存。补传必须携带原始采集时间、服务端接收时间、任务 identity、操作者 identity、来源、完整性标记与幂等键，禁止以补传时间覆盖采集时间。
• 后端负责乱序校正、重复去除、异常速度/精度标记、证据哈希与状态机校验；前端离线缓存、按钮禁用或页面显示不能替代服务端权限、金额、地理围栏和完成条件校验。

4.2 Flutter 工程落地基线

• 生产工程已落在 apps/user_app 与 apps/service_app，生成 Android、iOS、Web 平台目录；ui 继续作为视觉和交互原型，不作为运行时依赖。Web 构建通过仓库根目录 scripts/build-apps.sh 输出，生产环境必须注入 HTTPS API_BASE_URL。
• 两个 App 使用 MaterialApp.router、go_router、MVVM + Repository 与注入的平台 Service。HTTP 根地址通过 --dart-define=API_BASE_URL=... 注入；用户端和工作人员端分别固定访问 /heqi/client/v1/user 与 /heqi/client/v1/staff，JWT 请求头沿用当前服务端原始令牌契约。
• 访问令牌保存在 Android Keystore / iOS Keychain 支持的安全存储；Web 使用浏览器安全存储，且只能部署在 HTTPS 域名。服务端 App 的现场草稿和附件按账号使用 AES-GCM 加密；Web 仅保存密文，恢复网络后才上传并执行最终业务提交。浏览器端不承担 Android/iOS 的后台定位保障。
• 充值 Mock 确认只允许 Debug/开发联调，Release UI 不注册该入口；未落地的设备控制、收藏、押金、消息和发票能力不得以静态成功状态替代。

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

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 协议适配、设备命令、遥测与回执
  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/              # 遥测、订单、轨迹与消息积压压测

其中 apps/user_app、apps/service_app、backend/{api,worker,iot} 与当前管理端目录已经落地；其余标记为规划的目录仍不得因局部任务提前创建空壳。

6. 后端领域划分

• backend/api/internal/logic/common：承载跨平台后台、气站、配送点以及两个 Client 复用的鉴权、账户解析、资源响应和钱包记账能力；不再保留 logic/client/common 同义公共包。
• identity：登录、验证码、账号、RBAC、组织、数据范围、协议同意。
• organization：气站、配送点、服务区域、人员归属、用户服务关系和邀请注册二维码。
• device：设备注册/绑定、设备模型、遥测、命令、在线状态、固件。
• 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、org_invitation_qr_code
设备与物联网	dev_	dev_device、dev_telemetry、dev_command
商品与营销	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_wallet_ledger、wal_settlement、wal_withdrawal
内容管理	cms_	cms_content
生产与质量	mfg_	mfg_work_order、mfg_batch、mfg_quality_check
开放接口	api_	api_product、api_client、api_subscription
平台任务	sys_	sys_outbox_event、sys_dead_letter_event

• 每张表必须包含数据库内部使用的 id bigint 自增主键；主表还必须包含由应用生成、带唯一索引的 UUID V7 identity varchar(36)。HTTP、消息、审计日志、Flutter/Vue 模型和跨服务引用只使用 identity，不得暴露或接受内部 id。
• 数据库内部关联优先使用 <实体词根>_id 指向自增主键；跨服务契约、异步事件和审计关联使用 <实体词根>_identity。业务展示编号另设唯一字段，不能替代 id 或 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

• 所有实体一律使用单数：一个 org_gas_station 既可表示单个站点模型，也可作为列表返回项的模型名称。列表、批量和分页仅在 API 动词或响应字段表达，例如 GET /org/gas-station/list、items: []；不改变实体名。
• 关联表使用参与实体的单数词根和明确关系词，例如 org_user_service_relation、idn_account_role_relation，不得使用 users_roles、user_roles 等复数或含糊名称。
• ord_delivery_track 是配送任务的状态轨迹主表，dsp_delivery_track_point 是其定位点明细表；二者均为独立实体，不得再创建同义的 delivery_tracks、track_points 等表或模型。定位点通过 delivery_track_identity 关联主表。
• 钱包事实流水的唯一实体名为 wal_wallet_ledger；用户和服务人员的资金归属通过关联对象字段区分，禁止另建同义的 wal_ledger、wallet_ledgers 或 service_wallet_ledger。
• 文件目录可以按业务模块组织，但目录名不参与实体命名；模型、契约、测试文件都必须能从其文件名唯一定位到同名的数据库表和模型。
• 新增实体前应先登记规范名称；重命名须同时修改表、模型、文件、契约和中文注释，并进行全仓引用检查，禁止仅改其中一层。

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

• Go、Flutter 和 Vue 代码中的业务类型、领域模型、枚举、公开接口、复杂规则、状态机、金额计算、权限判断和异步事件必须使用中文注释说明业务意图。

• 中文注释应解释“为什么”和业务口径，不重复代码字面含义；对外 API 的字段说明、OpenAPI/AsyncAPI Schema 描述和错误码说明同样必须为中文。

• 模型注释应与数据库注释和接口契约保持一致。需求变更导致字段、状态或规则变化时，代码、模型和契约注释必须在同一变更中更新。

• 注释中应使用与表名/模型名一致的中文业务名称，例如“气站”对应 org_gas_station，不能在同一业务语境混用“站点”“气站信息”“GasStations”等不同实体名。

• 禁止以无意义拼音、英文缩写或临时注释代替业务说明；第三方库、协议标准和专有名词可保留其原文，并在首次出现处附中文解释。

• API 使用 OpenAPI；IoT/事件使用 AsyncAPI 或明确的版本化 Schema；客户端由契约生成类型。

• Redis Streams 的生产者、消费者、重试和死信处理均须有监控；任何消费者可安全重复执行，Redis 不可用时由 Outbox 补偿投递。

• 所有管理端统一沿用现有管理端的鉴权、数据权限、错误处理和审计埋点；所有 Go 进程统一沿用现有后端的配置、日志和健康检查规范。

• 单元测试覆盖规则、金额、状态机、权限；集成测试覆盖支付回调、设备回执、派单和并发库存；端到端测试覆盖高风险安全闭环。

• CI 必须执行静态检查、依赖漏洞扫描、契约兼容性检查和关键路径自动化测试；CD 必须执行健康检查和可回滚发布。