dsh-agent
523f7b312d
vehicle-heatmap
- 拆为 routes.ts / repository.ts（model.ts 原已存在），改为 registerVehicleHeatmapRoutes(app, deps)。
- 该域同时访问两个库，因此依赖分成 MysqlDatabase（execute，考核批次→车牌）与
PgDatabase（query 返回 { rows }，定位点），两者返回形状不同，不做统一抽象。
- 保留 $4 的原语义：是否"选择了考核批次"（而非"车牌集合是否为空"）；
批次无车牌时由调用方提前返回，与原实现一致。
- 保留 loadBatchModelPlates 的降级行为（查询失败→空映射）与"命中缓存不查主库"。
hydrogen-heatmap
- 拆为 routes.ts / repository.ts，改为 registerHydrogenHeatmapRoutes(app, deps)。
- VALID_COORDINATE（含西藏排除）与 buildWhere 移入 repository 并导出：
它被 meta 的统计口径复用，散落两处极易漂移。
- 5 条 SQL 由脚本从原文件按顺序抽取后原样落位，避免手工转写长 SQL 出错。
契约测试（新增 19 个用例）
- 逐条断言 SQL 文本（规范化空格）与参数顺序：分页/白名单/批次车牌数组/
WHERE 片段顺序/IN 占位符拼接/半径内无站点时不发第二条查询。
- buildWhere 直接单测片段与参数顺序。
- 架构守护的"已完整分层"清单扩到 5 个域。
等价性验证（关键）
- 把两个文件改造前的实现从 git 取出，与改造后跑同一批请求，对比落库 SQL、参数、
HTTP 状态与响应体：
vehicle-heatmap ：8 个场景完全一致（含批次路径、"未知批次"提前返回、错误分支）
hydrogen-heatmap ：8 个场景完全一致（含筛选组合、无权限 403、错误分支）
期间的修正：曾为 /meta 的空结果新增 503 分支，属于原实现没有的行为变更，已回退为原样。
lint / test(181) / build 全绿，可达性 0 未引用文件。
LN-BI
羚牛业务数据的统一 BI Web 应用。React 19 + Vite 前端，Hono 后端，单进程同时提供 API 与静态页面。
入口
| 入口 | 模块 | 路由 |
|---|---|---|
| 资产 BI | 资产管理、里程管理、车辆/加氢热力图、智能调度 | /asset |
| 能源 BI | 氢费 BI、电能、ETC | /energy |
| 隐藏页 | 充电记录导入（需能源角色） | /ele/import |
| 隐藏页 | 用户反馈管理 | /admin/feedback |
| 独立入口 | 氢能经营看板（与 /energy 内同一组件） |
/energy/hydrogen-board |
页面内部用 Hash 保存子页面状态，例如 /energy#hydrogen/overview。入口兼容逻辑见 src/app/routing.ts。
快速开始
需要 Node.js 22 与 npm。
npm ci
cp .env.local.example .env.local # 填入数据库等连接配置，切勿提交
npm run dev:local # 只读本地预览：前端 127.0.0.1:8115，API 127.0.0.1:3001
dev:local 会强制 DB_READ_ONLY=1、HYDROGEN_DB_READ_ONLY=1、MILEAGE_REPORT_AUTO_ARCHIVE=0、
DEV_BYPASS_AUTH=1，并且不启动建表与定时任务，适合看真实数据而不写库。不要把它暴露到公网。
常规开发（前端 3000，后端 3001，/api 由 Vite 代理）：
npm run dev
命令
| 命令 | 说明 |
|---|---|
npm run dev |
前后端开发模式 |
npm run dev:local |
只读本地预览（免登录，禁写库） |
npm run lint |
类型检查（tsc --noEmit） |
npm test |
Node 内置测试运行器 |
npm run build |
生成 dist |
npm start |
生产式启动（需先 build，且必须提供环境变量） |
发布门禁是 lint + test + build 三者同时通过（CI 见 woodpecker.yml）。
目录
src/
├── app/ 应用外壳：路由解析、导航注册
├── auth/ 前端认证状态与注入
├── components/ 跨模块 UI（Shell、反馈、通用控件）
├── modules/ 前端业务域（每个域自带 api / model / components / css）
│ ├── assets/ 资产管理
│ ├── mileage/ 里程（monitoring / statistics / daily-report）
│ ├── scheduling/智能调度
│ ├── energy/ 能源（hydrogen / electric / etc）
│ ├── ele/ 电能数据导入
│ ├── admin/ 反馈后台
│ └── *-heatmap/ 两类热力图
├── shared/ 前后端共享的叶子层（角色常量、跨端 DTO、日期区间、Excel、高德接入）
└── server/
├── config.ts 环境变量集中读取 + 启动期校验
├── app.ts 应用装配（无副作用，便于测试）
├── index.ts 进程启动
├── local.ts 只读预览启动
├── db/ MySQL / PostgreSQL 连接
├── middleware/认证、只读
├── auth/ 登录（SSO 换票 / 固定密码）、权限
└── routes/ 按业务域的 HTTP 路由
架构约定
分层规则、依赖方向与「新增一个模块该放哪」见 docs/ARCHITECTURE.md。
其中 6 条硬规则由 src/architecture.test.ts 断言，违反即测试失败。
部署注意事项
JWT_SECRET必须在运行环境注入且不少于 32 字符；SSO 模式下缺失时服务会拒绝启动。 镜像内不再内置默认密钥（历史默认值等同于公开密钥，可被离线伪造令牌）。- 数据库口令、Harbor 凭据、OSS / OneOS / 高德密钥一律通过环境变量或 CI Secret 注入， 仓库内不保留真实值。历史提交中出现过的凭据都需要轮换。
- 生产环境请显式设置
NODE_ENV=production与DEV_BYPASS_AUTH=0；后者会绕过全部认证。