refactor(web): 前端目录重构 — consoles/pages → layouts/features + shared

- consoles/admin/ → layouts/admin-layout/
- consoles/workbench/ → layouts/workbench-layout/ + features/chat/
- pages/ → features/ (dashboard, models, projects, not-found)
- components/ → shared/components/
- hooks/ → shared/hooks/
- utils/ → shared/utils/
- 更新所有 import 路径 (src/web/ + tests/web/)
- 更新开发文档 (README.md, frontend.md, architecture.md)

docs/development/README.md

@@ -37,20 +37,127 @@ AI 工具必须严格遵守以下全部约束。
 
 ### 目录边界
 
-| 目录                     | 约束                                         |
-| ------------------------ | -------------------------------------------- |
-| `src/server/`            | 后端，禁止 import src/web/                   |
-| `src/server/db/`         | 数据库层：schema、connection、migration、DAO |
-| `src/server/ai/`         | AI Provider Registry + Agent + 工具          |
-| `src/server/config/`     | 配置子系统：types、variables、issues、schema |
-| `src/server/helpers/`    | 跨路由工具：响应格式化、URL 拼接             |
-| `src/server/middleware/` | 参数校验 + 错误处理中间件                    |
-| `src/web/`               | 前端，禁止 import src/server/ 运行时实现     |
-| `src/web/consoles/`      | 控制台外壳（Admin / Workbench）              |
-| `src/shared/`            | 前后端共享类型（api.ts）和常量（app.ts）     |
-| `scripts/`               | 独立脚本，可 import 项目源码                 |
-| `drizzle/`               | SQL migration 文件（开发期产出）             |
-| `tests/`                 | 测试目录，镜像 src/ 结构                     |
+| 目录                     | 约束                                                |
+| ------------------------ | --------------------------------------------------- |
+| `src/server/`            | 后端，禁止 import src/web/                          |
+| `src/server/db/`         | 数据库层：schema、connection、migration、DAO        |
+| `src/server/ai/`         | AI Provider Registry + Agent + 工具                 |
+| `src/server/config/`     | 配置子系统：types、variables、issues、schema        |
+| `src/server/helpers/`    | 跨路由工具：响应格式化、URL 拼接                    |
+| `src/server/middleware/` | 参数校验 + 错误处理中间件                           |
+| `src/web/`               | 前端，禁止 import src/server/ 运行时实现            |
+| `src/web/layouts/`       | 布局组件（AdminLayout / WorkbenchLayout）           |
+| `src/web/features/`      | 功能模块（dashboard / projects / models / chat 等） |
+| `src/web/shared/`        | 前端共享代码（components / hooks / utils / types）  |
+| `src/shared/`            | 前后端共享类型（api.ts）和常量（app.ts）            |
+| `scripts/`               | 独立脚本，可 import 项目源码                        |
+| `drizzle/`               | SQL migration 文件（开发期产出）                    |
+| `tests/`                 | 测试目录，镜像 src/ 结构                            |
+
+### 前端目录使用规范
+
+#### 目录职责定义
+
+```
+src/web/
+├── main.tsx              ← 入口（Provider 装配、全局初始化）
+├── app.tsx               ← App 组件（路由挂载）
+├── routes.tsx            ← 全局路由表（集中声明）
+├── styles.css            ← 全局样式
+├── menu.tsx              ← 菜单配置类型定义
+├── layouts/              ← 布局组件
+│   ├── admin-layout/     ←   Admin 布局 + 侧边栏 + 菜单配置
+│   └── workbench-layout/ ←   Workbench 布局 + 项目上下文 + 入口守卫
+├── features/             ← 功能模块（核心目录）
+│   ├── dashboard/        ←   仪表盘页面 + 私有组件/hooks
+│   ├── projects/         ←   项目管理页面 + 私有组件/hooks
+│   ├── models/           ←   模型管理页面 + 私有组件/hooks
+│   ├── chat/             ←   聊天页面 + 私有组件/hooks
+│   └── <新增功能>/       ←   新功能直接新增目录
+├── shared/               ← 跨 feature 共享代码
+│   ├── components/       ←   通用 UI 组件（ErrorBoundary, Sidebar, ConsoleShell 等）
+│   ├── hooks/            ←   通用 hooks（use-logger, use-theme-preference, use-sidebar-collapsed 等）
+│   ├── utils/            ←   通用工具函数（api, logger, time）
+│   └── types.ts          ←   前端内部共享类型
+└── css.d.ts              ← CSS 模块类型声明
+```
+
+#### 依赖规则
+
+```text
+layouts/   →  shared/      ✅ 布局可使用共享代码
+features/* →  shared/      ✅ 功能模块可使用共享代码
+features/* →  layouts/     ❌ 功能模块不依赖布局（路由表负责组合）
+features/A →  features/B   ❌ 功能模块间禁止直接依赖
+shared/    →  features/*   ❌ 共享代码不依赖功能模块
+```
+
+#### feature 内部组织
+
+每个 feature 目录自治，不强制统一内部结构，按需组织以下子目录：
+
+```text
+features/<name>/
+├── index.tsx             ← 页面组件（必须，路由入口）
+├── components/           ← 私有 UI 组件
+├── hooks/                ← 私有 hooks（如 use-conversations 仅 chat 使用）
+├── utils/                ← 私有工具函数
+└── types.ts              ← 私有类型定义
+```
+
+- 只有 `index.tsx`（页面组件）是必需的，其他按实际复杂度按需创建。
+- feature 内部文件只在本 feature 内导入。被外部使用的必须提升到 `shared/`。
+
+#### 组件归属判定规则
+
+| 判定维度 | 放在 feature/                                      | 放在 shared/                                 |
+| -------- | -------------------------------------------------- | -------------------------------------------- |
+| 使用范围 | 仅一个功能模块使用                                 | 两个及以上功能模块使用                       |
+| 业务耦合 | 包含特定业务逻辑（如项目 CRUD 表单、聊天消息渲染） | 纯展示或通用交互（如 ErrorBoundary、侧边栏） |
+| 数据依赖 | 依赖特定 API 或业务数据                            | 无业务数据依赖或通过 props 注入              |
+| 可替换性 | 替换需理解业务上下文                               | 可直接复用于任何页面                         |
+
+#### 组件升降级流程
+
+**升级（feature → shared）：** 当一个 feature 内的组件/hook/tool 同时满足以下条件时，应提升到 `shared/`：
+
+1. 至少被 2 个不同的 feature 或 layout 使用
+2. 已消除对原 feature 业务逻辑的直接依赖（数据通过 props/callback 注入）
+3. 有清晰的 props 接口定义
+
+升级步骤：
+
+1. 将文件从 `features/<name>/` 移动到 `shared/` 对应子目录
+2. 更新所有 import 路径
+3. 如原 feature 有对应的测试文件，一并迁移（`tests/web/shared/`）
+4. 运行 `bun run check` 确认无遗漏
+
+**降级（shared → feature）：** 当一个 shared 组件/hook/tool 仅被一个 feature 使用时，应降级到该 feature 内部：
+
+1. 确认仅一个消费方（全局搜索 import）
+2. 移动到消费方 feature 的对应子目录
+3. 更新 import 路径
+4. 迁移对应测试文件
+5. 运行 `bun run check` 确认无遗漏
+
+#### 新增功能开发检查清单
+
+新增功能模块时按以下顺序操作：
+
+1. 在 `features/` 下创建以功能名命名的目录（kebab-case）
+2. 创建 `index.tsx` 作为页面组件入口
+3. 在 `routes.tsx` 中注册路由，选择对应 layout 包裹
+4. 如需布局内菜单项，更新对应 layout 的菜单配置
+5. 组件/hooks/utils 先写在 feature 内部
+6. 当确认需要跨 feature 复用时，按升级流程提升到 `shared/`
+7. 测试文件创建在 `tests/web/features/<name>/`
+
+#### 禁止事项
+
+- 禁止在 feature 目录外直接创建页面组件（`pages/` 目录不再使用）
+- 禁止 feature 间通过 `../features/other-feature/` 直接导入
+- 禁止在 shared/ 中放置仅单个 feature 使用的代码
+- 禁止跳过升降级流程直接在 shared/ 中新建"预判通用"的代码（先写 feature，确认复用后再提升）
 
 ### 类型与配置
 
@@ -141,10 +248,17 @@ AI 工具必须严格遵守以下全部约束。
 2. antd 布局组件（Layout、Space、Flex）
 3. antd theme token + CSS 变量
 4. TanStack Query + useState
-5. 已有 hooks（`use-*.ts`）和工具函数（`utils/`）
-6. CSS Modules（就近放置）
+5. 已有 hooks（`shared/hooks/use-*.ts`）和工具函数（`shared/utils/`）
+6. CSS Modules（就近放置在 feature 内部）
 7. 引入新依赖（需说明原因）
 
+### 前端代码组织
+
+- 新增页面在 `features/` 下创建功能目录，不使用 `pages/`。
+- 新增组件/hook/tool 默认放在所属 feature 内部；跨 feature 复用时提升到 `shared/`。
+- 布局组件放 `layouts/`，布局与页面通过 `routes.tsx` 组合，不互相导入。
+- 详细规则见上方「前端目录使用规范」章节。
+
 ### 样式红线
 
 - 严禁内联 `style`、覆盖 `.ant-*`、`!important`、硬编码色值。