ray604638018/cursor

Fork 0

Files

ray zhou 2dd9f17da9 ok

2026-06-29 14:51:55 +08:00

6.1 KiB

Raw Permalink Blame History

todos:

id: "internal-layer" content: "新建 internal DeviceController + 迁移 logic/dto/validate（DTO 含 user_id）" status: pending
id: "cleanup-api" content: "从 api DeviceController 移除绑定三接口并删除 api 侧绑定文件" status: pending
id: "remove-user-auth" content: "删除 UserAuth、UserRequestContext 及无引用错误码" status: pending
id: "docs-update" content: "更新 device.md §10、03-user-binding.md、06-internal-api.md 路径与调用方说明" status: pending
id: "verify" content: "docker php -l + slot-backend-completion-report" status: pending isProject: false

SR-3 设备绑定迁入 internal 应用

架构判断（同意你的方向）

与 device.md 中已有分层一致：

应用	调用方	鉴权	职责
api	物理设备	`device_sn` + 签名	激活、心跳、OTA 入口
admin	后台 BFF / admin-service	`Authorization`（骨架）	产品/型号/设备档案管理
internal	user-service、message-service、ota-service 等	`X-Internal-Token`	跨服务读写设备主数据

绑定关系是 device-service 的领域数据，但 用户登录态不应在本服务校验——应由 user-service（或 App BFF）完成 session/JWT 校验后，再调用 device-service 的 internal 接口写入绑定。这与 §4.3「后台 → BFF → device-service」模式同构。

sequenceDiagram
    participant User as 用户App
    participant UserSvc as user_service_BFF
    participant Device as device_service_internal

    User->>UserSvc: 扫码绑定 device_sn
    Note over UserSvc: 校验登录态，解析 user_id
    UserSvc->>Device: POST /internal/device/bind
    Note over Device: X-Internal-Token + user_id + device_sn
    Device-->>UserSvc: code=0
    UserSvc-->>User: 绑定成功

结论：SR-3 应落在 internal，而不是 api；当前 DeviceController.php 上的 #[Middleware(UserAuth)] + UserRequestContext 应移除。

目标接口（默认路由，id 走 body/query）

方法	路径	入参
POST	`/internal/device/bind`	`user_id`, `device_sn`
POST	`/internal/device/unbind`	`user_id`, `device_id`
GET	`/internal/device/list`	`user_id`（query）

鉴权：应用级 InternalTokenAuth（已挂在 internal），不再使用 UserAuth。

代码迁移步骤

1. 新建 internal 分层（从 api 平移）

新增 app/internal/controller/DeviceController.php（extends InternalController）
- bind / unbind / list 三个 action
将以下文件 改 namespace 为 app\internal\*（逻辑基本不变）：
- app/api/logic/DeviceBindLogic.php → app/internal/logic/DeviceBindLogic.php
- app/api/dto/DeviceBindDTO.php → 增加 userId 字段
- app/api/dto/DeviceUnbindDTO.php → 增加 userId 字段
- app/api/validate/DeviceBindValidate.php → 增加 user_id 规则（require|integer|gt:0）及 validation 文案

Controller 从 DTO 读取 userId，不再调用 UserRequestContext::getUserId()。

2. 清理 api 应用

从 app/api/controller/DeviceController.php 删除 bind / unbind / list 及 DeviceBindLogic、DeviceBindValidate、UserAuth 相关 use/构造注入
删除 api 侧已迁移的 logic/dto/validate 文件

3. 删除用户鉴权骨架（若无其它引用）

删除 app/middleware/UserAuth.php
删除 app/support/UserRequestContext.php
OtaErrorCode::USER_AUTH_FAILED (1004) 可保留翻译条目（无害），或一并移除——以「无引用」为准

4. Logic 行为

DeviceBindLogic 业务规则不变（幂等、唯一约束、状态校验）；仅入参来源从「上下文 user_id」改为「请求体/Query 显式 user_id」。

安全说明（写入 SR-3/SR-6 文档）：internal 信任「调用方已在网关/BFF 完成用户鉴权」；user_id 由调用方传入，device-service 只负责绑定域规则。与 SR-6 §5「服务间 token」一致。

5. 需求文档同步

03-user-binding.md：路径改为 /internal/device/*，注明调用方为 user-service/BFF
device.md §10：同上；§10 标题可改为「用户绑定（内部接口，由 user-service 暴露给 App）」
06-internal-api.md：补充 bind/unbind/list 三条（扩展 SR-6 范围或交叉引用 SR-3）

6. 调用方 SDK（可选，本仓库外）

按 cross-service-sdk，若 user-service 在 monorepo 内，后续在 slot_sdk 增加 DeviceClient（或 DeviceBindService）方法指向上述三条 internal 路径；本次 device 仓库内可不实现，仅在计划中标注为调用方跟进项。

不涉及

DeviceBindModel、错误码 4208/4209、翻译文案：已存在，无需改业务码
SR-6 只读查询（单设备档案/批量/在线状态）：可另 PR 实现，与本次迁移独立
「查询设备绑定用户」：admin 详情已只读；若 internal 需要可加 GET /internal/device/bind-owner?device_id=，非本次必须，除非你要求一并做

验收

api 仅保留 activate、heartbeat（及后续 OTA）
internal 三条绑定接口带 X-Internal-Token 可通，缺 token 返回 1001 + HTTP 403
绑定/解绑/列表业务行为与现 SR-3 验收要点一致
docker php -l + completion-report 通过

6.1 KiB Raw Permalink Blame History Unescape Escape