dashboard-nanobot/design/code-structure-standards.md

# Dashboard Nanobot 代码结构规范（强制执行）

本文档定义后续前端、后端、`dashboard-edge` 的结构边界与拆分规则。

目标不是“尽可能多拆文件”，而是：

- 保持装配层足够薄
- 保持业务边界清晰
- 避免再次出现单文件多职责膨胀
- 让后续迭代继续走低风险、小步验证路线

本文档自落地起作为**后续开发强制规范**执行。

---

## 1. 总原则

### 1.1 先分层，再分文件

- 优先先把“页面装配 / 业务编排 / 基础设施 / 纯视图”分开，再决定是否继续拆文件。
- 不允许为了“看起来模块化”而把强耦合逻辑拆成大量碎文件。
- 允许保留中等体量的“单主题控制器”文件，但不允许继续把多个主题堆进一个文件。

### 1.2 低风险重构优先

- 结构重构优先做“搬运与收口”，不顺手修改业务行为。
- 同一轮改动里，默认**不要**同时做：
  - 大规模结构调整
  - 新功能
  - 行为修复
- 如果确实需要行为修复，只允许修复拆分直接引入的问题。

### 1.3 装配层必须薄

- 页面层、路由层、应用启动层都只负责装配。
- 装配层可以做依赖注入、状态接线、事件转发。
- 装配层不允许承载复杂业务判断、持久化细节、长流程编排。

### 1.4 新文件必须按主题命名

- 文件名必须直接表达职责。
- 禁止模糊命名，例如：
  - `helpers2.py`
  - `misc.ts`
  - `commonPage.tsx`
  - `temp_service.py`

---

## 2. 前端结构规范

### 2.1 目录分层

前端统一按以下层次组织：

- `frontend/src/app`
  - 应用壳、全局路由视图、全局初始化
- `frontend/src/modules/<domain>`
  - 领域模块入口
- `frontend/src/modules/<domain>/components`
  - 纯视图组件、弹层、区块组件
- `frontend/src/modules/<domain>/hooks`
  - 领域内控制器 hook、状态编排 hook
- `frontend/src/modules/<domain>/api`
  - 仅该领域使用的 API 请求封装
- `frontend/src/modules/<domain>/shared`
  - 领域内共享的纯函数、常量、类型桥接
- `frontend/src/components`
  - 跨模块通用 UI 组件
- `frontend/src/utils`
  - 真正跨领域的通用工具

### 2.2 页面文件职责

页面文件如：

- `frontend/src/modules/platform/PlatformDashboardPage.tsx`
- `frontend/src/modules/platform/NodeWorkspacePage.tsx`
- `frontend/src/modules/platform/NodeHomePage.tsx`

必须遵守：

- 只做页面装配
- 只组织已有区块、弹层、控制器 hook
- 不直接承载长段 API 请求、副作用、数据清洗逻辑

页面文件目标体量：

- 目标：`< 250` 行
- 可接受上限：`350` 行
- 超过 `350` 行必须优先拆出页面控制器 hook 或区块装配组件

### 2.3 控制器 hook 规范

控制器 hook 用于承载：

- 页面状态
- 副作用
- API 调用编排
- 事件处理
- 派生数据

典型命名：

- `useNodeHomePage`
- `useNodeWorkspacePage`
- `usePlatformDashboardPage`

规则：

- 一个 hook 只服务一个明确页面或一个明确子流程
- hook 不直接产出大量 JSX
- hook 内部允许组合更小的子 hook，但不要为了拆分而拆分

控制器 hook 目标体量：

- 目标：`< 350` 行
- 可接受上限：`500` 行
- 超过 `500` 行时，必须再按主题拆成子 hook 或把重复逻辑提到 `shared`/`api`

### 2.4 视图组件规范

组件分为两类：

- 区块组件：例如列表区、详情区、摘要卡片区
- 弹层组件：例如 Drawer、Modal、Sheet

规则：

- 视图组件默认不直接请求接口
- 视图组件只接收已经整理好的 props
- 纯视图组件内部不保留与页面强耦合的业务缓存

### 2.5 前端复用原则

- 优先提炼“稳定复用的模式”，不要提炼“碰巧重复一次的代码”
- 三处以上重复，优先考虑抽取
- 同域复用优先放 `modules/<domain>/shared`
- 跨域复用优先放 `src/components` 或 `src/utils`

### 2.6 前端禁止事项

- 禁止再次把页面做成“一个文件管状态、接口、弹层、列表、详情、搜索、分页”
- 禁止把样式、业务逻辑、视图结构三者重新耦合回单文件
- 禁止创建无明确职责的超通用组件
- 禁止为减少行数而做不可读的过度抽象

---

## 3. 后端结构规范

### 3.1 目录分层

后端统一按以下边界组织：

- `backend/main.py`
  - 仅启动入口
- `backend/app_factory.py`
  - 应用实例创建
- `backend/bootstrap`
  - 依赖装配、应用初始化、生命周期拼装
- `backend/api`
  - FastAPI 路由层
- `backend/services`
  - 业务用例与领域服务
- `backend/core`
  - 数据库、缓存、配置、基础设施适配
- `backend/models`
  - ORM 模型
- `backend/schemas`
  - 请求/响应 DTO
- `backend/providers`
  - runtime/workspace/provision 适配层

### 3.2 启动与装配层规范

以下文件必须保持装配层属性：

