AGENTS.md

本文件适用于整个仓库。目标是让后续开发始终围绕“物联网智能瓶阀平台”的既定业务边界、架构和契约推进，避免把当前平台总后台扩成万能系统，或让样例、文档规划与已实现代码相互混淆。

1. 开始工作前

先阅读 docs/README.md，再按改动范围阅读：
- 业务边界：docs/01-项目总览与边界.md
- 跨系统流程：docs/02-核心业务流程.md
- 对应终端需求：docs/03 至 docs/09
- 架构和命名：docs/10-技术实现规划.md
- 接口、安全与隐私：docs/11-数据接口与安全.md
- 验收范围：docs/12-验收与迭代规划.md
检查 git status，保留用户已有改动；不要顺手格式化、重写或删除无关文件。
区分三类内容：
- frontend/platform_admin、backend/{api,worker,iot-client,iot-server} 是当前业务实现。
- docs/10-技术实现规划.md 中尚不存在的目录和系统属于规划，不得为完成局部任务擅自创建空壳工程。
需求不明确时以文档中的系统主责、数据主责和安全规则为边界；不得把标为“待确认”的事项自行固化为政策。
文档之间出现冲突时按以下顺序处理：
- 用户在当前任务中的明确要求。
- 已实现代码、资源契约和 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-client：管理系统/App 的设备上下行 HTTP 边界；不得绕过 API 的业务鉴权和安全状态校验。
backend/iot-server：外部 MQTT Broker 会话、厂商协议、遥测、设备命令和回执；本地配置不代表已完成真实设备联调。
frontend/platform_admin：平台级治理、运营、财务、安全、主数据和审计界面；后端资源契约是其资源和操作能力的依据。
docs：产品和技术基线；涉及业务口径、实体、状态、权限或跨端流程的变更必须同步更新相应文档。
doc：原始设计图和协议附件，仅作需求来源；不要批量改名、压缩或重写。

系统职责必须保持分离：

平台总后台不承接气站、配送点、生产单位的日常重复操作。
气站、配送点、生产、API 中心的业务事实各有唯一主责系统；其他系统通过 API、事件或只读聚合使用。
API 中心只管理接口产品和调用方，不能绕过业务服务直接写业务数据库。
api 不应承担长期运行的异步循环；worker 不应复制同步领域事务；两个 IoT 进程不应内嵌交易、资金或后台页面逻辑。

目录归属规则

仓库目录按以下职责使用，不要跨目录堆放代码：

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-client/                 # 当前：管理系统/App 的设备上下行接口
    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. 测试与验证

按改动范围执行最小充分验证，并在交付说明中列出实际运行的命令：

# 后端 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-client && 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 等批量写命令，除非任务明确是全仓格式化。

本地启动入口：

./scripts/run_backend.sh
./scripts/run_frontend.sh
# 或同时运行
./scripts/run_platform.sh

默认地址为后端 http://localhost:12426/heqi/platform/v1、前端 http://localhost:5173。

8. 变更完成标准

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

13 KiB Raw Blame History Unescape Escape