Skip to Content
工作周报2026 年度总结2026年09月28日

2026年09月28日

内容截止日: 2026年10月04日

本周工作计划与执行完成进度

中心服务平台 - 功能完善

  • 进度: 🔘 未开始 -> 🟡 进行中 -> ⚠️ 部分完成 -> ✅ 已完成 -> 📌 已自测
    • 以往已完成的工作不再重复，详情请查看上周及上月报告
    • 〔工作量〕es-center-server-services 90 次（设计 25 · 代码 65）· 代码 +5.0k/-2.1k ｜ es-center-server-web-app 22 次（设计 5 · 代码 17）· 代码 +1.6k/-0.6k ｜ es-center-server-install-app 4 次 · 代码 +1.5k/-0.6k ｜ es-center-server-build 4 次 · 代码 +0.1k/-0.1k ｜ es-center-server-agent 1 次
    • 〔方法论〕显式选测 ｜ 读取准入统一 ｜ 按审计结果修正 ｜ 明确命名的统一 ｜ 窄例外记录 ｜ 分段计时契约 ｜ 审查驱动呈现修正 ｜ 样板复用裁决 ｜ 配置驱动内置身份 ｜ 预设统一标记
    • 9-28: 组织管理路线与工程入口
      • ✅ 管理员跨租户管理定下后端先行的路线，Org 术语统一 〔es-center-server-web-app〕
        • 设计 Org（组织）词条入册：租户内按父子关系组成层级的组织单元；组织管理语境里的「部门」指同一实体，Avoid 标注禁止独立的 Department/Dept 用法。
        • 设计 管理员跨租户业务管理路线图与后端交接发布：规划主文（模块盘点、依赖顺序、交付节奏裁决）与后端开发交接文档保存；后续各模块分别走 to-spec → to-tickets → implement（规格 → 拆票 → 实施）技能管线，节奏定为先全部后端接口、再统一前端。
        • 评审 grill-with-docs 明确交付节奏；本周只有路线与交接产物，各模块仍须分别完成规格、拆票与实施。
    • 9-28: Web 显式选测
      • ✅ 单测必须显式选择范围，错误范围与零执行返回失败 〔es-center-server-web-app〕
        • 实施 单测入口要求显式选测（命令必须点名要跑哪些测试）：定向与全量单测分开成独立命令入口；空选择和会掩盖零测试的参数被拒绝，Vitest 失败状态如实传递；verify 收敛成类型、lint、格式三项静态检查。
        • 实施 不执行测试的 Vitest 选项一律拒绝：帮助、版本和维护类选项被拦截——不会再出现没跑测试却返回成功。
        • 实施 部分选测与零执行判失败：用 Vitest reporter 检查实际执行数与逐个选择范围的文件命中——部分拼错不再返回成功。
        • 实施 runner 选项后的尾随选测范围拒绝：常用 reporter 与并发参数的空格取值写法保留，与 Vitest 不区分大小写的文件匹配语义对齐。
        • 实施 Vitest 带值选项与规范化路径放行：对齐本仓 Vitest run 的带值选项——有效的空格取值不会被误当尾随范围拒绝。
        • 实施 从 Vitest 帮助解析空格取值选项：只在遇到空格取值时读已安装 Vitest 的扩展帮助；扩展帮助本身这类不执行测试的选项照样拦截。
        • 排障 全量串行运行下帮助输出捕获偶发为空的缺陷修复：动态选项的帮助输出先写临时文件再解析——worker 子进程管道偶发为空也不再误拒合法选项。
        • 审查 显式选测票 16 项验收统一、回写。
        • 实施 run-item.sh 接进 explicit-unit-test-selection 票目录。
    • 9-28: 组织 Web 请求合同
      • ✅ 组织根节点读取与旧新增请求对齐后端合同 〔es-center-server-web-app〕
        • 实施 组织读取与旧新增请求的合同对齐：v1 根组织读取类型接受服务端省略父字段的投影；旧业务新增的三个表单字段直接进原 HTTP API——生产改动只限两处前端文件。
    • 9-28: 管理入口清理
      • ✅ 旧个人空间采集设备列表退役，四票管理清理方案备齐 〔es-center-server-services〕
        • 重构 已淘汰的旧个人空间采集设备列表入口删除：按维护者裁决注销路由与 OpenAPI operation，已认证请求返回 404；现存的个人空间设备列表是 v1 retail list，合同不变。
        • 设计 既有管理能力清理的建图与两张决策票发布：wayfinder（先用决策地图澄清方向）的建图 map、评审记录与旧个人空间列表退役验证证据；租户查询边界、清理范围与验证两张 grilling（逐条追问的设计评审）决策票保存。
        • 设计 管理清理规格与租户边界裁决输入固定：维护者已确认的租户读取裁决、清理证据、统一规格和四张实施票进当前分支——决策完成不当作代码交付。
        • 实施 批次入口切到 management-cleanup-implementation；已完成批次入口行注释收敛。
      • ✅ 租户读取与认证定位明确准入，旧空参调用逐入口裁决 〔es-center-server-services〕
        • 设计 ADR-0095 新增，五份旧 ADR 的部分取代范围精确标注；插件作用域与显式 SQL 缓存的适用前提统一，认证位置与隔离、成本约束记录。
        • 重构 移除三处无作用的 SneakyThrows，查询、缓存键与代理行为保持。
        • 设计 认证空参例外与存量调用边界校准：三条认证 TODO 移到 token 比对后的实际范围选择处；本次只批准三条认证调用，其它旧空参调用待逐入口裁决。
        • 设计 租户读取规则与认证定位工单收尾、回写。
    • 9-28: Gradle 按类验证
      • ✅ Gradle 验证从布尔开关改为按测试类选择，两票交付 〔es-center-server-services〕
        • 实施 Gradle 测试与慢测可显式启用：根项目及 26 个子模块的 Test 任务加严格布尔总开关，slow 标签隔离慢测；默认跳过，日常构建因此缩短。
        • 审查 显式测试执行票经双轴审查纠偏：PTT（按键对讲）手册补验证日期与范围，测试命令复验不当作现场验收。
        • 实施 Gradle 验证改为按测试类显式选择：用 Gradle 原生 --tests 做类/方法选择入口；首版布尔属性与慢测标签移除；ADR-0096 精确部分取代 ADR-0025。
        • 实施 默认 build 跳测试，无范围 test 提示退出，testAll 显式跑完整集合；34 个集成测试类的 35 处环境门控移除，点名类实际执行。SQL、Mapper XML、Gradle 与运行配置变化仍按行为验证。
        • 实施 混合任务隔离、免测范围收紧：定向 --tests 的放行绑定到唯一模块 Test 任务路径；只有 .md/.sh diff 时不再启动 Java 单测。
        • 实施 按测试类选择验证工单记录完成；02 票验收措辞同步 ADR-0096 的测试类选择。
    • 9-28: PTT 可选字段
      • ✅ PTT 选择不适用时省略可选键 〔es-center-server-services〕
        • 排障 PTT 选择不适用时省略 defaultTalkGroupId 键：未指定、指定不适用或无有效群组时整个键省略、不再发空串占位；设备端按可选字段消费（ADR-0069 决策 3）。
        • 测试 按 ADR-0069 决策 3 修正 14 个此前失败的参数化断言。
    • 9-28: 跨租户注释语义
      • ✅ TODO 与 IMPORTANT 分开表达未完成动作与长期约束 〔es-center-server-services〕
        • 设计 TODO 与 IMPORTANT 的注释语义拆分：TODO 只标未完成动作；已实现但须持续遵守的关键约束统一用 IMPORTANT——两种语义不得混用。
        • 重构 跨租户关键约束注释统一改标 IMPORTANT：8 个文件 15 处已实现跨租户约束的 TODO 注释改成 IMPORTANT；纯注释改动，运行时行为不变。
    • 9-28: 组织查询复用
      • ✅ 组织 Plus 详情与列表共用 SQL 条件 〔es-center-server-services〕
        • 重构 组织 Plus 查询共用同义 SQL 片段：12 个普通字段条件、主排序与组织父资料列集中到手写 Plus Mapper；管理详情与列表共用资料关联。
        • 测试 父资料排序区分、双租户旧读锁定：父编号与名称排序产生不同实际顺序、分别断言；补上旧 Plus 在 A/B 同组织 ID 下的非空结果。
        • 设计 组织 Plus SQL 复用工单收尾、回写。
    • 9-28: 安装构建与制品
      • ✅ 20260923 制品引用推进，构建默认只在本地生成 〔es-center-server-install-app〕
        • 实施 制品引用与部署验收记录推进到 20260923：8 份部署脚本包引用 202609211708 → 202609231715，镜像标签 20260921 → 20260923，promgt 构建日志示例推进到 202609231530。
        • 重构 构建链路按检查结论重构：build.sh 默认只本地生成安装/升级/Coturn/Janus 四种包；--backup 与 --upload 显式开启备份和上传。
        • 重构 连接参数与密码集中到 build.conf、环境变量或本机 build.credentials.local.json；本机凭据文件被忽略，仓库仅保留空值 example，备份、上传与示例脚本接入新参数。
        • 测试 新增构建链合同测试；当时定向 pytest 为 85 项通过、1 项跳过，14 份脚本的 bash -n 检查通过。
        • 设计 构建失败即停止；上传逐目标继续，最终汇总失败并返回非零，NAS 失败告警后继续。凭据由配置、环境变量或被忽略的本机凭据文件提供，仓库只留 example 占位。
        • 测试 构建链合同测试核对参数与编排，备份上传默认关闭不代表自动执行它们。
    • 9-28: 构建发布通道
      • ✅ 20260928 发布版本推进，两条上传通道调整 〔es-center-server-build〕
        • 实施 dev.sh 发布版本推进到 20260928：flow、build、deploy 三段版本引用推进；47.121.142.93 通道改为上传 main-service 镜像，107.174.255.35 通道收窄成仅 main-service。
    • 9-28: Agent 联调路径
      • ✅ 构建与联调改用 /mnt/wsl 持久工作区 〔es-center-server-agent〕
        • 实施 cargo target-dir 从 /tmp 迁到 /mnt/wsl 持久工作区；dev-1.sh 的本机复制与 scp 源路径同步迁移；内网服务地址切到 192.168.1.53，随本机联调环境。
    • 9-28（晚间）: 组织验证与定位边界
      • ✅ 组织手写副本再生成保持，Web 读写合同完成验证 〔es-center-server-services〕
        • 测试 组织最终手写副本重生成使用真实 runner 验证入口和 41 份现存手写源码清单；独立输出根记录 1,915 个 fresh 文件、800 个 true 文件恢复、1,115 个 false 文件保留的逐文件摘要，真实 PG 元数据与生成编译证据保存。
        • 测试 生成器 42 项、core 32 项、缓存 1 项、Janus 只读 1 项通过且 XML 无 skipped；41 份手写副本逐字节核对，保持各组验证范围。
        • 设计 缓存模板与再生成保护工单收尾、回写。
        • 测试 测试租户两条旧业务新增的真实请求、Boolean 响应与服务端 ID 回读记录保留，列表、详情、编辑浏览器结果与前后端证据边界区分。
        • 测试 组织 Web 测试后端部署日期记录在案：该日期与源码基线都不能代替未提供的部署 Git SHA 或镜像 tag。
        • 测试 维护者提供的部署日期为 2026-09-24；该日期不能替代部署身份核验。
        • 测试 组织浏览器证据与后端测试对齐：字段白名单、缺省角色、服务端 ID 与 Boolean 响应断言对照后端新旧组织新增核对；旧入口空串父字段组合补上。
        • 测试 旧入口复验前端三字段新增请求：覆盖空父根组织与用服务端父 ID 的子组织；独立连接核对服务端生成的组织身份、租户归属和父关系。
      • ✅ 设备号定位保持精确边界，平台预置租户 ID 统一 〔es-center-server-services〕
        • 实施 设备号 Function（按编号定位设备的函数）的精确定位边界守住：三个设备号 Function 保留同号投影选择，准入、隔离前提与缓存 miss 成本分别记录；固件与 ICE 两处拦截 null/空串设备号。
        • 重构 平台预置租户 ID 统一：es-center-server-core 集中定义 default、pcm、scm 三个领域租户 ID；ADR-0058 事实来源勘误，触及的跨租户范围选择点记录 IMPORTANT 准入。
    • 9-29（凌晨）: 缓存合规审计
      • ✅ ADR-0095 全仓缓存合规审计完成，两服务免租户名单对齐 〔es-center-server-services〕
        • 审查 全仓 Service 缓存方法合规审计归档：扫描 Service 层 131 个缓存查询方法——真违例 0、名实不符瑕疵 2、挂账（登记在案、留待逐项裁决的存量例外）11 处；这份审计是挂账拆票与免租户表名单闭合的共同依据。
        • 重构 ValueSet 读缓存改双态租户键、死参数名纠正：tenantId 经 JetCache 默认参数序列化进缓存 key；审计点名的名实不符死参数纠正——全仓零调用方，无消费者迁移。
        • 实施 免租户表名单按审计结论对齐两服务：共同新增 user_center_user_tag，device-service 补齐三张表、与 main-service 一致；双方都到 6 张免租户表全覆盖。
        • 实施 批次入口切到 adr0095-pending-entries-adjudication。
        • 设计 ADR-0095 挂账入口核对 spec 与 02–05 票发布：承载决策 4 的逐入口核对义务（8 处待裁决 + 3 处已批准对照清单）；新增三张裁决票与按 ADR 逐份批准的回写票。
    • 9-29（日间）: 设备投影与 20260929 制品
      • ✅ 设备号跨租户读取逐入口批准，索引归属按有效投影数确定 〔es-center-server-services〕
        • 设计 三处 HTTP 入口的注释明确准入与成本：main-service getDeviceData、device-service IP 自报、按号列表分别保留匿名/token 门槛、同号投影选择与 miss 跨分区扫描。
        • 测试 真实 PostgreSQL 双租户投影用例补上，业务逻辑保持。
        • 设计 ADR-0097 记录设备号 HTTP 入口跨租户投影窄例外（只限点名入口的受控例外）：匿名读取只返回云节点元数据，IP 自报保留同号全部租户投影，按号列表保留租户筛选；ADR-0042/ADR-0095 部分取代与 ADR-0084 事实勘误同步标注。
        • 设计 ADR-0095 挂账票 02 的 HTTP/token 入口裁决统一，逐份批准票回写。
        • 评审 电池、GPS、MQTT 连接与指令四类调度的跨租户范围与成本裁决完成：3 秒调度、共享 10 分钟缓存，单轮至多 10000 次定位仍有跨分区扫描成本；票 03 的记录用于最终批准前核对。
        • 实施 设备运行消息的搜索索引归属按设备号投影数确定：零条跳过、单条归所属租户、多条归 default；四个调度复用精确设备号 limit 2 解析。
        • 实施 采集服务器 IP 同步的下行范围精确限定：消费者 serverNo 查询改精确匹配、排除相似编号。
        • 测试 消费者与真实 PostgreSQL 回归用例补上。
        • 审查 纠偏索引归属复审问题：无投影必须先退出，不能先写派生字段；补同号活动与较新软删除投影的区分样本。
        • 重构 解析器移到 scheduling/index 关注点子包，按修订顺序执行；设备号 limit 2 的解析规则保持。
        • 测试 设备号 SQL 测试共用插入 fixture（固定测试数据），保留同号活动投影与较新软删除投影的区分样本，生产行为不变。
        • 设计 mqttClientId 设备身份来源澄清、遥测索引设备身份前提限定：ADR-0095 点名入口、审计与票面的准入前提修正；误把 username 绑定列为设备身份门禁的过程判断退役。
        • 设计 mqttClientId 第二段是设备硬件编号，EMQX 登录 username 可独立配置；遥测当前只接受设备报文，三条索引取号仅对设备类身份成立，未来其它身份接入前重新裁决。
      • ✅ 20260929 发布制品引用同步完成 〔es-center-server-install-app〕
        • 实施 包版本引用同步到 202609291015：12 份文件 70 处字面替换——上传、解压、安装与说明操作指向同一批安装/升级产物。
        • 实施 制品引用与部署验收记录推进到 20260929：应用镜像标签 20260923 → 20260929，nginx 反代镜像 1.29.4 → 1.30.5；部署机验收证据与构建日志示例随发布回写。
      • ✅ 20260929 版本推进，Gradle 副本与基础镜像同步调整 〔es-center-server-build〕
        • 实施 dev.sh 发布版本推进到 20260929：flow、build、deploy 及运维各段镜像票面共 32 处推进；上传通道组合沿用上一轮约定。
        • 实施 es-center-server-services 构建改用共享 Gradle 缓存的发行版专用副本：构建前 rsync 一份副本，避开另一 WSL2 环境的在途构建锁冲突，已下载依赖照常复用。
        • 实施 es-center-server-web-app 基础镜像升级 node 26.10.0 / nginx 1.30.5：构建、运行两阶段 tag 推进；初始化机预拉取与离线导出清单同步。
    • 9-30: 响应计时与跨租户规划
      • ✅ 响应时间改为分段字段，HTTP/MQTT 实施保留方案演变轨迹 〔es-center-server-services〕
        • 设计 先按 ADR-0098 用 receiveTime/replyTime/costTime 三字段快照，后改为 ADR-0098~0102 所记录的分段五字段模型：HTTP 输出 processStartTime/replyTime/processCostTime 三字段，MQTT 另有首次排队的 queueStartTime/queueCostTime 两字段，逐轮独立计算。合同是字段与缺失规则唯一正本。
        • 评审 ADR-0099~0102 四张 ADR 分别决定统一业务回复计时、逐轮起点、ApiResult 静态工厂计时与 Web 上下文读取；早期单区间与请求属性 Map 方案保留为历史。
        • 设计 管理员组织管理与 PTT 配置两份既有合同接上分段计时字段：响应示例先行，实际生效以后端切换为准。
        • 实施 HTTP 响应计时（01 工单）由 ApiResult（统一业务响应封装）提供认证前起点、工厂完成快照和处理耗时，旧 timestamp 删除；两服务使用同一模型。
        • 测试 更新 22 个 OpenAPI 示例，201 项定向测试核对真实认证链、退出、重复分派与线程隔离。
        • 实施 MQTT 首次排队与逐轮处理计时（02 工单）：原生 Message timestamp 经 JMS（进程间消息通道）属性传递，保留任务启动前完整等待；后轮继承首次排队信息，前轮快照保持。
        • 测试 383 项定向验证包含遥测与 Janus 回归，三模块实际 XML 计数保留。
        • 实施 应用慢执行日志由响应时间字段替代：静态阈值与两服务阈值注入移除，ADR-0103 同步；Druid 独立慢 SQL 合同保留。
        • 设计 后续 ADR-0103 取消应用慢执行日志，HTTP/MQTT 工厂只产快照与差值；无回复路径不制造计时结果，Druid 慢 SQL 独立保留。
        • 测试 MQTT 缺包探针快照判词明确：队列观测与 HTTP 元数据异常判定提为有名字的布尔判定；测试语义与生产实现不变。
        • 重构 MQTT 后轮起点与回复信封组装收敛：后轮处理起点放在线判断通过之后——准入检查的等待不再计入本轮业务耗时。
        • 测试 用 650 ms Cache 延迟验证起点边界：在线判断的等待不计入本轮业务耗时；保留遥测 null 结果与失败终结合同。
        • 设计 响应计时研究稿保存 Spring Boot 3.5.16 依赖核对、HTTP 时间源排除与离线 Paho/MQTT timestamp 探针；分段计时规格拆四票，工单入口切到 mqtt-api-timing。
        • 审查 HTTP 计时 01 经双轴零发现评审，201 项验证与消费者发布条件分别保存。
    • 9-30: 跨租户管理决策图
      • ✅ 管理员跨租户管理建立决策图，全部决策后再进入实施 〔es-center-server-services〕
        • 设计 管理员跨租户管理建立 wayfinder（先用决策地图澄清方向）地图：25 张决策票按真实依赖连边，全部决策完成后再进入 to-spec → to-tickets → implement（规格 → 拆票 → 实施）；本图没有实施业务改动。
        • 评审 保存 2026-09-29 准备度评审：组织管理适合作下一资源的实现参考，Role 写链的目标保护缺口与事务风险须在开放管理入口前处理；本次建图引用该评审，没有执行 Java 测试。
    • 9-30: 图标语义与验证
      • ⚠️ 图标语义与控件名称已修正，部分真实 UI 验收仍待补齐 〔es-center-server-web-app〕
        • 排障 批量音频按钮的反向图标交换回来：图标与按钮语义恢复对应；文字、回调与设备协议行为均不变。
        • 审查 批量音频按钮审查记录前端调用链与真实 DOM；用户裁定只交换图标，文字、回调、设备协议和广播范围保持，“所有”仅指当前挂载播放器。
        • 实施 实体与配置图标语义修正：连接/断链区分服务器绑定关系；录像、值集、设备分类与采集盒入口表达实际配置对象。
        • 实施 请离、洞察操作与全屏状态图标对齐：播放器用 ahooks 持有真实全屏状态，Esc 退出后呈现准确的下一步操作；确认框按实际动作区分、危险色分级；9 个洞察消费点显式声明图标。
        • 实施 32 个直播、地图、回放和报表按钮补图标控件名称，未知电量准确显示：静音与设备列表开关向辅助技术提供当前状态；电量缺失呈现中性问号。
        • 测试 全屏测试 fixture（固定测试数据）清理与串行隔离闭合：异常路径归还原有 fullscreen 属性描述符与 CJS 缓存引用——全屏测试不再影响其它消费者。
        • 审查 图标语义三票记录代码、检查与真实 UI 条件：01 已完成，02/03 保留 needs-info（待补信息），不把单测通过写成整批验收完成。
    • 10-01（凌晨）: MQTT 推送与慢 SQL
      • ✅ SYS 消息统一为文本，独立主动推送记录真实处理起点 〔es-center-server-services〕
        • 实施 SYS 事件文本载荷与来源属性统一：两条 SYS 通道的 JMS 载荷收敛为文本，topic 统一取来源属性；旧 Pair 在途消息不兼容与切换边界写明，ADR-0104 定下 wire（线上格式）取舍。
        • 重构 MQTT 桥接只接收目的地和原 Message，在内部读来源、时间并规范化文本。
        • 审查 02 工单完成；最终双轴评审与 35 份 JUnit XML 保存，旧 Pair 在途消息不兼容的切换边界保持。
        • 实施 独立主动推送固定处理计时（03 工单）：设备列表刷新与采集服务器 IP 同步两个消费任务启动时记录真实处理起点；多设备发送共用一份 JSON，发送等待不计入业务耗时。
        • 测试 主动推送计时评审证据补齐：慢执行回归同时捕获通知消费者与 ApiResult 工厂 logger；共用通知消费者测试装配提取出来。
        • 设计 03 独立主动推送计时工单统一回写：只完成代码交付、未部署，边界写明。
    • 10-01（凌晨）: Druid 慢 SQL
      • ✅ 两服务启用 Druid 原生慢 SQL 日志，生产状态仍待核验 〔es-center-server-services〕
        • 实施 两个服务启用 Druid（数据库连接池）原生慢 SQL ERROR 日志（04 工单）：各由 starter 装配一份 StatFilter、独立 3000 ms 缺省值。
        • 测试 属性绑定与原生 JDBC 行为共 9 项定向测试覆盖。
        • 测试 两服务分别执行共享装配测试、核对慢 SQL 等值门槛：共享测试源码经相对符号链接各自编译——不把 main-service 的测试代作 device-service 验证。
        • 测试 装配与日志用例共用语义常量，合并装配验证，消除重复字面量；两服务仍各自编译验证。
        • 测试 Druid 慢 SQL 工单的 9 项定向 JUnit 全部执行，无失败、错误或跳过；ERROR 等值门槛核对实际恰好 3000 ms 耗时。外部 Nacos 与生产启用状态仍未核验。
    • 10-03 ~ 10-04: 跨租户管理裁决
      • ✅ 跨租户管理四票裁决明确读取、设备与角色新增边界 〔es-center-server-services〕
        • 设计 设备归属检索与账号识别票决议：采集设备、服务器与采集箱支持部分编号 LIKE 搜索；详情与关联只用唯一资源 ID；每条租户投影独立展示 Org 口径账号集合与设备 state 原值；资料不完整的记录保留可见、供修正。
        • 设计 Role（业务角色）新增保护与旧 upsert（存在即更新、不存在即插入）兼容票决议：新旧普通新增入口统一纯 INSERT 与服务端 NanoID（服务端生成的短随机唯一编号）；内置三角色初始化改走一个点名的内部 upsert；Role 保护缺口的静态事实与六项实施验收定稿入票。
        • 设计 设备检索与 Role 新增结论向下游决策票传递：管理读取与设备投影票继承 LIKE 搜索与唯一 ID 关联约束；独立权限写入口 guard 缺失与内置角色前缀识别失效纳入待裁。
        • 设计 准入组装票认领、决策图与地图刷新：登记「以已交付组织管理合同及实际实现为样板、只对点名清楚的领域差异或真实冲突提问」的裁决方法论。
        • 设计 管理员准入与租户资料组装共用层票决议：准入与作用域编排留在 main-service、复用 BusinessManagementAccess；租户账号资料组装抽成应用层共同能力；各资源 Controller 保留用途适配与领域业务命令。
        • 设计 管理读取共同合同决议、设备父子一致性方向确立：新管理设备读取保留 INNER JOIN，父子收敛五态矩阵定稿；正常父子写入共用同一 Service 事务，定时清理在数据库内直接执行集合 SQL。
        • 评审 撤回此前 LEFT JOIN 方向。Device 与子类型按 ID + tenantId 关联，双方存在且未软删才计入有效设备；父子五态是双方有效保持、一方软删同步软删、双方软删留历史、一方缺席硬删另一方、均缺席无动作。
        • 设计 正常写入共用 Service 事务，修复走数据库集合 SQL；新增 26/27 两张决策票核对所有写者、关联表与调度协调，不退回逐行 Java 清理。
        • 设计 设备父子事务与定时清理票新增、结论向下传递：既定方向拆成两张后续票，向 8 票传导 JOIN 门槛与读取一致性约束。
        • 设计 管理读取用用途限定 DTO；list 限量 1..100000，分页缺省 1/100、pageSize 1..1000，排序白名单及 count/total 按主体粒度。各用途缓存单独登记，前端 Excel 单次上限 100000 行；厂家主动改选才清型号，初始回填保持。
        • 设计 角色权限票认领、决策图与地图刷新：权限来源核查事实登记（Permission 表是赋权结果而非目录，候选来自登录租户前端静态导航）；「目录是否约束后端写入」作为待答问题提出。
    • 10-04: 角色与系统预设政策
      • ✅ 角色初始化和预设身份按 ADR-0105/0106/0107 三决策演进，实施仍待全图闭合 〔es-center-server-services〕
        • 设计 ADR-0105 新增——系统租户跳过业务角色初始化：按租户类型而非硬编码 tenantId 判断，所有角色初始化生产路径跳过三个业务角色；部分取代 ADR-0058 决策第 9 项。
        • 设计 system 租户为 default、pcm、scm，启动重放、新建租户、直接消息消费均跳过 personnel、department-management、team-management 三角色；按租户类型判断，不在启动里暗做存量清理。
        • 设计 角色权限内容票决议、Role 生命周期票认领：权限集合命令只做最小输入过滤、不建目录白名单；Role 更新删除链十条源码核查事实登记。
        • 审查 普通固件列表筛选、新增、编辑都使用厂家、设备类型和型号选择器；原导航遗漏属于配置 bug，读取依赖须为 device-firmware-package:read、device-manufacturer:read、device-device-type:read、device-device-model:read 四码，原型号 read 保留。
        • 设计 四码修正交给普通固件前端交接与无 administrator 旁路的联调；该配置片段当时未写入前端，不能机械推广到 SCM 专用表单，create/write/delete 仍按原操作权限表达。
        • 设计 Role 生命周期票决议、配置驱动内置角色确立：内置业务角色以配置 key 集合为唯一声明来源；普通删除在单一事务里软删 Role 与四类关系；三租户多余权限按增量 SQL 物理清理。
        • 设计 初始政策以 role-permission-list-map 的 key 声明内置业务角色，role-name-map 只管可选英文显示名；administrator 独立保护。权限集合四入口分别核对普通新增、普通更新、独立集合命令与初始化 upsert 的省略、空集合、非空替换语义。
        • 设计 删除同事务软删 Role 与 RoleOrg/RoleUser/RolePermission/UserGroupRole 四类关系；旧删除消息先停生产再排空退役。三租户 default/pcm/scm 的七张权限表用增量 SQL 物理清理，仅保留 administrator，授权缓存继续 10 秒 TTL。以上为待实施决定。
        • 设计 「内置业务角色」领域词入册：按配置声明与现存角色码识别，administrator 独立保护；固定三角色、按角色 ID 前缀识别等三个误用明确。
        • 设计 Role 生命周期结论向下游传递：02/05 票收尾条款统一指向 06 Answer；生成器票继承配置驱动的内置身份与初始化。
        • 设计 决策图与地图刷新、Role 生命周期决议登记：内置角色随配置扩展；角色与四类关系同事务退场；三租户权限增量 SQL 物理清理。
        • 设计 ADR-0106 新增——系统预设数据（平台安装时自动内置的初始数据）以保留创建者统一识别：统一写入 createdUsername=__preset__、按该值精确识别预设身份，取代 06 票「现存同码即内置」判据；「系统预设数据」领域词入册。
        • 评审 ADR-0106 后继裁决改为按预设创建者标记识别 Role，取代同码即内置及移除 key 自动解保的早期方案；配置仍决定初始化内容，普通同码记录不自动获得预设身份。
        • 设计 只有明确声明预设数据的初始化显式写 __preset__，不建可登录同名用户。普通新增、更新、导入、复制、派生链不得接受或传播该值；存量按可核实声明与身份映射补标，空创建者、system 租户或相似 ID 都不是独立证据。
        • 设计 组织绑定角色读取票决议、独立回填合同确立：新增 listByOrgId 独立直查，不受候选列表 100 条限量约束；INNER JOIN 自然排除已删角色；roleIds 省略或 null 都跳过角色关系处理。
        • 设计 绑定读取用 RoleOrg 与同租户有效 Role 的 INNER JOIN，一次取全 tenantId/orgId/roleId/roleCode/name；读取失败不能伪装空集合或触发清理。完整回填后才允许 [] 清空或替换，保存后以组织详情与独立 listByOrgId 确认，不复用旧单 ID 缓存。
        • 设计 系统预设创建者票决议、Role 生命周期衔接同步：统一保留值 __preset__，存量按增量 SQL 补标；移除初始化配置不会自动解除既有预设保护。
        • 设计 系统预设标记与绑定读取结论向下游传递：厂家管理票认领并登记七项事实核对；设备类型树票继承预设创建者合同——不从 ID 前缀或冒号推断身份。
        • 设计 决策图与地图刷新、绑定读取与预设标记决议登记：维护记录固定「系统预设数据统一创建者标记」，长期正本是 ADR-0106。
        • 设计 ADR-0107 新增——系统预设的普通删除由删除 SQL 统一排除：在实际 mutation SQL 的 WHERE 做空值安全的非相等排除；混合批删不因预设整批拒绝。ADR-0106 改为已部分取代。
        • 设计 删除 SQL 同时保留请求身份、原租户/权限和有效性条件，用真实 created_username 与 __preset__ 作空值安全比较；主记录排除后关联也保持。原 affected-row Boolean 返回语义沿用，不预查后 Java 过滤，不用全局拦截器，也不加 ignorePreset 请求开关。
        • 设计 「企业级租户」与「员工用户关联」领域词入册：确认 team 就是承载企业业务的租户；同租户同用户最多对应一名员工，且不表达账号权限。
        • 评审 设备类型树裁决：预设只改名称/简介，编码与父关系固定；撤回混合批删整批拒绝，按 ADR-0107 排除预设。普通类型沿组织样板，可选根/中间节点、同步拒环，删除保留子孙与业务引用。
        • 设计 设备投影三线操作矩阵确定：管理更新不改编号，App 仅改名，库存同步保留各投影名称；个人投影不经管理员普通新增制造，删除只处理所选投影及同事务精确分享关系，不联动其它投影。个人直接拥有/分享投影不能升级，须选择并准入 PCM 库存对象。
        • 审查 员工-账号绑定链首轮核查，记录无事务、静默转绑、本人角色隐式跳过及用户组缺省清空等存量事实；员工全局身份票仍在裁决中。
        • 评审 员工权限先提出退役方案，核实旧表单与本人/非本人写链后撤回，最终裁定保留既有行为；无账号员工可独立新增，原组织已删除时旧 orgId 原样保持，主动换组织才要求有效目标或明确清空。
        • 设计 转绑后旧账号保留企业成员身份，直接授权不随转绑迁移；非本人非空 roleIds 沿旧集合替换，省略/null/[] 沿旧链，本人跳过。未改空集合清空语义、未新增用户组表单或权限 API；team 绑定限制对历史员工维护的入口范围仍待 Q9 答复，票保持 claimed。