- `backend/main.py`
- `backend/app_factory.py`
- `backend/bootstrap/app_runtime.py`

规则：

- 只做依赖创建、注入、路由注册、生命周期绑定
- 不写业务 SQL
- 不写领域规则判断
- 不写长流程编排

### 3.3 Router 规范

`backend/api/*.py` 只允许承担：

- HTTP 参数接收
- schema 校验
- 调用 service
- 把领域异常转换成 HTTP 异常

Router 不允许承担：

- 多步业务编排
- 大量数据聚合
- 数据库表间拼装
- 本地文件系统读写细节

Router 文件体量规则：

- 目标：`< 300` 行
- 可接受上限：`400` 行
- 超过 `400` 行必须拆成子 router，并由装配层统一 `include_router`

### 3.4 Service 规范

Service 必须按业务主题拆分。

允许的 service 类型：

- `*_settings_service.py`
- `*_usage_service.py`
- `*_activity_service.py`
- `*_analytics_service.py`
- `*_overview_service.py`
- `*_query_service.py`
- `*_command_service.py`
- `*_lifecycle_service.py`

Service 文件规则：

- 一个文件只负责一个主题
- 同一文件内允许有私有 helper，但 helper 只能服务当前主题
- 如果一个主题明显包含“读模型 + 写模型 + 统计 + 配置”，应继续拆为多个 service

Service 体量规则：

- 目标：`< 350` 行
- 可接受上限：`500` 行
- 超过 `500` 行必须继续拆

### 3.5 当前 platform 域的标准拆法

`platform` 域后续固定按如下职责组织：

- `backend/api/platform_router.py`
  - 仅负责平台路由总装配
- `backend/api/platform_admin_router.py`
  - 仅负责平台后台管理路由装配
- `backend/api/platform_overview_router.py`
  - 平台概览、统计、事件、usage、缓存刷新
- `backend/api/platform_settings_router.py`
  - 平台设置、system settings
- `backend/api/platform_nodes_router.py`
  - 节点相关路由总装配
- `backend/api/platform_node_catalog_router.py`
  - 节点列表、增删改、连通性测试
- `backend/api/platform_node_probe_router.py`
  - 节点探测、心跳、自检类接口
- `backend/api/platform_node_resource_router.py`
  - 节点资源、工作区、运行态资源接口
- `backend/services/platform_settings_service.py`
  - 平台设置与系统设置
- `backend/services/platform_usage_service.py`
  - request usage 记账与查询
- `backend/services/platform_activity_service.py`
  - activity event 记录与清理
- `backend/services/platform_analytics_service.py`
  - dashboard analytics 聚合
- `backend/services/platform_overview_service.py`
  - platform / node overview 聚合
- `backend/services/platform_common.py`
  - 仅放当前 platform 域内部共享的纯工具

`backend/services/platform_service.py` 只允许保留为**薄兼容导出层**，不得再新增业务逻辑。

`backend/api/platform_admin_router.py` 与 `backend/api/platform_nodes_router.py` 只允许继续承担子路由装配职责，不得重新回填具体业务接口实现。

### 3.6 Schema 规范

- `schemas` 只定义 DTO
- 不允许在 schema 中直接读数据库、读文件、发网络请求
- schema 字段演进必须保持前后端契约可追踪

### 3.7 Core 规范

`core` 只允许放：

- 数据库与 Session 管理
- 缓存
- 配置
- 基础设施适配器

不允许把领域业务塞回 `core` 来“躲避 service 变大”。

### 3.8 Provider 规范

`providers` 只处理运行时/工作区/部署目标差异。

不允许把平台业务逻辑塞进 provider。

### 3.9 dashboard-edge 规范

`dashboard-edge` 按与主后端相同的规则执行：

- `app/main.py` 仅启动
- `app/api/router.py` 仅路由
- `app/services` 仅业务编排
- `app/runtime` 仅 runtime 适配

`dashboard-edge/app/runtime/docker_manager.py` 与 `dashboard-edge/app/runtime/native_manager.py`
后续必须按以下方向拆分：

- 生命周期控制
- 资源采样
- preflight / 诊断
- workspace / 文件交互

---

## 4. 本项目后续开发的执行规则

### 4.1 每轮改动的默认顺序

1. 先审计职责边界
2. 先做装配层变薄
3. 再提炼稳定复用块
4. 最后再考虑继续细拆

### 4.2 校验规则

- 前端结构改动后，默认执行 `frontend` 构建校验
- 后端结构改动后，默认至少执行 `python3 -m py_compile`
- 如果改动触达运行时或边界协议，再考虑追加更高层验证

### 4.3 文档同步规则

以下情况必须同步设计文档：

- 新增一层目录边界
- 新增一个领域的标准拆法
- 改变页面/服务的职责划分
- 把兼容层正式降级为装配/导出层

### 4.4 禁止事项

- 禁止回到“大文件集中堆功能”的开发方式
- 禁止为了图省事把新逻辑加回兼容层
- 禁止在没有明确复用收益时过度抽象
- 禁止在一次改动里同时重写 UI、重写数据流、重写接口协议

---

## 5. 当前执行基线（2026-03）

当前结构治理目标分两层：

- 第一层：主入口、页面入口、路由入口必须变薄
- 第二层：领域内部的 service / hook / overlays / sections 必须按主题稳定收口

后续所有新增功能与重构，均以本文档为准执行。