refactor(stage7): 后端目录分层、架构守护测试与文档

后端目录
- db/：mysql / hydrogen / heatmap 连接与氢能只读 SQL 守卫收拢到一处。
- middleware/：auth（JWT → 注入 user）与 read-only 归位。
- 相关测试随文件移动（middleware/read-only.test.ts、db/hydrogen-read-only.test.ts）。
  import 改写由一次性 codemod 完成，未改变任何逻辑。

架构守护
- 新增 src/architecture.test.ts，断言 6 条分层铁律：
  server 不依赖 modules、前端不依赖 server、shared 为叶子层、
  无 vendor 引用、model.ts 不依赖 react、@ts-nocheck 仅限已登记的原型快照。
  豁免清单只减不增。

测试基建
- npm test 的 glob 同时匹配 .test.ts 与 .test.tsx（此前 .tsx 测试会被静默漏掉）。

文档
- 新增根 README.md：入口、快速开始、命令、目录、部署注意事项
  （JWT_SECRET 必须注入且 >=32 字符，否则拒绝启动）。
- 新增 docs/ARCHITECTURE.md：依赖方向、6 条硬规则、业务域形状、
  中间件顺序、新增模块步骤，以及"已知未尽事项"的诚实清单。

lint / test(134) / build 全绿。

README.md

@@ -0,0 +1,87 @@
+# 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。
+
+```bash
+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 代理）：
+
+```bash
+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）
+└── server/
+    ├── config.ts  环境变量集中读取 + 启动期校验
+    ├── app.ts     应用装配（无副作用，便于测试）
+    ├── index.ts   进程启动
+    ├── local.ts   只读预览启动
+    ├── db/        MySQL / PostgreSQL 连接
+    ├── middleware/认证、只读
+    ├── auth/      登录（SSO 换票 / 固定密码）、权限
+    └── routes/    按业务域的 HTTP 路由
+```
+
+## 架构约定
+
+分层规则、依赖方向与「新增一个模块该放哪」见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。
+其中 6 条硬规则由 `src/architecture.test.ts` 断言，违反即测试失败。
+
+## 部署注意事项
+
+- `JWT_SECRET` **必须**在运行环境注入且不少于 32 字符；SSO 模式下缺失时服务会拒绝启动。
+  镜像内不再内置默认密钥（历史默认值等同于公开密钥，可被离线伪造令牌）。
+- 数据库口令、Harbor 凭据、OSS / OneOS / 高德密钥一律通过环境变量或 CI Secret 注入，
+  仓库内不保留真实值。历史提交中出现过的凭据都需要轮换。
+- 生产环境请显式设置 `NODE_ENV=production` 与 `DEV_BYPASS_AUTH=0`；后者会绕过全部认证。