其它工作

  • 目标: 记录日常杂项工作、协作沟通等事务
  • 进度: 🔘 未开始 -> 🟡 进行中 -> ⚠️ 部分完成 -> ✅ 已完成 -> 📌 已自测
    • 📌 以往已自测工作不再重复，详情请查看上周及上月报告
    • 28 日
      • ✅ 协作 git → svn 源代码同步
    • 29 日
      • ✅ 实施 将最新版本部署到 192.168.1.53/zxs-cs/zxs-ca 服务器: 编译最新程序 → 制作 Docker 镜像 → 制作升级程序 → 上传服务器 → 升级部署 〔es-center-server-build, es-center-server-install-app〕
      • ✅ 协作 帮郭工排查 app 直播连接速度慢的原因. 直到 30 日,耗时 10h
        • MQTT 历史遥测需要排空：同账号、同安装标识的 client ID 固定，中心会话保留 7 天、遥测订阅使用 QoS 1；已有 /iot/telemetry/v1 遥测订阅在重连后恢复历史消息，两次在线查询的收发日志间隔分别为 12.545 秒和 7.257 秒，应评估历史遥测与实时控制消息共用中心连接的排队影响（PCTopics.swift:51；PCMqttService.swift:180、189、240）。
        • 遥测批量上传内容超出定位需求：/iot/telemetry/v1 包含设备积累一段时间后批量上传的 GPS、电量等十多项动态信息，本次 App 定位更新只需其中的 GPS，却仍接收整批数据并解析、记录完整消息；多余内容增加跨国网络流量、JSON 处理和日志写入开销，降低积压消息的排空速度；建议在设备或服务端按用途拆分主题、裁剪推送给 App 的内容，定位订阅仅保留所需 GPS 数据，其他信息按需获取；App 收包后再过滤无法减少已发生的网络传输（批量上报范围为现场补充；PCMqttService.swift:240、615、629；PCPlayerServiceHolder.swift:254、660）。
        • 历史数据量与跨国网络叠加影响排空：本次 App 在美国使用，中心 zxs 的 MQTT 在中国、地区 zxs-hs 的 MQTT 在美国；积压消息条数多、单条内容大，会增加总传输量及解析、日志处理负担，叠加跨境吞吐、时延和丢包情况，可能共同拉长在线回复与直播启动等待；应结合原始 payload 字节数分段测量，不能仅凭美国连接回复快排除跨境影响（部署位置为现场补充；PCMqttService.swift:160、615）。
        • 日志可直接记录原始 MQTT 文本，避免 JSON 转换开销：本场景的消息内容已经是 JSON 文本，日志无需先解析 JSON 再格式化成字符串，SDK 以字节提供载荷时只需按需做 UTF-8 解码；当前接收回调先解析再以 prettyPrinted 输出，973 条遥测展开约 20 万行、4.85 MB（不是原始 MQTT 传输量）；建议日志入口仅将原始载荷副本投递至专用队列，直接记录原始文本，取消日志对 JSON 解析、重新序列化和美化输出的依赖，减少 CPU、内存及日志体积开销，业务处理所需的 JSON 解析仍保留一次（PCMqttService.swift:615、619、629、642；PCGlobalUtils.swift:336）。
        • 文件日志需要攒批写入：现有源码是较早版本，后续版本已新增文件日志（现场补充）；建议在专用串行日志队列中按条数、字节数或时间窗口攒批落盘，减少逐条写入的存储 I/O 开销，并测量实际收益；旧版仅能定位日志入口，后续写文件实现未提供（PCGlobalUtils.swift:336）。
        • MQTT 消息队列需按业务与回复主题细分：当前 App 在统一接收回调中先解析、输出日志，再按主题处理并向主队列分发，IoT 遥测与直播控制共享这段处理路径；Web 已按回复主题路由消息，各 RPC 实例使用独立发送队列，WebRTC 组件另有信令输入、输出队列；建议参考这种组织方式，将 IoT 遥测、在线状态/ICE 配置和 WebRTC 信令分成独立处理通道，入口按主题快速入队，同通道保持顺序、不同通道独立调度，只将必要 UI 更新交给主队列，减少批量遥测对建连控制的阻塞；同一 MQTT 连接、broker 与跨国链路上的传输积压仍需另行优化（App：PCMqttService.swift:615、683、847；Web：use-mqtt-request.ts:36、42、use-device-prefix-rpc.ts:59、83、webrtc-live-p2p-1.tsx:73、83、182、188）。
        • 高频遥测增加主队列负担：接收后的配置通知逐条投递主队列，再合并设备状态、更新视图；建议按设备合并可覆盖的状态更新并限制刷新频率，避免历史积压连续触发 UI 更新（PCMqttService.swift:781、847、927；PCPlayerServiceHolder.swift:648）。
        • 延迟缺少分段耗时证据：发送日志早于实际 publish，接收日志晚于 JSON 解析和格式化，12.545 秒不能全部归给落盘或网络；应关联记录收包、解析、日志入队及实际写入、主队列处理时间，并结合 broker 追踪区分服务端排队与客户端处理（PCMqttService.swift:543、615）。
        • 直播建连串行导致等待逐段累加：同一设备当前依次经历在线查询 → 获取或复用 ICE 配置 → 创建 WebRTC 连接 → 查询播放模式 → P2P/SFU 协商，前一步完成后才启动下一步，各阶段的处理、排队及网络往返等待会累加，历史积压和跨国网络会进一步拉长总耗时；建议参考 Web，在拿到设备列表后提前、并行准备可独立获取的在线状态和 ICE 配置，让播放器复用已准备的结果，减少建连关键路径中的串行等待，同时保留必要的在线状态、配置和 SDP 就绪检查（PCWebRtcLiveService.swift:147、504、364、547）。
        • 连接配置需由直播客户端提前推送给设备：设备端被动接收 ICE（STUN/TURN）配置，客户端取得设备在线状态及连接配置后，应在发起视频协商前主动下发；当前所给 App 代码收到配置后用于本地 WebRTC，未见对应的设备侧 ICE 配置下发步骤；建议参考 Web，将获取配置和向设备推送前置到直播准备阶段，减少点击开播后的等待，并核实逐设备接收、应用情况，不能把 MQTT 发布完成等同于设备配置已生效（设备被动接收为现场补充；App：PCWebRtcLiveService.swift:527、364；Web：use-ice-server-deliver.ts:23、50）。
        • TURN 凭据轮换要求定期刷新连接配置：服务端出于凭据安全考虑，每次版本升级都会重新生成 TURN 认证密码；当前 App 仅在 ICE 缓存为空时请求配置，且配置回复只在准备建连阶段处理，长期复用旧配置可能在服务器升级后导致 TURN 认证失败并增加重试等待；应将配置刷新从单次建连流程中拆出，定时获取并替换旧缓存，配置变化时重新推送给设备，重连或认证失败时及时补拉，确保 App 与设备使用有效配置（服务端密码轮换机制为现场补充；PCWebRtcLiveService.swift:513、527；PCMqttService.swift:343）。
        • 首次在线状态补齐缺少快慢分档：当前每 30 秒定时查询，并在订阅成功后立即补查；结果尚未齐备时可提高补查频率，取得有效结果后降低频率，减少用户等待下一轮查询的时间（PCConnectManager.swift:305；PCPlayerServiceHolder.swift:564）。
        • 关键直播指令缺少 MQTT 接收确认：发送默认使用 QoS 0，可评估关键指令改用 QoS 1，并继续以设备业务回复确认执行结果；broker 接收确认不能代替设备执行成功（PCMqttService.swift:490、543）。
        • 指令发送未统一等待回复订阅就绪：发送入口只检查 MQTT 已连接，订阅回调即使存在失败项也会冲刷待发队列，可能出现请求已发送但回复接收尚未准备好的窗口；应以必需回复主题订阅成功作为发送条件（PCMqttService.swift:543、603）。
        • 重连可能丢失超时检查：旧的同名计时任务未清理时，新任务注册会被跳过，旧回调又可能因连接代次变化而退出；应在重建连接时同步取消并重建超时任务（PCTimerManager.swift:62；PCWebRtcLiveService.swift:238、1156）。
        • 在线回复未关联具体建连请求：回复只按设备编号分发，定时查询或较早请求的回复也可能推进当前连接；应补充请求关联及连接代次校验，避免旧结果影响新连接（PCPlayerServiceHolder.swift:581；PCWebRtcLiveService.swift:504）。
        • 本客户端占用判断存在恒真条件：connectMode != .P2P || connectMode != .P2P_ 始终成立，可能误发离开指令；应修正条件并核对各连接状态下的占用处理（PCWebRtcLiveService.swift:646）。
        • 占用者 ID 缺失被误判为他人占用：接收层将缺失 ID 转为空字符串，后续仅判断 nil，导致空 ID 进入他人占用分支；应明确区分本客户端占用、其他客户端占用和身份未知（PCMqttService.swift:760；PCWebRtcLiveService.swift:644）。
        • 控制指令补发缺少统一边界：播放分支设有补发次数上限，暂停分支没有对应上限，关键帧请求缺少独立补发机制；应分别限定次数、等待时间和终止条件，减少无效等待与重复控制（PCWebRtcLiveService.swift:1188、973）。
        • 首帧等待缺少超时恢复：WebRTC 连接成功后即取消建连计时器，但等待首帧没有独立超时，可能长时间停在加载状态；应为首帧等待补充超时与恢复策略（PCWebRtcLiveService.swift:979、1223）。
    • 30 日
      • ✅ 协作 帮郭工排查 app 直播连接速度慢的原因. 耗时 2h
        • 用实际业务场景推演来说明问题
        • 微信会议沟通
Last updated on
2026年09月21日2026年10月05日