|
700
|
23
|
42
|
1
|
|
0
|
需求 小程序设置导出 16583
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1784696709
|
1784696723
|
1784696723
|
0
|
0
|
0
|
Edit
Delete
|
|
702
|
23
|
43
|
1
|
|
0
|
需求 小程序设置导出 16583
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1784772728
|
1784772735
|
1784772735
|
0
|
0
|
0
|
Edit
Delete
|
|
706
|
23
|
44
|
1
|
|
0
|
bug-V2平台调音-1的商家id不显示问题
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1784802032
|
1784802046
|
1784802046
|
0
|
0
|
0
|
Edit
Delete
|
|
710
|
23
|
45
|
1
|
|
0
|
111
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1784874629
|
1784874643
|
1784874643
|
0
|
0
|
0
|
Edit
Delete
|
|
711
|
23
|
46
|
1
|
|
0
|
bug-V2平台调音-1的商家id不显示问题
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1784874674
|
1784874685
|
1784874685
|
0
|
0
|
0
|
Edit
Delete
|
|
716
|
23
|
47
|
1
|
|
0
|
其他
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1785224273
|
1785224279
|
1785224279
|
0
|
0
|
0
|
Edit
Delete
|
|
717
|
23
|
48
|
1
|
|
0
|
其他
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1785224288
|
1785224294
|
1785224294
|
0
|
0
|
0
|
Edit
Delete
|
|
723
|
23
|
49
|
1
|
|
0
|
111
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1786339385
|
1786339390
|
1786339390
|
0
|
0
|
0
|
Edit
Delete
|
|
724
|
23
|
50
|
1
|
|
0
|
111
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1786339403
|
1786339409
|
1786339409
|
0
|
0
|
0
|
Edit
Delete
|
|
729
|
23
|
51
|
1
|
|
0
|
111
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1786438592
|
1786438597
|
1786438597
|
0
|
0
|
0
|
Edit
Delete
|
|
730
|
23
|
52
|
1
|
|
0
|
111
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1786438614
|
1786438619
|
1786438619
|
0
|
0
|
0
|
Edit
Delete
|
|
733
|
23
|
53
|
1
|
|
0
|
需求 增加包厢筛选参数 16722
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1786672377
|
1786672401
|
1786672401
|
0
|
0
|
0
|
Edit
Delete
|
|
752
|
23
|
54
|
1
|
|
0
|
编译
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1787640115
|
1787640123
|
1787640123
|
0
|
0
|
0
|
Edit
Delete
|
|
753
|
23
|
55
|
1
|
|
0
|
编译
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1787640140
|
1787640147
|
1787640147
|
0
|
0
|
0
|
Edit
Delete
|
|
771
|
23
|
56
|
1
|
|
0
|
1111
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1788426740
|
1788426764
|
1788426764
|
0
|
0
|
0
|
Edit
Delete
|
|
772
|
23
|
57
|
1
|
|
0
|
1111
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1788426774
|
1788426780
|
1788426780
|
0
|
0
|
0
|
Edit
Delete
|
|
780
|
23
|
58
|
1
|
|
0
|
包厢续费小程序码
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1789436552
|
1789436571
|
1789436571
|
0
|
0
|
0
|
Edit
Delete
|
|
781
|
23
|
59
|
1
|
|
0
|
包厢续费小程序码
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1789436596
|
1789436624
|
1789436624
|
0
|
0
|
0
|
Edit
Delete
|
|
788
|
23
|
60
|
1
|
|
0
|
需求 回访任务批量作废 16852
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1789718392
|
1789718403
|
1789718403
|
0
|
0
|
0
|
Edit
Delete
|
|
767
|
24
|
1
|
4
|
|
0
|
[后台管理] 按省市统计设备月度新增上线数量报表
|
## 关联 Issue
Close #4 — [后台] 按省市统计设备月度新增上线数量报表
（I ## 关联 Issue
Close #4 — [后台] 按省市统计设备月度新增上线数量报表
（Issue 位于另一仓库 laiqiaojie/jh-project，Gitea 跨仓库 `Close #N` 不会自动关联，merge 后需手动去 jh-project 更新 Issue 状态）
## 变更说明
- 新增 `DeviceOnlineStats` 控制器，暴露 `getProvinceStats`（按月+省份汇总新增上线设备数）、`getCityStats`（指定省份后按城市下钻）两个接口
- `Ahead_authenticate_log_model` 新增对应查询方法：联表 `ahead_authenticate_log` → `ahead_family_servers` → `ahead_yc_shop`，权限过滤复用现有 `Ahead_manage_user_model::check_is_agent()`（超管看全国，运营商强制按 `shop._agent_id` 过滤）
- 与 plan.md 的偏差：实现与计划一致；另外在 `/code-review` 中发现并修复了两个问题（均已回归验证）：
- `month` 参数只校验格式未校验取值范围，如 `2026-00` 会被 `strtotime` 静默接受为上一年 12 月而不报错 → 正则改为 `(0[1-9]|1[0-2])` 严格校验月份范围
- 未绑定门店的设备（`room._shop_id` 为 0/未匹配）会被计入 `total` 但在 `GROUP BY shop._province` 时产生一个 province 为 null 的脏分组 → 加 `room._shop_id > 0` 过滤
## 测试说明
- 本地起 PHPStudy，登录后手动调用两个接口验证：正常月份返回 `{code:0, result:{total, list}}`；缺 `month`/非法月份（`2026-00`、`2026-13`、`0000-00`）均正确返回 400
- 用只读 SQL 直接查了云端开发库确认 JOIN 链路正确——本地测试库 `ahead_authenticate_log` 表只有 1 条 2021 年的历史数据，所以当月查询返回空列表是预期行为，不是 bug
- `tests/api/smoke.mjs` 里补充了对应的自动化用例，但该冒烟测试框架整体依赖另一个尚未推送到 `admin` 分支的提交（`694e34c`，属于另一项未提交的工作，不在本 Issue 范围内），为保持本 PR 改动范围干净，本次未包含测试框架文件，仅代码改动
- 需要 Tech Lead 重点看：`check_is_agent()` 权限过滤范围是否符合预期；`room._shop_id > 0` 过滤是否会误伤合法数据
## 产物归档
- Plan：[plan/device-online-stats-by-region-admin.md](https://gitea.g-hi.com/laiqiaojie/jh-project/src/branch/design/device-online-stats-by-region/plan/device-online-stats-by-region-admin.md)（位于 laiqiaojie/jh-project 仓库）
...
|
0
|
0
|
1
|
1
|
1
|
|
0
|
1788244598
|
1788246926
|
1788245236
|
0
|
0
|
0
|
Edit
Delete
|
|
769
|
24
|
2
|
4
|
|
0
|
[Web前端] 按省市统计设备月度新增上线数量报表
|
## 关联 Issue
Related to laiqiaojie/jh-project#5
Re ## 关联 Issue
Related to laiqiaojie/jh-project#5
Related to laiqiaojie/jh-project#8 — 按省市统计设备月度新增上线数量报表（Web 前端）
## 变更说明
- 新增 页面组件
- 省份视图：横向柱状图展示各省份当月新增上线设备数，点击下钻城市
- 城市视图：横向柱状图展示选定省份各城市分布，面包屑返回全国
- 使用 CSS 自定义 bar（不引入 ECharts），保持项目依赖不变
- 更新 ：注册 device_online_stats 组件
- 更新 ：新增 路由规则
- **修复** ： 在父菜单 为空时拼出 双斜杠，导致路由匹配失败
- **修复** ： 同一根因的双斜杠问题
## 测试说明
- 月份切换后图表重新加载
- 点击省份柱子进入城市视图，面包屑显示「全国 › XX省」
- 点击「全国」/「返回全国」返回省份视图
- 无数据月份显示空状态
- 点击「数据」顶部菜单 → 侧栏「设备上线分布」→ 组件正常渲染（已端到端验证）
## DB 变更（需手动执行）
## 产物归档
- Plan：（在 jh-project 仓库）
- 设计文档：
🤖 Generated with [Claude Code](https://claude.com/claude-code)...
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1788247154
|
1789379914
|
1789377273
|
0
|
3
|
0
|
Edit
Delete
|
|
283
|
25
|
1
|
1
|
|
0
|
🔍 代码审查报告：api - 11
|
## 自动代码审查报告
**分支**: api
**提交**: `f1638c3adf2bcd34 ## 自动代码审查报告
**分支**: api
**提交**: `f1638c3adf2bcd34796a5bd8afe7ade89a6ec836`
**提交人**: zhangjunnan (121158035@qq.com)
**时间**: 2026-05-22 10:19:57
---
## 1. 审查摘要
- **代码质量评分**：4/10 分
- **总体评价**：代码实现了阿里云 MQTT 消息推送与基础 HTTP 请求封装，具备初步的业务可用性。但存在**严重的安全隐患**（硬编码云密钥）、**核心逻辑缺陷**（数组操作错误、异常吞没）、**规范缺失**（非标准函数调用、调试代码未清理、注释乱码）及**框架适配不足**。整体处于“可运行但不可投产”状态，需优先进行安全加固与逻辑修复。
- **风险等级**：🔴 高
## 2. 问题详情
| 严重程度 | 文件/行号 | 问题描述 | 建议修改方案 | 代码示例 (可选) |
| :--- | :--- | :--- | :--- | :--- |
| 🔴 严重 | `Mqttapi.php` L10-11 | 硬编码阿里云 `AccessKey` 与 `Secret`。一旦代码提交至版本库，将直接导致云账号资源泄露与被恶意调用。 | 移除硬编码，改用环境变量或框架配置中心动态读取。 | `self::$accessKeyId = getenv('ALIBABA_CLOUD_ACCESS_KEY_ID') ?: config('mqtt.ak');` |
| 🔴 严重 | `HttpRequest.php` L118 | `removeSignHeader` 使用 `unset($this->signHeaders[$value])`，但 `$signHeaders` 是索引数组（值数组），`unset` 会尝试删除不存在的键，导致静默失败或误删。 | 使用 `array_search` 定位真实索引后再 `unset`。 | `$key = array_search($value, $this->signHeaders, true); if ($key !== false) unset($this->signHeaders[$key]);` |
| 🔴 严重 | `Mqttapi.php` L8 | `import()` 非 PHP 原生函数。若 `phpci` 框架未全局注册该辅助函数，将直接触发 `Fatal Error`。 | 改用标准 `require_once` 或依赖 Composer 自动加载机制。 | `require_once COMMONCLASS . 'AliCloudPHPSDK/vendor/autoload.php';` |
| 🟠 警告 | `Mqttapi.php` L45-51 | `catch (Exception $error)` 未加全局命名空间前缀 `\`，在 `use` 命名空间下可能捕获不到异常；且直接 `return false` 掩盖了真实错误堆栈，极难排查。 | 捕获 `\Exception`，记录日志并抛出或返回结构化错误对象。 | `catch (\Exception $e) { log_message('error', $e->getMessage()); throw $e; }` |
| 🟠 警告 | `HttpClient.php` L15-16 | 超时值设为 `30000`/`80000`，注释却标注 `30 second`。底层若使用 cURL，默认单位为秒，数值过大会导致请求长时间挂起。 | 统一单位。若底层支持毫秒请明确注释，否则改为秒级整数。 | `private static $connectTimeout = 30; // 单位：秒` |
| 🟠 警告 | `Demo.php` L12, L48, L50 | 文件被 `include` 时直接实例化并执行请求，且残留 `var_dump` 和 `print_r`。违反库文件“只定义不执行”原则，且调试信息会污染生产环境输出。 | 移除顶层执行逻辑与调试输出，将调用移至 `phpci` 控制器或 CLI 入口。 | 删除 `include` 后的 `$demo = new Demo(); ...` 代码块 |
| 🟡 建议 | `HttpRequest.php` L33, L43, L53... | 多处 `if (null == $this->headers) { $this->headers = array(); }` 属冗余代码。属性已在声明时初始化，且 PHP 数组赋值不会自动变为 `null`。 | 直接移除冗余判断，保持代码简洁。 | 删除所有 `if (null == $this->xxx)` 块 |
| 🟡 建议 | `Constants.php` 全文 | 注释出现大量乱码（如 `ͨó`, `ǩ㷨`），表明文件保存编码与声明编码不一致（疑似 GBK 混入 UTF-8）。 | 使用编辑器统一转换为 `UTF-8 无 BOM` 编码，并修正注释内容。 | 无 |
| 🟡 建议 | `Mqttapi.php` L38 | `$args` 参数未声明类型，且直接作为 `payload` 传入 SDK。若传入非字符串/数组，SDK 可能抛出类型异常。 | 补充类型提示，并在内部进行 JSON 序列化或类型校验。 | `public static function main(string $mqttTopic, array|string $payload)` |
## 3. 总结与行动建议
### 🔑 优先修复项（P0）
1. **密钥安全治理**：立即将 `Mqttapi.php` 与 `Demo.php` 中的硬编码 AK/SK 迁移至 `phpci` 的配置文件（如 `config/mqtt.php`）或服务器环境变量中，严禁明文提交至代码库。
2. **修复数组操作 Bug**：修正 `HttpRequest::removeSignHeader()` 的删除逻辑，避免签名头清理失败导致 API 鉴权报错。
3. **替换非标准函数**：将 `import()` 替换为 `require_once` 或接入 Composer 自动加载，确保代码在标准 PHP 环境中可独立运行。
### 🛠 后续重构与优化方向
1. **框架适配规范**：
- `apitest/` 目录结构不符合常规 MVC 框架规范。建议将其迁移至 `phpci` 的 `app/` 或 `application/` 目录下，利用框架的路由、配置加载与日志组件。
- 避免在类文件中直接执行逻辑（如 `Demo.php` 的顶层调用），应通过框架控制器接收请求并分发。
2. **代码规范升级**：
- 全面补充 PHP 7.4+/8.x 类型声明（参数类型、返回值类型、属性类型），提升静态分析能力。
- 遵循 PSR-12 规范：统一缩进（4空格）、移除冗余空行、规范命名空间与 `use` 语句顺序。
3. **健壮性增强**：
- `Mqttapi::main()` 建议改为返回 `Result` 对象或抛出业务异常，而非简单返回 `false`，便于上层统一处理成功/失败/重试逻辑。
- 统一超时单位，并在 `HttpClient` 中增加对 `HttpUtil` 底层实现的依赖注入或配置化，避免硬编码网络参数。
> 📌 **局限性说明**：本次审查未提供 `HttpUtil.php` 源码及 `phpci` 框架的具体生命周期/配置加载机制。若 `HttpUtil` 内部对 cURL 选项或签名算法有特殊处理，请结合实际底层实现进行二次验证。建议查阅 `phpci` 官方文档中关于“第三方 SDK 集成”与“配置管理”的章节，以确保架构一致性。
---
*此 Issue 由代码审查服务自动创建*...
|
0
|
0
|
0
|
0
|
0
|
|
0
|
1779416397
|
1779416397
|
0
|
0
|
0
|
0
|
Edit
Delete
|
|
412
|
25
|
2
|
1
|
|
0
|
🔍 代码审查报告：api-260616 - 需求 时序设备api控制 16449
|
## 自动代码审查报告
**分支**: api-260616
**提交**: `30d690ac9 ## 自动代码审查报告
**分支**: api-260616
**提交**: `30d690ac959cffb607e3e7aa6960476d839e5290`
**提交人**: chenjunfeng (developer.jeff.c@gmail.com)
**时间**: 2026-05-29 16:49:32
---
## 1. 审查摘要
- **代码质量评分**：5/10 分
- **总体评价**：代码实现了较为完整的包厢控制与状态管理业务，但存在多处**严重逻辑漏洞**（如响应重复输出、未定义变量、条件判断错位）、**数据一致性风险**（多表更新无事务）以及**代码规范问题**（命名混乱、魔法数字、死代码）。整体可维护性与生产环境稳定性较低，需优先修复核心逻辑缺陷并统一错误处理机制。
- **风险等级**：🔴 高
> 📌 **框架说明**：根据目录结构 (`system/`, `application/`, `$this->load->model()`, `FCPATH`) 判断，实际使用的应为 **CodeIgniter 3.x** 框架。若 `phpci` 为贵司内部定制/分支框架，请结合其官方文档对加载器、响应机制进行适配。以下审查基于 CI3 标准实践。
## 2. 问题详情
| 严重程度 | 文件/方法 | 问题描述 | 建议修改方案 | 代码示例 (可选) |
| :--- | :--- | :--- | :--- | :--- |
| 🔴 严重 | `showNotice()` / `closeNotice()` | **响应重复输出/不可达代码**：在 `if/else` 已调用 `success_response` 或 `error_response` 后，末尾又追加了 `$this->success_response([], "成功");`。若响应函数包含 `exit` 则死代码；若不含则会导致重复输出或 Header 已发送错误。 | 移除方法末尾的冗余响应调用，确保每个执行路径仅返回一次。 | `if ($success) { $this->success_response(); } else { $this->error_response(); } return;` |
| 🔴 严重 | `transferRoom()` | **逻辑错误/查询条件错位**：构建 `$new_room_data` 查询条件时，错误地使用了旧包厢变量 `$room_name` 和 `$family_server_id` 进行非空判断，导致新包厢可能查询失败或查错数据。 | 将判断条件修正为新包厢对应变量 `$new_room_name` 与 `$new_family_server_id`。 | `if (!empty($new_room_name)) { $where['_name'] = $new_room_name; }`<br>`if (!empty($new_family_server_id)) { $where['_family_server_id'] = $new_family_server_id; }` |
| 🔴 严重 | `upRoomQrcode()` | **未定义变量 & 死代码**：`$arr` 未定义即被访问；且 `$res` 赋值后未使用，直接调用了 `success_response`，后续 `if(isset($arr...))` 为无效逻辑。 | 删除未使用的 `$arr` 判断块，或正确解析 `$res` 结果后再响应。 | 移除末尾 `if (isset($arr['response'])...)` 整个代码块。 |
| 🔴 严重 | `updateRoomStatus()` / `transferRoom()` | **数据一致性风险**：涉及 `family_servers`、`open_room_log`、`bill` 等多表联动更新，但未使用数据库事务。若中途网络中断或逻辑报错，将产生脏数据（如已开房但无账单、状态不一致）。 | 使用 CI3 事务机制包裹核心写操作，失败时自动回滚。 | `$this->db->trans_start();`<br>`// 执行 insert/update`<br>`$this->db->trans_complete();`<br>`if ($this->db->trans_status() === FALSE) { $this->db->trans_rollback(); throwError("操作失败"); }` |
| 🟠 警告 | `updateRoomStatus()` | **死代码分支**：`elseif ($update_status == 3 && false)` 中的 `&& false` 导致该分支永远无法执行，疑似调试遗留。 | 移除 `&& false` 或根据业务需求恢复逻辑，清理无用代码。 | `elseif ($update_status == 3) { // 清扫逻辑 }` |
| 🟠 警告 | 全局多处 | **同步网络请求阻塞**：`send_web_socket()`、`send_room_msg()` 等为同步阻塞调用，未设置超时时间。若下游服务响应慢，将直接拖垮 PHP-FPM 进程池导致 API 超时。 | 为底层 Socket 请求添加 `timeout` 参数，或引入消息队列（如 Redis/RabbitMQ）异步下发指令。 | `send_room_msg($id, $data, $server, ['timeout' => 3]);` |
| 🟠 警告 | `RenewalReminder()` / `consumptionEnd()` 等 | **输入验证缺失**：直接信任 `$this->stream`，未对 `$params['title']`、`$params['img_url']` 等进行长度、格式或 XSS 过滤。 | 引入统一参数校验层（如 CI `form_validation` 或自定义 DTO），对字符串进行 `trim()`、`htmlspecialchars()` 或白名单校验。 | `$title = trim(htmlspecialchars($params['title'] ?? '', ENT_QUOTES, 'UTF-8'));` |
| 🟡 建议 | 全局方法命名 | **命名不规范**：方法名混用驼峰与下划线（如 `RenewalReminder`、`getSlefBill`、`reboot_room`），且存在拼写错误 (`Slef` -> `Self`)。 | 严格遵循 PSR-12，统一使用 `camelCase`，修正拼写错误。 | `public function renewalReminder()`<br>`public function getSelfBill()` |
| 🟡 建议 | 全局魔法数字 | **魔法数字泛滥**：`31`, `9063`, `0,1,2,3`, `86400`, `1440`, `100` 等硬编码散落在各处，降低可读性且易引发维护错误。 | 提取为类常量或配置文件，集中管理。 | `const STATUS_FREE = 0; const STATUS_OPEN = 1;`<br>`const MAX_VOICE_VOL = 100;` |
| 🟡 建议 | 全局模型加载 | **重复加载模型**：每个方法内部频繁调用 `$this->load->model()`，虽 CI 支持重复加载，但增加 I/O 开销且不符合最佳实践。 | 将高频使用的模型移至 `__construct()` 或 `config/autoload.php` 中预加载。 | `public function __construct() { parent::__construct(); $this->load->model('Ahead_family_servers_model'); }` |
## 3. 总结与行动建议
### 🚨 优先修复的关键问题（P0）
1. **修复响应逻辑漏洞**：立即清理 `showNotice`、`closeNotice`、`upRoomQrcode` 中的重复响应与未定义变量 `$arr`，避免 API 返回异常或触发 PHP Warning。
2. **修正 `transferRoom` 查询条件**：将新包厢查询的 `if (!empty($room_name))` 改为 `if (!empty($new_room_name))`，否则转房功能在特定参数组合下必然失败。
3. **引入数据库事务**：在 `updateRoomStatus` 和 `transferRoom` 的核心状态流转逻辑外层包裹 `$this->db->trans_start()` 与 `$this->db->trans_complete()`，保障业务数据强一致性。
### 🛠 后续重构与优化方向
1. **统一错误处理机制**：当前混用 `throwError()` 与 `$this->error_response()`。建议定义统一的 `ApiResponse` 基类或中间件，所有异常捕获后统一格式化为 JSON 输出，避免部分路径直接 `exit` 导致日志丢失或前端解析失败。
2. **构建参数校验层**：`$this->stream` 为自定义输入源，建议封装 `validateParams(array $rules)` 方法，集中处理类型转换（`intval`/`floatval`）、边界限制（`max/min`）与安全过滤，消除各方法中重复的 `if/empty` 校验块。
3. **异步化网络指令**：包厢控制指令（WebSocket/Socket）属于高延迟操作。建议将指令下发改为写入 Redis 队列，由独立 Worker 消费并处理重试/超时逻辑，API 仅返回“指令已接收”，大幅提升接口吞吐与稳定性。
4. **遵循 PSR-12 与 DRY 原则**：统一方法命名风格，提取重复的音量/倒计时校验逻辑为 `private function validateDuration()` 等私有方法；清理所有注释掉的废弃代码，保持代码库整洁。
> 💡 **提示**：若 `phpci` 框架对控制器生命周期、模型加载或响应机制有特殊约定，请优先查阅其官方文档。上述建议已兼容标准 PHP 生态与 CI3 架构，可直接平滑迁移。
---
*此 Issue 由代码审查服务自动创建*...
|
0
|
0
|
0
|
0
|
0
|
|
0
|
1780044572
|
1780044572
|
0
|
0
|
0
|
0
|
Edit
Delete
|
|
554
|
25
|
3
|
1
|
|
0
|
🔍 代码审查报告：api-260616 - 需求 时序设备api控制日志记录 16449
|
## 自动代码审查报告
**分支**: api-260616
**提交**: `7e447e7f3 ## 自动代码审查报告
**分支**: api-260616
**提交**: `7e447e7f32b5ff41344ec17d2fa199cbc015a5ae`
**提交人**: chenjunfeng (developer.jeff.c@gmail.com)
**时间**: 2026-06-05 13:27:14
---
⚠️ **重要提示**：您提供的输入中仅包含项目目录结构，**未包含具体的 `变更文件内容`**。根据约束要求，若代码片段缺失或过短，我将明确指出局限性并提供基于该架构的审查预案。请补充具体代码（Git Diff 或修改后的文件内容）后，我将立即输出精准到行号的深度审查报告。
以下为基于当前输入的标准审查报告模板：
## 1. 审查摘要
- **代码质量评分**：`N/A (待补充代码)`
- **总体评价**：当前输入仅展示项目结构，未提供实际变更代码。从目录特征判断，该系统采用典型的 MVC 架构（高度类似 CodeIgniter 3 或内部衍生的 `phpci` 框架），核心组件（数据库驱动、会话管理、缓存、辅助函数）划分清晰。待代码提交后，将立即开展五大维度的深度审查。
- **风险等级**：`待评估`
## 2. 问题详情
| 严重程度 | 文件/行号 | 问题描述 | 建议修改方案 | 代码示例 (可选) |
| :--- | :--- | :--- | :--- | :--- |
| ⚪ 待补充 | 全局 | **未提供变更代码/Diff**，无法进行实质性逻辑、安全与性能审查。 | 请提交具体的修改文件路径、行号及变更代码片段。 | - |
| 🟠 警告 | `system/database/DB_driver.php` | *(架构通用预警)* 若新增查询逻辑使用字符串拼接而非参数绑定，将直接暴露 SQL 注入风险。 | 强制使用查询构造器或预处理语句，禁止直接拼接用户输入。 | `$this->db->query('SELECT * FROM users WHERE id = ?', [$id]);` |
| 🟠 警告 | `system/libraries/Session/Session.php` | *(架构通用预警)* 自定义会话驱动若未严格实现 `SessionHandlerInterface` 或未处理并发锁，可能导致会话覆盖或数据不一致。 | 完整实现标准接口，使用原子操作或文件/Redis 锁机制，避免直接 `unserialize` 不可信数据。 | `if (!flock($fp, LOCK_EX)) { throw new Exception('Session lock failed'); }` |
| 🟡 建议 | `system/helpers/*.php` | *(架构通用预警)* 辅助函数若依赖全局变量或隐式状态，将降低可测试性并可能引发内存泄漏。 | 遵循无状态设计，显式传参，避免使用 `global` 或静态缓存未清理的上下文。 | `function format_price($amount, $currency = 'USD') { return number_format($amount, 2); }` |
## 3. 总结与行动建议
- **优先修复**：请补充具体的变更代码内容。收到后我将立即输出包含精确行号、漏洞定位及可直接替换的修复代码的完整报告。
- **后续重构/优化方向**（基于当前架构预判）：
1. **安全基线加固**：重点审查 `DB_driver.php`、`Form_validation.php`、`Security_helper.php` 中的输入过滤、输出转义（`htmlspecialchars`/`xss_clean`）及 CSRF Token 验证逻辑，确保符合 OWASP 防护标准。
2. **性能与资源管理**：针对 `Cache/` 与 `Session/` 驱动，建议引入连接复用、惰性加载与批量操作（如 `Cache::saveMany()`），避免在循环中重复建立数据库/缓存连接。
3. **规范与现代化**：若 `phpci` 为自研或 CI3 衍生框架，建议逐步对齐 PSR-12 规范，引入 PHP 7.4+ 类型声明（`declare(strict_types=1);`）、属性类型提示及命名空间，提升静态分析兼容性与可维护性。
4. **框架生命周期适配**：确保新增/修改的库或辅助函数正确接入框架的钩子（Hooks）或事件总线，避免破坏 `pre_system` → `post_controller` 的请求生命周期。
📥 **下一步**：请回复具体的变更代码（支持 Git Diff 格式或完整文件内容）。我将严格依照 PSR-12、安全编码规范及 `phpci` 框架最佳实践，为您生成精准、可落地的审查报告。
---
*此 Issue 由代码审查服务自动创建*...
|
0
|
0
|
0
|
0
|
0
|
|
0
|
1780637234
|
1780637234
|
0
|
0
|
0
|
0
|
Edit
Delete
|
|
690
|
25
|
4
|
1
|
|
0
|
需求 时序设备api控制 16449
|
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1783048848
|
1783048853
|
1783048853
|
0
|
0
|
0
|
Edit
Delete
|
|
673
|
32
|
1
|
1
|
|
0
|
222
|
|
0
|
0
|
0
|
1
|
0
|
|
0
|
1781158798
|
1781158798
|
0
|
0
|
0
|
0
|
Edit
Delete
|
|
691
|
50
|
1
|
5
|
|
0
|
fix(web): update Lyra product labels
|
<!--
PR 治理模板。提交前请逐项确认，确保符合 docs/standards 下的 <!--
PR 治理模板。提交前请逐项确认，确保符合 docs/standards 下的工程规范。
CI 会执行：pnpm check（命名 + 单源漂移 + 治理棘轮 + lint + typecheck）；
有测试 DB 的流水线另执行 DATABASE_URL=... pnpm check:runtime。
-->
## 变更内容
<!-- 简述这次改了什么、为什么改（聚焦 why） -->
-
## 涉及业务概念
<!-- 列出涉及的业务词典英文名，例如 store / order / verification。参见 docs/domain-glossary.md -->
-
## 检查清单
### 命名一致性
- [ ] 业务概念使用了词典中的标准英文名（未出现 shop/branch/seller/voucher/writeOff 等禁用词）
- [ ] 数据库 snake_case + 复数表名；API/JSON 字段 camelCase；类型 PascalCase；常量 SCREAMING_SNAKE_CASE
- [ ] `pnpm check:naming` 通过
- [ ] `pnpm check:schema` 通过，未新增第二份状态/契约真源
### API / 契约
- [ ] 不涉及 API 变更
- [ ] 新增/修改了 API，路由符合 `/api/v1/{resources}` 规范
- [ ] 已更新 `packages/contracts` 中的 Zod schema / DTO / 类型（前后端共用同一份）
- [ ] 无破坏前端兼容的字段删除/重命名（如有，已在描述中说明迁移方案）
### 数据库
- [ ] 不涉及数据库变更
- [ ] 新增/修改了表或字段，已通过 migration review（表名复数、字段 snake_case、外键 xxx_id、时间 _at、状态 status）
- [ ] 高增长表已考虑分区；涉及多租户的表带 tenant_id
- [ ] 写链显式带 tenant_id；跨租户读写按 404/隔离口径处理
### 数据库迁移（迁移即代码：版本/顺序/内容/环境/发布/回滚一致）
- [ ] 改 schema.prisma 的同时**已生成并提交 migration**（`pnpm db:migrate:dev --name <change>`），未只改 schema 不落迁移
- [ ] **未修改已发布过的历史 migration 文件**（内容一致：历史不可变，新变更走新迁移）
- [ ] `pnpm check:migrations` 通过（迁移历史在位 / 无未豁免高危 DDL / schema 表、enum、`@map` 列均已落迁移）
- [ ] 破坏性变更（删表/删列/改名/改类型/加 NOT NULL/加唯一约束）走 **expand→migrate→contract** 三阶段，不一次切
- [ ] 大表加索引用 `CREATE INDEX CONCURRENTLY`；大批量回填走 BullMQ 分批任务，不塞进 migration
- [ ] 高危但确需的 DDL 已加 `-- migration-allow:<原因>` 留痕，并在下方回滚方案说明
- [ ] 非开发环境只用 `migrate deploy`（禁止 `db push` / 线上手动 ALTER）；发布前 `pnpm db:migrate:status` 无 drift
### 实时 / 队列
- [ ] 不涉及
- [ ] 关键业务事件进入 BullMQ 或持久化事件表（未仅依赖 Redis Pub/Sub）
- [ ] 写库事件与真实写操作在同一 tx 写入 outbox，未在 commit 后旁路 publish
- [ ] 实时通道选型符合规范（订单/看板/通知用 SSE；设备在线/包间控制/IM 用 WebSocket）
### 质量与发布
- [ ] 通过 `pnpm lint` 与 `pnpm typecheck`
- [ ] 通过 `pnpm check:governance`，`reports/*.latest.json` 已刷新且无棘轮回退
- [ ] 涉及写链 / DB / 租户 / 状态机时，通过 `DATABASE_URL=... pnpm check:runtime`，`reports/runtime-acceptance.latest.json` 已刷新
- [ ] 已补充/更新必要的测试
- [ ] 不需要回滚方案
- [ ] 需要回滚方案，已在下方说明
## 回滚方案 / 其他说明
-
...
|
0
|
0
|
0
|
1
|
0
|
|
0
|
1783327279
|
1783431501
|
0
|
0
|
0
|
0
|
Edit
Delete
|
|
692
|
57
|
1
|
5
|
|
0
|
feat(material-factory): 图像模型真实推理对接 + 双后端渲染管线闭环
|
<!--
PR 治理模板。提交前请逐项确认，确保符合 docs/standards 下的 <!--
PR 治理模板。提交前请逐项确认，确保符合 docs/standards 下的工程规范。
CI 会执行：pnpm check（命名 + 单源漂移 + 治理棘轮 + lint + typecheck）；
有测试 DB 的流水线另执行 DATABASE_URL=... pnpm check:runtime。
-->
## 变更内容
<!-- 简述这次改了什么、为什么改（聚焦 why） -->
-
## 涉及业务概念
<!-- 列出涉及的业务词典英文名，例如 store / order / verification。参见 docs/domain-glossary.md -->
-
## 检查清单
### 命名一致性
- [ ] 业务概念使用了词典中的标准英文名（未出现 shop/branch/seller/voucher/writeOff 等禁用词）
- [ ] 数据库 snake_case + 复数表名；API/JSON 字段 camelCase；类型 PascalCase；常量 SCREAMING_SNAKE_CASE
- [ ] `pnpm check:naming` 通过
- [ ] `pnpm check:schema` 通过，未新增第二份状态/契约真源
### API / 契约
- [ ] 不涉及 API 变更
- [ ] 新增/修改了 API，路由符合 `/api/v1/{resources}` 规范
- [ ] 已更新 `packages/contracts` 中的 Zod schema / DTO / 类型（前后端共用同一份）
- [ ] 无破坏前端兼容的字段删除/重命名（如有，已在描述中说明迁移方案）
### 数据库
- [ ] 不涉及数据库变更
- [ ] 新增/修改了表或字段，已通过 migration review（表名复数、字段 snake_case、外键 xxx_id、时间 _at、状态 status）
- [ ] 高增长表已考虑分区；涉及多租户的表带 tenant_id
- [ ] 写链显式带 tenant_id；跨租户读写按 404/隔离口径处理
### 数据库迁移（迁移即代码：版本/顺序/内容/环境/发布/回滚一致）
- [ ] 改 schema.prisma 的同时**已生成并提交 migration**（`pnpm db:migrate:dev --name <change>`），未只改 schema 不落迁移
- [ ] **未修改已发布过的历史 migration 文件**（内容一致：历史不可变，新变更走新迁移）
- [ ] `pnpm check:migrations` 通过（迁移历史在位 / 无未豁免高危 DDL / schema 表、enum、`@map` 列均已落迁移）
- [ ] 破坏性变更（删表/删列/改名/改类型/加 NOT NULL/加唯一约束）走 **expand→migrate→contract** 三阶段，不一次切
- [ ] 大表加索引用 `CREATE INDEX CONCURRENTLY`；大批量回填走 BullMQ 分批任务，不塞进 migration
- [ ] 高危但确需的 DDL 已加 `-- migration-allow:<原因>` 留痕，并在下方回滚方案说明
- [ ] 非开发环境只用 `migrate deploy`（禁止 `db push` / 线上手动 ALTER）；发布前 `pnpm db:migrate:status` 无 drift
### 实时 / 队列
- [ ] 不涉及
- [ ] 关键业务事件进入 BullMQ 或持久化事件表（未仅依赖 Redis Pub/Sub）
- [ ] 写库事件与真实写操作在同一 tx 写入 outbox，未在 commit 后旁路 publish
- [ ] 实时通道选型符合规范（订单/看板/通知用 SSE；设备在线/包间控制/IM 用 WebSocket）
### 质量与发布
- [ ] 通过 `pnpm lint` 与 `pnpm typecheck`
- [ ] 通过 `pnpm check:governance`，`reports/*.latest.json` 已刷新且无棘轮回退
- [ ] 涉及写链 / DB / 租户 / 状态机时，通过 `DATABASE_URL=... pnpm check:runtime`，`reports/runtime-acceptance.latest.json` 已刷新
- [ ] 已补充/更新必要的测试
- [ ] 不需要回滚方案
- [ ] 需要回滚方案，已在下方说明
## 回滚方案 / 其他说明
-
...
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1783381428
|
1783381594
|
1783381594
|
0
|
0
|
0
|
Edit
Delete
|
|
731
|
57
|
2
|
5
|
|
0
|
chore: add material factory model weights
|
<!--
PR 治理模板。提交前请逐项确认，确保符合 docs/standards 下的 <!--
PR 治理模板。提交前请逐项确认，确保符合 docs/standards 下的工程规范。
CI 会执行：pnpm check（命名 + 单源漂移 + 治理棘轮 + lint + typecheck）；
有测试 DB 的流水线另执行 DATABASE_URL=... pnpm check:runtime。
-->
## 变更内容
<!-- 简述这次改了什么、为什么改（聚焦 why） -->
-
## 涉及业务概念
<!-- 列出涉及的业务词典英文名，例如 store / order / verification。参见 docs/domain-glossary.md -->
-
## 检查清单
### 命名一致性
- [ ] 业务概念使用了词典中的标准英文名（未出现 shop/branch/seller/voucher/writeOff 等禁用词）
- [ ] 数据库 snake_case + 复数表名；API/JSON 字段 camelCase；类型 PascalCase；常量 SCREAMING_SNAKE_CASE
- [ ] `pnpm check:naming` 通过
- [ ] `pnpm check:schema` 通过，未新增第二份状态/契约真源
### API / 契约
- [ ] 不涉及 API 变更
- [ ] 新增/修改了 API，路由符合 `/api/v1/{resources}` 规范
- [ ] 已更新 `packages/contracts` 中的 Zod schema / DTO / 类型（前后端共用同一份）
- [ ] 无破坏前端兼容的字段删除/重命名（如有，已在描述中说明迁移方案）
### 数据库
- [ ] 不涉及数据库变更
- [ ] 新增/修改了表或字段，已通过 migration review（表名复数、字段 snake_case、外键 xxx_id、时间 _at、状态 status）
- [ ] 高增长表已考虑分区；涉及多租户的表带 tenant_id
- [ ] 写链显式带 tenant_id；跨租户读写按 404/隔离口径处理
### 数据库迁移（迁移即代码：版本/顺序/内容/环境/发布/回滚一致）
- [ ] 改 schema.prisma 的同时**已生成并提交 migration**（`pnpm db:migrate:dev --name <change>`），未只改 schema 不落迁移
- [ ] **未修改已发布过的历史 migration 文件**（内容一致：历史不可变，新变更走新迁移）
- [ ] `pnpm check:migrations` 通过（迁移历史在位 / 无未豁免高危 DDL / schema 表、enum、`@map` 列均已落迁移）
- [ ] 破坏性变更（删表/删列/改名/改类型/加 NOT NULL/加唯一约束）走 **expand→migrate→contract** 三阶段，不一次切
- [ ] 大表加索引用 `CREATE INDEX CONCURRENTLY`；大批量回填走 BullMQ 分批任务，不塞进 migration
- [ ] 高危但确需的 DDL 已加 `-- migration-allow:<原因>` 留痕，并在下方回滚方案说明
- [ ] 非开发环境只用 `migrate deploy`（禁止 `db push` / 线上手动 ALTER）；发布前 `pnpm db:migrate:status` 无 drift
### 实时 / 队列
- [ ] 不涉及
- [ ] 关键业务事件进入 BullMQ 或持久化事件表（未仅依赖 Redis Pub/Sub）
- [ ] 写库事件与真实写操作在同一 tx 写入 outbox，未在 commit 后旁路 publish
- [ ] 实时通道选型符合规范（订单/看板/通知用 SSE；设备在线/包间控制/IM 用 WebSocket）
### 质量与发布
- [ ] 通过 `pnpm lint` 与 `pnpm typecheck`
- [ ] 通过 `pnpm check:governance`，`reports/*.latest.json` 已刷新且无棘轮回退
- [ ] 涉及写链 / DB / 租户 / 状态机时，通过 `DATABASE_URL=... pnpm check:runtime`，`reports/runtime-acceptance.latest.json` 已刷新
- [ ] 已补充/更新必要的测试
- [ ] 不需要回滚方案
- [ ] 需要回滚方案，已在下方说明
## 回滚方案 / 其他说明
-
...
|
0
|
0
|
0
|
1
|
0
|
|
0
|
1786603028
|
1786603028
|
0
|
0
|
0
|
0
|
Edit
Delete
|
|
743
|
57
|
3
|
5
|
|
0
|
feat(script): 接入大语言模型——歌词/文案 → 拍摄脚本 → 角色确认 → 定格图
|
本仓此前零 LLM 接入（全仓只有 DashScope 的图像调用），「歌词成图」屏是纯前端
原型 本仓此前零 LLM 接入（全仓只有 DashScope 的图像调用），「歌词成图」屏是纯前端
原型（procedural.ts 画色块 + setTimeout 假装推理，不落库不接后端）。本轮把这条
动线升级为真链路 + 真持久化。
契约单源（packages/contracts/src/script.ts）
- 角色确认状态机 scriptRoleMachine、脚本状态机 shootingScriptMachine
- 景别/运镜用枚举而非自由文本：LLM 一旦自由发挥，下游 prompt 与统计就没有稳定口径
- scriptDraftSchema 是 LLM 输出的唯一判据；prompt 构造器单源，两后端禁止各拼一份
- evaluateRoleReadiness：本域核心不变量，双后端硬拦截 + 前端同源即时反馈
- 前端私有的 findBannedHits 上收为 contracts 的 findBannedWords（后端也要逐镜标记，
两份并行就是双真源）
LLM 不是权威
- sidecar /v1/script 只保证「返回长得像脚本的 JSON」，两个后端各自再 parse 一次才落库
- 模型引用未声明角色键 → 422 SCRIPT_ROLE_KEYS_DANGLING（幻觉护栏）
- 连续给不出合法 JSON → 502 LLM_OUTPUT_UNPARSEABLE，绝不返回占位脚本
- parse_json_object 只剥围栏、截首尾花括号，不做字段猜测或补齐
角色必须先确认才允许出定格图
- 判据 = status CONFIRMED 且有 referenceAssetId（没有参考图就没有一致性锚点）
- CONFIRMED --reset--> DRAFT 会解除参考图绑定：人确认的是那一张图，不是那个名字
- 出图时按 roleKeys 顺序喂参考图，与指令里「第 N 张参考图」编号严格对齐
写链纪律与物料链路同构：tenant 全覆盖、updateMany 带状态前置条件（0 行即 409）、
终态与 outbox 同 tx、能力不可用 → job BLOCKED + 诚实 reason，禁止静默降级。
品牌准绳只逐镜标记不拒绝整份脚本（脚本属创作内容），硬拦截点在出定格图这个受控出口，
显式放行需带参数且落审计事件。
顺带修掉三个既有缺陷
1. 合并遗留：sidecarEdit 用 sidecarGenerateResponseSchema 校验响应（要求 steps/
loadSeconds），但 run_hosted_edit 两个字段都不返回 —— 托管改字会在客户端边界
直接 Zod 抛错（本地路径返回这两个字段，所以一直没暴露）
2. check-migrations 的列检查只扫 CREATE TABLE，凡 ALTER TABLE ADD COLUMN 追加的
@map 列一律误报 drift（此前唯一的 ALTER 列 brand_kits.profile 没 @map 才没现形）
3. ktv-poster-master.png 血统在合并两侧打架，git log --all 证明该文件自初始化提交后
从未重新生成，取诚实标注 prototype-demo-master
验收
- 新增 pnpm check:script → reports/script-acceptance.latest.json（双后端各 8 passed
+ 1 skipped-live）；own-tests floor 10→14，棘轮已收紧
- pnpm check / check:runtime 均 exit 0
- 浏览器实测：未确认角色 → 按钮 disabled 且提示缺哪个角色；绕过前端直打后端 → 422
ROLE_NOT_CONFIRMED；跨租户 404；无凭证生成 → UI 显示 503 且不产生占位脚本
诚实边界（已写入 CLAUDE.md）
- liveLlmAsserted=false：本机无 DASHSCOPE_API_KEY，真调 LLM 的 live 断言被 skip，
门禁成立 ≠ LLM 出脚本已验证
- check:inference 在本机为 failed（动手前即为 failed）：本工作副本的模型权重是
git-lfs 指针存根，非本轮改动导致；基线表该行已从 GREEN 改为 OPEN
- ui-acceptance 报告早于本屏，未覆盖 script 屏，已标 STALE
- 新开缺口 G16（LLM 只做结构校验、无事实性校验）、G17（同步 HTTP 挂分钟级推理 /
render_jobs 索引非 CONCURRENTLY / 本地多图 I2I 未在本机验证）
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
<!--
PR 治理模板。提交前请逐项确认，确保符合 docs/standards 下的工程规范。
CI 会执行：pnpm check（命名 + 单源漂移 + 治理棘轮 + lint + typecheck）；
有测试 DB 的流水线另执行 DATABASE_URL=... pnpm check:runtime。
-->
## 变更内容
<!-- 简述这次改了什么、为什么改（聚焦 why） -->
-
## 涉及业务概念
<!-- 列出涉及的业务词典英文名，例如 store / order / verification。参见 docs/domain-glossary.md -->
-
## 检查清单
### 命名一致性
- [ ] 业务概念使用了词典中的标准英文名（未出现 shop/branch/seller/voucher/writeOff 等禁用词）
- [ ] 数据库 snake_case + 复数表名；API/JSON 字段 camelCase；类型 PascalCase；常量 SCREAMING_SNAKE_CASE
- [ ] `pnpm check:naming` 通过
- [ ] `pnpm check:schema` 通过，未新增第二份状态/契约真源
### API / 契约
- [ ] 不涉及 API 变更
- [ ] 新增/修改了 API，路由符合 `/api/v1/{resources}` 规范
- [ ] 已更新 `packages/contracts` 中的 Zod schema / DTO / 类型（前后端共用同一份）
- [ ] 无破坏前端兼容的字段删除/重命名（如有，已在描述中说明迁移方案）
### 数据库
- [ ] 不涉及数据库变更
- [ ] 新增/修改了表或字段，已通过 migration review（表名复数、字段 snake_case、外键 xxx_id、时间 _at、状态 status）
- [ ] 高增长表已考虑分区；涉及多租户的表带 tenant_id
- [ ] 写链显式带 tenant_id；跨租户读写按 404/隔离口径处理
### 数据库迁移（迁移即代码：版本/顺序/内容/环境/发布/回滚一致）
- [ ] 改 schema.prisma 的同时**已生成并提交 migration**（`pnpm db:migrate:dev --name <change>`），未只改 schema 不落迁移
- [ ] **未修改已发布过的历史 migration 文件**（内容一致：历史不可变，新变更走新迁移）
- [ ] `pnpm check:migrations` 通过（迁移历史在位 / 无未豁免高危 DDL / schema 表、enum、`@map` 列均已落迁移）
- [ ] 破坏性变更（删表/删列/改名/改类型/加 NOT NULL/加唯一约束）走 **expand→migrate→contract** 三阶段，不一次切
- [ ] 大表加索引用 `CREATE INDEX CONCURRENTLY`；大批量回填走 BullMQ 分批任务，不塞进 migration
- [ ] 高危但确需的 DDL 已加 `-- migration-allow:<原因>` 留痕，并在下方回滚方案说明
- [ ] 非开发环境只用 `migrate deploy`（禁止 `db push` / 线上手动 ALTER）；发布前 `pnpm db:migrate:status` 无 drift
### 实时 / 队列
- [ ] 不涉及
- [ ] 关键业务事件进入 BullMQ 或持久化事件表（未仅依赖 Redis Pub/Sub）
- [ ] 写库事件与真实写操作在同一 tx 写入 outbox，未在 commit 后旁路 publish
- [ ] 实时通道选型符合规范（订单/看板/通知用 SSE；设备在线/包间控制/IM 用 WebSocket）
### 质量与发布
- [ ] 通过 `pnpm lint` 与 `pnpm typecheck`
- [ ] 通过 `pnpm check:governance`，`reports/*.latest.json` 已刷新且无棘轮回退
- [ ] 涉及写链 / DB / 租户 / 状态机时，通过 `DATABASE_URL=... pnpm check:runtime`，`reports/runtime-acceptance.latest.json` 已刷新
- [ ] 已补充/更新必要的测试
- [ ] 不需要回滚方案
- [ ] 需要回滚方案，已在下方说明
## 回滚方案 / 其他说明
-
...
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1787029791
|
1787032807
|
1787032807
|
0
|
0
|
0
|
Edit
Delete
|
|
720
|
67
|
1
|
5
|
|
0
|
治理: 关闭对抗性验收发现的假绿装置、导出层静默数据损坏与文档幽灵资产
|
<!--
PR 治理模板。提交前请逐项确认，确保符合 docs/standards 下的 <!--
PR 治理模板。提交前请逐项确认，确保符合 docs/standards 下的工程规范。
CI 会执行：pnpm check（命名 + 单源漂移 + 治理棘轮 + lint + typecheck）；
有测试 DB 的流水线另执行 DATABASE_URL=... pnpm check:runtime。
-->
## 变更内容
<!-- 简述这次改了什么、为什么改（聚焦 why） -->
-
## 涉及业务概念
<!-- 列出涉及的业务词典英文名，例如 store / order / verification。参见 docs/domain-glossary.md -->
-
## 检查清单
### 命名一致性
- [ ] 业务概念使用了词典中的标准英文名（未出现 shop/branch/seller/voucher/writeOff 等禁用词）
- [ ] 数据库 snake_case + 复数表名；API/JSON 字段 camelCase；类型 PascalCase；常量 SCREAMING_SNAKE_CASE
- [ ] `pnpm check:naming` 通过
- [ ] `pnpm check:schema` 通过，未新增第二份状态/契约真源
### API / 契约
- [ ] 不涉及 API 变更
- [ ] 新增/修改了 API，路由符合 `/api/v1/{resources}` 规范
- [ ] 已更新 `packages/contracts` 中的 Zod schema / DTO / 类型（前后端共用同一份）
- [ ] 无破坏前端兼容的字段删除/重命名（如有，已在描述中说明迁移方案）
### 数据库
- [ ] 不涉及数据库变更
- [ ] 新增/修改了表或字段，已通过 migration review（表名复数、字段 snake_case、外键 xxx_id、时间 _at、状态 status）
- [ ] 高增长表已考虑分区；涉及多租户的表带 tenant_id
- [ ] 写链显式带 tenant_id；跨租户读写按 404/隔离口径处理
### 数据库迁移（迁移即代码：版本/顺序/内容/环境/发布/回滚一致）
- [ ] 改 schema.prisma 的同时**已生成并提交 migration**（`pnpm db:migrate:dev --name <change>`），未只改 schema 不落迁移
- [ ] **未修改已发布过的历史 migration 文件**（内容一致：历史不可变，新变更走新迁移）
- [ ] `pnpm check:migrations` 通过（迁移历史在位 / 无未豁免高危 DDL / schema 表、enum、`@map` 列均已落迁移）
- [ ] 破坏性变更（删表/删列/改名/改类型/加 NOT NULL/加唯一约束）走 **expand→migrate→contract** 三阶段，不一次切
- [ ] 大表加索引用 `CREATE INDEX CONCURRENTLY`；大批量回填走 BullMQ 分批任务，不塞进 migration
- [ ] 高危但确需的 DDL 已加 `-- migration-allow:<原因>` 留痕，并在下方回滚方案说明
- [ ] 非开发环境只用 `migrate deploy`（禁止 `db push` / 线上手动 ALTER）；发布前 `pnpm db:migrate:status` 无 drift
### 实时 / 队列
- [ ] 不涉及
- [ ] 关键业务事件进入 BullMQ 或持久化事件表（未仅依赖 Redis Pub/Sub）
- [ ] 写库事件与真实写操作在同一 tx 写入 outbox，未在 commit 后旁路 publish
- [ ] 实时通道选型符合规范（订单/看板/通知用 SSE；设备在线/包间控制/IM 用 WebSocket）
### 质量与发布
- [ ] 通过 `pnpm lint` 与 `pnpm typecheck`
- [ ] 通过 `pnpm check:governance`，`reports/*.latest.json` 已刷新且无棘轮回退
- [ ] 涉及写链 / DB / 租户 / 状态机时，通过 `DATABASE_URL=... pnpm check:runtime`，`reports/runtime-acceptance.latest.json` 已刷新
- [ ] 已补充/更新必要的测试
- [ ] 不需要回滚方案
- [ ] 需要回滚方案，已在下方说明
## 回滚方案 / 其他说明
-
...
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1785285580
|
1785285593
|
1785285593
|
0
|
0
|
0
|
Edit
Delete
|
|
756
|
85
|
1
|
4
|
|
0
|
[Intent] 按省市统计设备月度新增上线数量报表
|
Related to #8
## 需求摘要
在「数据报表 > 设备分析」下新增报表，按月筛 Related to #8
## 需求摘要
在「数据报表 > 设备分析」下新增报表，按月筛选展示各省份新激活上线设备数量柱状图排行，支持下钻到城市维度。
## 核心决策
- 统计口径：当月**新激活**上线设备（首次上线，取 ahead_authenticate_log 表的 create_time 字段）
- 地区归属：取设备绑定**门店地址**的省/市字段
- 交互方式：点击省份**下钻**到城市排行（非 Tab 切换）
- 权限：跟随现有 agent_id 角色体系，超管看全国，运营商看自己区域
## 不在范围内
- 不做 Excel 导出
- 不做地图热力图
- 不做区/县级别
- 不做跨月趋势
## 产物文件
[intent/device-online-stats-by-region.md](https://gitea.g-hi.com/laiqiaojie/jh-project/src/branch/intent/device-online-stats-by-region/intent/device-online-stats-by-region.md)
## PM 审核清单（参考 REVIEW.md）
- [ ] 需求背景和问题描述是否准确反映了原始诉求？
- [ ] 期望结果是否可验证？
- [ ] 不在范围内的排除项是否合理？
- [ ] 受影响系统判断是否正确（admin / ahead_authenticate_log）？
- [ ] 本次是否接受排期，进入 Design 阶段？...
|
1
|
0
|
1
|
1
|
2
|
|
0
|
1787817232
|
1789379898
|
1787823622
|
0
|
5
|
0
|
Edit
Delete
|
|
757
|
85
|
2
|
4
|
|
0
|
[Design] 按省市统计设备月度新增上线数量报表
|
## 关联 Intent
[PR #1 — 按省市统计设备月度新增上线数量报表](https:// ## 关联 Intent
[PR #1 — 按省市统计设备月度新增上线数量报表](https://gitea.g-hi.com/laiqiaojie/jh-project/pulls/1)
---
## 审核顺序：PM 先确认原型，再由 Tech Lead Approve
---
## 第一步：PM 确认原型
**原型文件：**
（从仓库拉取后浏览器直接双击打开，可点击交互）
页面状态：
- 全国省份视图 — 月份筛选器 + 当月总数卡片 + 各省份横向柱状图
- 城市下钻视图 — 点击省份柱子进入，面包屑「全国 › 广东省」+ 城市排行
交互流程：点击省份柱子进入城市视图，点击面包屑「全国」或「返回全国」按钮返回。
**PM 审核 checklist：**
- [ ] 页面布局和组件符合预期？
- [ ] 交互路径（下钻、返回）正确？
- [ ] 数据定义（新增上线 = 首次激活，归属 = 门店地址）理解一致？
- [ ] 权限范围（超管看全国，运营商看自己区域）正确？
**PM 确认方式：在本 PR 评论「原型确认 ✅」即可，无需 Approve**
---
## 第二步：Tech Lead 审核（PM 确认后进行）
**数据链路：**
> 待确认：ahead_family_servers._shop_id 是否关联 ahead_yc_shop._id，Build 阶段查库验证。
**新增接口（新建控制器 DeviceOnlineReport.php）：**
- POST /DeviceOnlineReport/getStats — 省份排行 + 当月总数
- POST /DeviceOnlineReport/getCityStats — 城市下钻
**权限：** agent_id 从 session 取，= 0 为超管不过滤
**安全：** month 正则校验、province_id intval()、agent_id 不信任前端
**Tech Lead 审核 checklist：**
- [ ] 数据链路正确？表关联关系有无误判？
- [ ] 接口设计合理？参数和响应格式符合规范？
- [ ] 权限处理方式正确？
- [ ] 安全检查要点覆盖？
- [ ] 前端方案可行（ECharts 按需引入）？
**Tech Lead Approve → Merge → 评审会议（里程碑内所有需求一起）→ Plan 阶段**...
|
1
|
0
|
1
|
1
|
0
|
|
0
|
1787824027
|
1789379887
|
1787829412
|
0
|
3
|
0
|
Edit
Delete
|
|
758
|
85
|
3
|
4
|
|
0
|
[Design] 按省市统计设备月度新增上线数量报表
|
Related to #8
## 关联 Intent
[PR #1 — 按省市统计设备月度新增上 Related to #8
## 关联 Intent
[PR #1 — 按省市统计设备月度新增上线数量报表](https://gitea.g-hi.com/laiqiaojie/jh-project/pulls/1)
---
## PM 确认原型
**需求说明文档：**
[design/device-online-stats-by-region.md](https://gitea.g-hi.com/laiqiaojie/jh-project/src/branch/design/device-online-stats-by-region/design/device-online-stats-by-region.md)
**在线原型（点击直接打开，可交互，无需登录）：**
https://claude.ai/code/artifact/b50eaa98-689b-4742-8024-cdf74f95d5c8
**页面状态：**
- 全国省份视图 — 月份筛选器 + 当月总数卡片 + 各省份横向柱状图
- 城市下钻视图 — 点击省份柱子进入，面包屑「全国 › 广东省」+ 城市排行
**交互流程：** 点击省份柱子进入城市视图，点击面包屑「全国」或「返回全国」按钮返回。
**审核 checklist：**
- [ ] 页面布局和组件符合预期？
- [ ] 交互路径（下钻、返回）正确？
- [ ] 数据定义（新增上线 = 首次上线，归属 = 门店注册地址）理解一致？
- [ ] 权限范围（超管看全国，运营商看自己区域）正确？
**确认方式：在本 PR 评论「原型确认 ✅」，然后 Approve + Merge**...
|
1
|
0
|
1
|
1
|
0
|
|
0
|
1787829439
|
1789379899
|
1787908921
|
0
|
7
|
0
|
Edit
Delete
|
|
759
|
85
|
4
|
4
|
|
0
|
[后台] 按省市统计设备月度新增上线数量报表
|
> 子任务，属于主 Issue #8「按省市统计设备月度新增上线数量报表」
## 关联 De > 子任务，属于主 Issue #8「按省市统计设备月度新增上线数量报表」
## 关联 Design PR
[PR #3 — Design: 按省市统计设备月度新增上线数量报表](https://gitea.g-hi.com/laiqiaojie/jh-project/pulls/3)
## 工作范围
负责后台接口实现：
- 新增查询接口，按月份统计各省份新增上线设备数量
- 支持下钻查询：指定省份，返回城市级别数据
- 按权限过滤：超管返回全国数据，运营商返回自己区域
## 产物
- （实现前提交，Tech Lead 审核后开始 Build）
## 参考
- 需求说明：[design/device-online-stats-by-region.md](https://gitea.g-hi.com/laiqiaojie/jh-project/src/branch/design/device-online-stats-by-region/design/device-online-stats-by-region.md)
- 在线原型：https://claude.ai/code/artifact/b50eaa98-689b-4742-8024-cdf74f95d5c8...
|
1
|
0
|
1
|
0
|
2
|
|
0
|
1787909526
|
1789380193
|
1789380193
|
0
|
1
|
0
|
Edit
Delete
|
|
760
|
85
|
5
|
4
|
|
0
|
[Web] 按省市统计设备月度新增上线数量报表
|
> 子任务，属于主 Issue #8「按省市统计设备月度新增上线数量报表」
## 关联 De > 子任务，属于主 Issue #8「按省市统计设备月度新增上线数量报表」
## 关联 Design PR
[PR #3 — Design: 按省市统计设备月度新增上线数量报表](https://gitea.g-hi.com/laiqiaojie/jh-project/pulls/3)
## 工作范围
负责 Web 前端页面实现：
- 数据报表 → 设备上线分布 页面
- 月份筛选器 + 当月总数卡片 + 省份横向柱状图
- 点击省份下钻到城市视图，支持面包屑返回
## 产物
- plan/device-online-stats-by-region-web.md（实现前提交，Tech Lead 审核后开始 Build）
## 参考
- 需求说明：[design/device-online-stats-by-region.md](https://gitea.g-hi.com/laiqiaojie/jh-project/src/branch/design/device-online-stats-by-region/design/device-online-stats-by-region.md)
- 在线原型：https://claude.ai/code/artifact/b50eaa98-689b-4742-8024-cdf74f95d5c8...
|
1
|
0
|
1
|
0
|
3
|
|
0
|
1787909556
|
1789380193
|
1789380193
|
0
|
1
|
0
|
Edit
Delete
|
|
768
|
85
|
6
|
4
|
|
0
|
[Plan] 按省市统计设备月度新增上线数量报表 (后台管理)
|
Related to #8
## 关联 Issue
[#4 — [后台] 按省市统计设备月度新增 Related to #8
## 关联 Issue
[#4 — [后台] 按省市统计设备月度新增上线数量报表](https://gitea.g-hi.com/laiqiaojie/jh-project/issues/4)
## 说明
补交 Plan 阶段产物（此前误提交到已合并关闭的 design 分支，未能进入 main，见此 PR 重新提交）。
代码已实现并提交：[laiqiaojie/admin#1](https://gitea.g-hi.com/laiqiaojie/admin/pulls/1)
按 REVIEW.md「跳过评审的路径」，`plan/` 产物文件不需要 Tech Lead 单独审核，随此 PR 直接入库。...
|
0
|
0
|
1
|
1
|
1
|
|
0
|
1788245555
|
1789379899
|
1788245966
|
0
|
1
|
0
|
Edit
Delete
|
|
770
|
85
|
7
|
4
|
|
0
|
[Skill] build-complete 新增接口文档归档步骤
|
Related to #8
## 说明
在 `build-complete` skill 里新增 Related to #8
## 说明
在 `build-complete` skill 里新增一步：Plan 阶段确定接口设计后、代码开发完成时，如涉及新增/修改接口，需要生成并归档接口文档：
- Apifox（规范化 OpenAPI 文档，Claude 通过 API 增量导入）
- `docs/frontend-specs/<功能名>.md`（面向其他端的对接说明文档，固定五章结构）
背景：issue #4 实现完成后发现接口文档一直没有归档，靠事后补做；这次把它固化成流程里的正式一步，插在"提交 plan.md"和"开代码 PR"之间。
同时补充了代码仓库与 jh-project 分离时的注意事项（milestone/label 可能不存在、Close #N 跨仓库不生效）。...
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1788247386
|
1789379900
|
1788247940
|
0
|
1
|
0
|
Edit
Delete
|
|
773
|
85
|
8
|
4
|
|
0
|
按省市统计设备月度新增上线数量报表
|
## 功能概述
在 PC 管理后台「数据报表」模块，按省市统计各 KTV 设备每月新增上线数量，支 ## 功能概述
在 PC 管理后台「数据报表」模块，按省市统计各 KTV 设备每月新增上线数量，支持全国省份分布视图 + 城市下钻。
## 完整产物链路
| 阶段 | 产物 | 链接 | 状态 |
|------|------|------|------|
| 需求意图 | Intent 文档 | PR #1 | ✅ 已合并 |
| 设计原型 | Design 文档 | PR #3 | ✅ 已合并 |
| 技术方案（后台） | Plan 文档 | PR #6 | ✅ 已合并 |
| 开发实现（后台） | admin 仓库代码 | admin PR #1 | ✅ 已合并 |
| 开发实现（Web前端） | admin 仓库代码 | admin PR #2 | ✅ 已合并 |
| 测试验收 | — | 本 Issue | 🧪 待测试 |
## 验收标准
- 后台 API 返回省份/城市维度的月度新增上线设备数，分页正确
- PC 管理后台菜单「数据报表 > 设备上线分布」可正常点击进入
- 省份视图正常渲染（横向柱状图），点击下钻到城市视图
- 城市视图面包屑可返回全国
- 月份切换后数据刷新正确
- 无数据月份显示空状态，不报错...
|
0
|
0
|
0
|
0
|
0
|
|
0
|
1789379887
|
1789380277
|
0
|
0
|
2
|
0
|
Edit
Delete
|
|
790
|
116
|
1
|
5
|
|
0
|
fix(contracts): 注册中心规则补失败关闭与摘要规范化——三个入口此前抛 TypeErr fix(contracts): 注册中心规则补失败关闭与摘要规范化——三个入口此前抛 TypeError，同一摘要的两种写法此前分叉成两个复核键...
|
蓝图 docs/domain/registry-snapshot-blueprint.md 从迁入起 蓝图 docs/domain/registry-snapshot-blueprint.md 从迁入起就写着「失败关闭」与
「review key 仅用于人工复核幂等」两条不变量，实测三处不成立。本次按蓝图自己的口径补齐，
改动只在 contracts/src/domain/application-contract-registry/：不新增写入点、不新增宿主、
不动 Catalog 与 Schema，每条输出仍固定 activationAllowed=false / registryWriteAllowed=false /
humanApprovalRequired=true。
1. 失败关闭：assessRegistrySnapshot / assessRegistryTransition /
reviewCandidateSnapshotUpgrade 对畸形输入抛 TypeError（快照缺字段、now 不是 Date、
decisions 整个缺失都会抛），四个入口里只有 LocalManifestAdmissionPlanner.plan 是
失败关闭的。现四个入口一致返回 REJECT + 原因码。这不是洁癖：check-fixtures 把抛出当
配置错误处理，实测一次 TypeError 会让整套 15 例逐例判定塌成一条 configuration 失败。
2. 十六进制引用规范化：digest / commit 的正则带 /i 收大小写两种写法，比较与入键却
大小写敏感——同一摘要写成大写会得到另一个 reviewIdempotencyKey，同版本大小写翻转被判成
SAME_VERSION_DIGEST_CHANGED，大写回滚 pin 被判成 ROLLBACK_PIN_MUST_MATCH_CURRENT。
现一律规范化为小写后再比较、再入键，ACCEPT 回吐规范化后的值。
3. 版本文法收敛：一个模块三套（快照流与清单准入用 \d+\.\d+\.\d+，升级复核用严格 SemVer），
新增 registry-primitives.ts 作单一来源，含预发布序；DEC-009—012 此前在两份文件各写一份，
一并收敛。snapshot-upgrade-review.ts 因此净减约 60 行重复实现。
两处语义变化（蓝图新增一节已如实登记）：
- 收紧：1.02.0 这类前导零版本此前被放行，现在拒；assessRegistrySnapshot 另开始拒 latest
这类可变标签——此前它能过体检却必然过不了迁移规则。
- 放宽：1.0.0-rc.1 这类预发布版本此前被快照流整条挡在外面，现在按 SemVer 序参与迁移。
平台自己发的就是 1.0.0-rc.N，升级复核那一侧本来就这么判。风险面有限：本模块所有出口
都不激活、不写 Registry，多进人工复核队列不等于多放行制品。
证据（本分支隔离工作树，clean）：注册中心单测 44/44（原 34 + 加固 10）；
contracts check:local 302/302；check:fixtures 九个契约域套件 100 例 0 失败，
其中本套件 15 例（正 4 / 反 11，原 8 例）。篡改必红实测两次：sameHexRef 退回大小写敏感
→ 单测 1 红 + 夹具 P03 红；去掉快照入口守卫 → 整套塌成 0 例 1 配置失败。
仍为仓内候选 sdk_e2，不代表正式 Registry、Snapshot 发布或跨仓 Required Check 已上线。
清单登记的 C01.04 / C01.06 是「接线」型缺口且前置 Q01 运行宿主未裁，本次未动。
reports/fixtures.latest.json 未回绑：它是 17 套件的聚合报告，只跑 9 个套件去覆盖会缩小结论面，
应在整批（含并行会话的 public-file / IM / 跨域流程改动）落定后统一重跑回绑。
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>...
|
0
|
0
|
1
|
1
|
0
|
|
0
|
1789742918
|
1789744064
|
1789742925
|
0
|
0
|
0
|
Edit
Delete
|