lanyuanxiaoyao
6cb378d7cb
- 抽取 ConsoleShell 共享外壳（Layout/Header/Sider/主题切换/侧边栏折叠） - Sidebar 纯化为接受 menuItems prop 的展示组件 - Admin 管理台：/ 总览 + /projects 项目管理 - Workbench 工作台：/workbench/:projectId 项目作用域 - WorkbenchProjectGate 入口守卫（loading/error/archived/不存在拦截） - ProjectContext 提供当前项目上下文 - 项目管理表格 active 行增加'进入工作台'按钮 - 项目名称 trim 后最多 10 字符（前后端一致） - Workbench 总览页展示项目 Descriptions - Header 区分：管理台显示副标题，工作台显示项目名 + 返回管理台按钮 - 28/28 前端测试通过 - 文档更新：frontend.md ConsoleShell 规范、usage.md 双入口说明
开发文档
本文档是 alfred 的开发入口。AI 工具和开发者应先阅读 ../README.md 判断文档归属，再阅读本文和最小必要专题。
适用场景：修改源码、测试、构建脚本、开发流程、架构边界或项目工程规则。
专题索引
| 文档 | 内容 |
|---|---|
| architecture.md | 项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界 |
| backend.md | 后端库优先级、API 路由、共享工具、类型规范、配置契约、日志、测试 |
| frontend.md | React、Ant Design、TanStack Query、组件、样式和前端测试规范 |
| release.md | 开发服务、前后端集成、构建、脚本、环境变量 |
| ../README.md | 文档路由、文档归属矩阵、development/user 文档更新规则 |
常用命令
| 命令 | 说明 |
|---|---|
bun install |
安装依赖 |
bun run dev config.yaml |
启动双进程开发环境 |
bun run dev:server config.yaml |
仅启动后端 API server |
bun run dev:web |
仅启动 Vite dev server |
bun run schema |
生成 config.schema.json |
bun run schema:check |
检查导出 schema 是否同步 |
bun run typecheck |
TypeScript 类型检查 |
bun run lint |
ESLint 和 Prettier 格式检查 |
bun run format |
Prettier 自动格式化 |
bun test |
运行全部测试 |
bun run check |
schema:check + typecheck + lint + test |
bun run build |
构建生产可执行文件 |
bun run verify |
check + build 完整验证 |
bun run clean |
清理构建缓存与临时文件 |
bun run version:patch |
升迁 patch 版本（x.y.Z） |
bun run version:minor |
升迁 minor 版本（x.Y.0） |
bun run version:major |
升迁 major 版本（X.0.0） |
bun run version:set |
显式设置版本号 |
质量门禁
代码变更必须按影响范围执行验证。
| 变更类型 | 必跑命令 |
|---|---|
| 常规代码变更 | bun run check |
| 构建、部署、前后端集成变更 | bun run verify |
| 配置 schema 变化 | bun run schema、bun run schema:check、bun run check |
| 仅文档变更 | 检查链接、索引和文档归属一致性 |
正式提交或影响构建产物时优先运行 bun run verify。如果因环境限制无法执行完整验证，必须在收尾说明中记录未执行项和原因。
全局工程规则
- 使用中文编写注释、文档和项目内交流内容。
- 仅使用 bun 作为包管理器，禁止使用 npm、pnpm、yarn。
- 运行工具使用 bunx，禁止使用 npx、pnpx。
- 新增代码优先复用已有组件、工具和依赖库，不引入新依赖；确需新增依赖时先说明原因。
- 后端优先使用 Bun 内置 API，其次是 es-toolkit、标准 Web API、主流三方库，最后才自行实现。
- 前端优先使用 Ant Design 组件默认能力和组件 props 组合界面，具体组件、样式、数据流和测试细节见 frontend.md。
- 当前项目无需考虑向前兼容。
包管理、依赖与提交
- 仅使用 bun 安装依赖和运行项目脚本，锁文件为 bun.lock。
- 新增依赖前先确认 Bun 内置 API、es-toolkit、标准 Web API、现有三方库和项目公共工具是否已满足需求。
- Git 提交信息使用中文，格式为"类型: 简短描述"。
- 提交类型限定为 feat、fix、refactor、docs、style、test、chore。
- 多行提交描述时，标题和正文之间空一行。
目录边界
| 目录 | 约定 |
|---|---|
src/server/ |
Bun 后端代码，不能 import src/web/，HTML import 集成除外 |
src/server/db/ |
SQLite 数据库模块，包含 schema、connection、migration 和 data access |
src/web/ |
React 前端，不能 import src/server/ 运行时实现 |
src/shared/ |
前后端共享 TypeScript 类型 |
scripts/ |
独立运行脚本，可 import 项目源码 |
drizzle/ |
Drizzle Kit 生成的 SQL migration 文件（开发期产出） |
tests/ |
测试目录，结构镜像 src/ |
docs/user/ |
用户使用、配置、部署和排障文档 |
docs/development/ |
架构、后端、前端、发布开发文档 |
openspec/ |
OpenSpec 变更管理与规格文档 |
文档影响分析
每次代码变更都必须执行文档影响分析。
| 如果变更影响 | 更新 |
|---|---|
| 用户可见行为、配置、部署、运行行为 | docs/user/ 对应文档 |
| 开发流程、架构、测试、构建发布流程 | docs/development/ 对应文档 |
| 项目定位、快速开始、核心能力列表、文档导航 | README.md |
| 文档同步规则或文档归属矩阵 | docs/README.md 和 openspec/config.yaml |
如果无需更新文档，必须在收尾说明中说明原因。详细规则见 文档总览。
事实来源
| 主题 | 事实来源 |
|---|---|
| 代码结构和实现 | src/、scripts/、tests/ |
| 配置 schema | TypeBox fragments、config.schema.json、schema 测试 |
| 项目全局规则 | openspec/config.yaml、本文档、本目录专题文档 |
更新触发条件
修改常用命令、质量门禁、全局工程规则、目录边界或开发文档索引时，必须更新本文档。