platforms/AGENTS.md

# 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-gateway,iot-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-gateway`：API/Worker 与 IoT Server 的无状态上下行 HTTP 轻网关；不得保存业务事实或绕过 API 的业务鉴权和安全状态校验。
- `backend/iot-server`：内嵌 Mochi MQTT 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-gateway/                # 当前：API/Worker 与 IoT Server 的无状态上下行网关
    iot-server/                 # 当前：MQTT 与设备协议边界
  contracts/
    openapi/                    # 规划：HTTP 契约
    asyncapi/                   # 规划：MQTT/事件契约
  deploy/                       # 规划：Caddy、发布和回滚
  scripts/                      # 当前：仓库级开发启动脚本
  tests/                        # 规划：跨模块契约、E2E 和性能测试
  docs/                         # 需求与技术基线
  doc/                          # 原始设计图、协议和附件
```

- “规划”目录只表示未来归属；任务没有明确要求时不得提前创建。
- 新管理端统一复用现有管理端的公共机制，新 Go 进程统一沿用现有后端分层；通过共享包或模板复用，禁止复制后独立漂移。
- 跨系统契约放入 `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-gateway && go test ./... && go build ./cmd/main/main.go
cd backend/iot-server && 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. 变更完成标准

- 改动只落在正确的主责模块，没有把规划系统偷塞进平台总后台。
- 需求、模型、契约、路由、权限、前端和测试在受影响范围内保持一致。
- 没有引入同义实体、越权入口、直接状态写入、浮点金额、不可恢复事件或敏感信息泄露。
- 已运行与改动相称的测试/检查；若因环境或外部依赖未运行，明确说明具体原因。
- 不提交日志、临时文件、本地配置、构建目录、依赖目录或无关格式化变更。