From de51a817fbdc0f89e381eb234d0c75bf177c07d3 Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Mon, 1 Jun 2026 16:12:21 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BC=80=E5=8F=91=E8=A7=84=E8=8C=83?= =?UTF-8?q?=E9=87=8D=E6=9E=84=20=E2=80=94=20=E6=96=B0=E5=A2=9E=E5=90=8E?= =?UTF-8?q?=E7=AB=AF=E7=BA=A2=E7=BA=BF=E3=80=81=E7=A6=81=E6=AD=A2=E4=BA=8B?= =?UTF-8?q?=E9=A1=B9=E6=B1=87=E6=80=BB=E3=80=81=E5=89=8D=E7=AB=AF=E8=83=BD?= =?UTF-8?q?=E5=8A=9B=E4=BC=98=E5=85=88=E7=BA=A7=EF=BC=8C=E7=B2=BE=E7=AE=80?= =?UTF-8?q?=20config.yaml?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/development/README.md | 298 ++++++++++++++++++++----------------- openspec/config.yaml | 45 +++--- 2 files changed, 181 insertions(+), 162 deletions(-) diff --git a/docs/development/README.md b/docs/development/README.md index 1430188..2a35822 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -1,155 +1,181 @@ -# 开发文档 - -本文档是 alfred 的开发入口，包含**全部开发规范**和专题索引。AI 工具和开发者应首先阅读本文档掌握所有约束，再按需查阅专题文档获取实现细节。 - -适用场景：修改源码、测试、构建脚本、开发流程、架构边界或项目工程规则。 - -## 专题索引 - -| 文档 | 内容 | -| ---------------------------------- | ----------------------------------------------------------------- | -| [architecture.md](architecture.md) | 项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界 | -| [backend.md](backend.md) | 后端实现细节：模块 API、工具函数索引、数据访问函数清单、AI 层说明 | -| [frontend.md](frontend.md) | 前端实现细节：运行时代码结构、组件索引、页面组成、hooks/工具清单 | -| [release.md](release.md) | 开发服务、前后端集成、构建、脚本、环境变量 | -| [../README.md](../README.md) | 文档路由、文档归属矩阵、文档更新规则 | - ---- - # 开发规范 -以下规范是所有代码变更必须遵守的约束。AI 工具必须严格遵守，开发者 review 时以此为准。 +AI 工具必须严格遵守以下全部约束。 + +## 专题文档 + +| 文档 | 内容 | +| ---------------------------------- | ---------------------------------- | +| [architecture.md](architecture.md) | 项目结构、启动流程、前后端边界 | +| [backend.md](backend.md) | 模块 API、数据访问函数、AI 层说明 | +| [frontend.md](frontend.md) | 组件索引、页面组成、hooks/工具清单 | +| [release.md](release.md) | 开发服务、构建、脚本、环境变量 | + +--- ## 一、全局规则 ### 语言与环境 -- 使用中文编写注释、文档和项目内交流内容。 -- 仅使用 bun 作为包管理器，禁止使用 npm、pnpm、yarn。 -- 运行工具使用 bunx，禁止使用 npx、pnpx。 -- 当前项目无需考虑向前兼容。 +- 使用中文编写注释、文档和交流内容。 +- 仅使用 bun 作为包管理器和 bunx 作为工具运行器；禁止 npm、pnpm、yarn、npx、pnpx。 +- 无需考虑向前兼容。 ### 依赖引入 -**后端**：新增依赖前必须按以下优先级检查，上层已有方案则不得引入新依赖： +**后端**优先级（上层已有方案则不得引入新依赖）： -| 优先级 | 来源 | 典型用途 | -| ------ | ------------ | ---------------------------------------------------- | -| 1 | Bun 内置 API | Bun.serve、Bun.file、Bun.YAML、Bun.spawn、bun:sqlite | -| 2 | es-toolkit | 类型判断、深度比较、并发控制 | -| 3 | 标准 Web API | Headers、fetch、AbortController | -| 4 | 主流三方库 | pino、@sinclair/typebox、ajv、drizzle-orm | -| 5 | 自行实现 | 仅在以上都无法满足时 | +1. Bun 内置 API（Bun.serve、bun:sqlite 等） +2. es-toolkit +3. 标准 Web API（fetch、Headers 等） +4. 已批准三方库：pino、@sinclair/typebox、ajv、drizzle-orm、ai、@ai-sdk/\* +5. 自行实现（仅以上都不满足时） -**前端**：新增代码优先复用已有组件、工具和依赖库，不引入新依赖。确需新增依赖时先说明原因。 +**前端**：优先复用已有组件/hooks/依赖库；确需新增依赖时先说明原因。 -### Git 提交 - -- 提交信息使用中文，格式为 `类型: 简短描述`。 -- 提交类型限定为：`feat`、`fix`、`refactor`、`docs`、`style`、`test`、`chore`。 -- 多行提交描述时，标题和正文之间空一行。 +**Zod**：已引入但未使用（预留），配置校验用 TypeBox + Ajv，不得混用 Zod。 ### 目录边界 -| 目录 | 约定 | -| ------------------- | -------------------------------------------------------------------- | -| `src/server/` | Bun 后端代码，不能 import src/web/，HTML import 集成除外 | -| `src/server/db/` | SQLite 数据库模块，包含 schema、connection、migration 和 data access | -| `src/server/ai/` | AI Provider Registry 构建与连接测试 | -| `src/web/` | React 前端，不能 import src/server/ 运行时实现 | -| `src/shared/` | 前后端共享 TypeScript 类型 | -| `scripts/` | 独立运行脚本，可 import 项目源码 | -| `drizzle/` | Drizzle Kit 生成的 SQL migration 文件（开发期产出） | -| `tests/` | 测试目录，结构镜像 src/ | -| `docs/user/` | 用户使用、配置、部署和排障文档 | -| `docs/development/` | 架构、后端、前端、发布开发文档 | -| `openspec/` | OpenSpec 变更管理与规格文档 | +| 目录 | 约束 | +| ------------------------ | -------------------------------------------- | +| `src/server/` | 后端，禁止 import src/web/ | +| `src/server/db/` | 数据库层：schema、connection、migration、DAO | +| `src/server/ai/` | AI Provider Registry + Agent + 工具 | +| `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/shared/api.ts` 为唯一源头。 -- 应用常量以 `src/shared/app.ts` 为唯一源头。 -- 版本号以 `package.json.version` 为唯一源头。 -- 前端不得 import `src/server/` 下的任何文件。 -- 配置加载流程固定为：unknown → AuthoringConfig → NormalizedConfig → ValidatedConfig → ServerConfig。 -- Ajv 保持严格拒绝模式：不开类型强制转换、不注入默认值、不自动删除未知字段。 -- 新增或修改配置字段时必须同步更新 TypeBox schema fragments、`config.schema.json`、测试和对应用户文档。 +- 共享类型唯一源头：`src/shared/api.ts`；应用常量唯一源头：`src/shared/app.ts`；版本号唯一源头：`package.json`。 +- 配置加载流程：unknown → AuthoringConfig → NormalizedConfig → ValidatedConfig → ServerConfig。 +- Ajv 严格拒绝模式：不类型转换、不注入默认值、不删除未知字段。 +- 新增/修改配置字段必须同步更新 TypeBox schema、`config.schema.json`、测试和用户文档。 ### 后端日志 -- 后端运行时代码统一通过 Logger 接口输出日志，禁止直接使用 `console.*`（仅 `src/server/logger.ts` 的实现类内部可用）。 -- 敏感信息自动 redact `authorization`、`cookie`、`password` 等字段。 +- 运行时代码通过 Logger 接口输出，禁止 `console.*`（仅 `logger.ts` 实现类内部可用）。 +- 敏感字段（authorization、cookie、password 等）自动 redact。 ### API 路由 -- 路由文件位于 `src/server/routes/`，每个端点一个文件。 -- 路由通过 `server.ts` 的 `Bun.serve({ routes })` 声明式注册。 -- 新增路由步骤：创建 handler 文件 → 在 `server.ts` 注册 → 在 `tests/server/` 添加测试。 +- 每个端点一个文件：`src/server/routes/{资源}/{操作}.ts`。 +- 路由在 `server.ts` 的 `Bun.serve({ routes })` 中声明式注册。 +- 新增路由：创建 handler → 在 `server.ts` 注册 → 在 `tests/server/` 添加测试。 ### 前端数据层 - 统一使用 `fetch`，不引入 axios。 -- 错误抛异常，由 TanStack Query 的 error 状态承接。 -- 前端 fetch 返回类型必须匹配后端真实 JSON 形状；后端返回包装对象（如 `{ project: Project }`）时，应声明对应响应类型并在 hook 内提取业务对象。 -- 不引入额外状态管理库。TanStack Query 承担服务端状态，组件内状态使用 `useState`。 +- 错误抛异常，TanStack Query error 状态承接。 +- 返回类型必须匹配后端 JSON 形状；包装对象（如 `{ project }`）须在 hook 内提取业务对象。 +- 服务端状态用 TanStack Query，组件内状态用 `useState`，不引入额外状态管理库。 + +### 禁止事项 + +- 禁止前端 import `src/server/` +- 禁止后端使用 `console.*` +- 禁止组件内联 `style` 属性 +- 禁止 CSS 覆盖 `.ant-*` 内部类名 +- 禁止 `!important` +- 禁止硬编码色值（使用 `var(--ant-*)` CSS 变量） +- 禁止路由 handler 直接操作 `bun:sqlite` / Drizzle ORM（须通过 DAO 层） +- 禁止跳过或忽略测试 +- 禁止在 `Modal onOk` 中直接执行异步提交（用 `Form onFinish`） --- -## 二、前端红线 +## 二、后端红线 -### 组件红线 +### 路由 handler -- 优先使用 antd 组件默认能力和 props 配置行为，不额外改写组件视觉。 -- 全局使用 `ConfigProvider` 配置中文 locale 和主题切换，不在 CSS 中硬编码亮色或暗色分支。 -- 需要 message、modal、notification 等应用级能力时，在 `ConfigProvider` 内包裹 `App`（代码中别名为 `AntApp`），组件内通过 `App.useApp()` 获取。 -- 页面组件保持编排职责，组合 hooks 和展示组件；当页面同时承担查询、筛选、分页、表格列、弹窗表单和 mutation 时，应按功能边界拆分。 +- 签名：`(req: Request, db: Database, mode: RuntimeMode, logger?: Logger): Promise`。 +- 业务错误：`jsonResponse(createApiError(msg, status), { mode, status })`；未知异常直接 throw，`withErrorHandler` 兜底。 +- body 解析后立即校验必填字段和类型，失败返回 400。 +- ID 参数走 `validateIdParam`，分页参数走 `validatePagination`。 +- 路由注册：`withErrorHandler` 包裹 + 动态 `await import()` 加载 handler。 + +### 数据访问层 + +- handler 通过 `src/server/db/*.ts` 函数操作数据库，禁止直接使用 `bun:sqlite` 或 Drizzle。 +- DAO 函数第一个参数接收原始 `Database`，内部 `wrap(db)` 转 Drizzle。 +- 返回联合类型：成功 `{ resource: T }`，失败 `{ error: string; status: number }`。 +- 输入输出类型来自 `src/shared/api.ts`。 +- 列表查询使用 `paginateQuery()`，不重复实现分页。 +- 列名 snake_case，TS 类型 camelCase，Drizzle schema 映射。 + +### AI 调用层 + +- Provider 实例：`buildProviderRegistry(db)`，每次从 DB 重建，不缓存。 +- Agent 实例：`createAlfredAgent(model)` 工厂。 +- SSE 响应：`createAgentUIStreamResponse`，`onFinish` 持久化完整 parts。 +- 工具定义：`src/server/ai/tools/`。 + +### 错误处理 + +- 业务异常用 `AppError(statusCode)` 或 `jsonResponse(createApiError(...))`。 +- handler 外层 `withErrorHandler` 兜底，不手动 try-catch 整个 handler。 +- 生产模式错误响应不暴露内部细节。 + +--- + +## 三、前端红线 + +### 组件规范 + +- 优先 antd 默认能力 + props，不额外改写视觉。 +- `ConfigProvider(zhCN)` 配置中文 locale 和主题，不在 CSS 硬编码亮/暗分支。 +- 应用级能力（message、modal、notification）通过 `AntApp` + `App.useApp()` 获取。 +- 页面保持编排职责，组合 hooks + 展示组件；复杂页面按功能边界拆分。 + +### 能力优先级（上层满足则不用下层） + +1. antd 组件/props +2. antd 布局组件（Layout、Space、Flex） +3. antd theme token + CSS 变量 +4. TanStack Query + useState +5. 已有 hooks（`use-*.ts`）和工具函数（`utils/`） +6. CSS Modules（就近放置） +7. 引入新依赖（需说明原因） ### 样式红线 -- **严禁**在组件中使用 `style` 属性内联样式。 -- **严禁**通过 CSS 覆盖 antd 组件内部类名（`.ant-*`）。 -- **严禁**使用 `!important`。 -- **严禁**使用硬编码色值，颜色统一使用 antd CSS 变量（`var(--ant-*)`）。 -- 默认不引入 Tailwind、Sass、Less、CSS-in-JS 等额外样式方案；确需引入时必须先说明原因和影响范围。 - -### 样式指导原则 - -- antd 承担主视觉系统，项目 CSS 只补足页面外壳和局部布局，不另起一套样式体系。 -- 样式选择优先级：antd 默认能力 → antd props → antd 布局组件 → theme token → antd CSS 变量 → 全局 CSS。 -- 全局 CSS 仅承载应用外壳和基础样式，类名使用 `app-*` 前缀，禁止泛名类（如 `.container`、`.title`）。 -- 当样式需求增长到需要就近维护时，使用 CSS Modules 与页面/组件同级放置。 +- 严禁内联 `style`、覆盖 `.ant-*`、`!important`、硬编码色值。 +- 颜色使用 `var(--ant-*)` CSS 变量。 +- 不引入 Tailwind/Sass/Less/CSS-in-JS 等额外样式方案。 +- 全局 CSS 类名用 `app-*` 前缀，禁止泛名。样式增长后用 CSS Modules 就近维护。 ### 表单与交互 -- Modal + Form 提交使用 `Form onFinish` 处理业务提交，`Modal onOk` 只触发 `form.submit()`。 -- 不在 `Modal onOk` 中直接执行异步 `validateFields` 和提交逻辑。 -- 文本必填字段同时配置 `required: true` 和 `whitespace: true`，保持前后端校验一致。 -- 操作确认优先使用 `Popconfirm`，成功/失败反馈优先使用 antd message。 +- Modal + Form：`Form onFinish` 处理提交，`Modal onOk` 只调 `form.submit()`。 +- 必填文本字段同时配 `required` + `whitespace`。 +- 操作确认用 `Popconfirm`，反馈用 antd message。 -### 错误边界 - -- 生产入口必须启用 `ErrorBoundary`。 -- `ReactQueryDevtools` 仅在 `import.meta.env.DEV` 条件下渲染。 +- 生产入口必须启用 `ErrorBoundary`。`ReactQueryDevtools` 仅 `DEV` 模式渲染。 --- -## 三、测试规范 +## 四、测试规范 -### 后端测试 +### 后端 -- API 路由集成测试必须通过真实 `startServer` 覆盖路由注册、HTTP method、fallback、响应 header 和核心错误路径。 -- SQLite 相关测试必须复用 `tests/helpers.ts` 中的测试数据库 helper，不要在测试文件内分散实现临时目录清理。 -- DAO 和路由边界测试应优先使用真实 migration 初始化测试库。 -- logger/bootstrap 中预期的 fallback 输出必须在测试中捕获并断言，正常通过的测试不应污染 stdout/stderr。 +- 路由测试通过真实 `startServer` 覆盖路由注册、HTTP method、fallback、header 和核心错误路径。 +- SQLite 测试复用 `tests/helpers.ts`，不分散实现临时目录清理。 +- DAO/路由测试优先用真实 migration 初始化。 +- logger/bootstrap fallback 输出须捕获断言，正常测试不污染 stdout/stderr。 -### 前端测试 +### 前端 -- 测试目录为 `tests/web/`，结构对应 `src/web/`。 -- 组件测试使用 jsdom 和 `@testing-library/react`，测试用户行为而非实现细节。 -- 断言优先基于用户可见文本、role、按钮和交互结果，不依赖 `.ant-*` 内部类名。 -- 系统边界（fetch mock、路由、QueryClientProvider）优先复用 `tests/web/test-utils.tsx`。 -- 数据驱动页面至少覆盖请求 URL/query、method/body、成功后的用户可见结果，以及关键错误路径。 -- ErrorBoundary、hooks 纯逻辑和 fetch helper 应使用单元测试覆盖异常回退，页面测试只保留真实用户路径。 +- 目录 `tests/web/`，结构对应 `src/web/`。 +- 用 jsdom + `@testing-library/react` 测试用户行为，断言基于可见文本/role/按钮。 +- 系统边界复用 `tests/web/test-utils.tsx`。 +- 数据页面覆盖：请求参数、成功可见结果、关键错误路径。 +- ErrorBoundary/hooks/fetch helper 用单元测试覆盖异常，页面测试只保留用户路径。 --- @@ -157,39 +183,35 @@ | 命令 | 说明 | | -------------------------------- | -------------------------------------- | -| `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 run format:check` | Prettier 格式检查 | -| `bun test` | 运行全部测试 | +| `bun run dev:server config.yaml` | 仅后端 API server | +| `bun run dev:web` | 仅 Vite dev server | | `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 build` | 构建生产可执行文件 | +| `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 clean` | 清理构建缓存 | +| `bun run version:patch` | 升迁 patch 版本 | +| `bun run version:minor` | 升迁 minor 版本 | +| `bun run version:major` | 升迁 major 版本 | | `bun run version:set` | 显式设置版本号 | ## 质量门禁 -代码变更必须按影响范围执行验证。 +| 变更类型 | 必跑命令 | +| ----------------------- | --------------------------------------------------------- | +| 常规代码变更 | `bun run check` | +| 构建、部署、集成变更 | `bun run verify` | +| 配置 schema 变化 | `bun run schema`、`bun run schema:check`、`bun run check` | +| SQLite 测试基础设施变化 | 相关测试 + SQLite 聚焦 `--rerun-each` + `bun run check` | +| 仅文档变更 | 检查链接、索引和文档归属一致性 | -| 变更类型 | 必跑命令 | -| -------------------------- | ------------------------------------------------------------- | -| 常规代码变更 | `bun run check` | -| 构建、部署、前后端集成变更 | `bun run verify` | -| 配置 schema 变化 | `bun run schema`、`bun run schema:check`、`bun run check` | -| SQLite 测试基础设施变化 | 相关单文件测试 + SQLite 聚焦 `--rerun-each` + `bun run check` | -| 仅文档变更 | 检查链接、索引和文档归属一致性 | - -正式提交或影响构建产物时优先运行 `bun run verify`。如果因环境限制无法执行完整验证，必须在收尾说明中记录未执行项和原因。 +正式提交优先运行 `bun run verify`。无法执行时须在收尾说明中记录。 ## 已知设计决策 @@ -199,17 +221,15 @@ ## 文档影响分析 -每次代码变更都必须执行文档影响分析。 +| 变更影响 | 更新 | +| -------------------------------------- | ------------------------------------------ | +| 用户可见行为、配置、部署、运行行为 | `docs/user/` 对应文档 | +| 开发流程、架构、测试、构建发布流程 | `docs/development/` 对应文档 | +| 项目定位、快速开始、核心能力、文档导航 | `README.md` | +| 文档同步规则或归属矩阵 | `docs/README.md` 和 `openspec/config.yaml` | +| 开发规范变化 | 本文档对应章节 | -| 如果变更影响 | 更新 | -| ------------------------------------------ | ------------------------------------------ | -| 用户可见行为、配置、部署、运行行为 | `docs/user/` 对应文档 | -| 开发流程、架构、测试、构建发布流程 | `docs/development/` 对应文档 | -| 项目定位、快速开始、核心能力列表、文档导航 | `README.md` | -| 文档同步规则或文档归属矩阵 | `docs/README.md` 和 `openspec/config.yaml` | -| 开发规范变化 | 本文档对应章节 | - -如果无需更新文档，必须在收尾说明中说明原因。详细规则见 [文档总览](../README.md)。 +无需更新文档时，须在收尾说明中说明原因。 ## 更新触发条件 diff --git a/openspec/config.yaml b/openspec/config.yaml index 9a3d00e..99b18fb 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -1,32 +1,31 @@ schema: fast-drive context: | + ## 项目概览 + - 本项目为 Bun 全栈应用（Alfred·阿福），Bun 是唯一包管理器和运行时，严禁使用 npm、pnpm、yarn、npx、pnpx + - docs/user/ 记录用户使用方法，docs/development/ 记录开发技术细节 - 使用中文（注释、文档、交流），面向中文开发者 - - **优先阅读 docs/README.md** 获取文档路由、归属矩阵和影响分析规则 - - **其次阅读 docs/development/README.md** 获取开发规范、常用命令、质量门禁和全局规则 - - 文档文件名优先使用单个英文单词（usage.md、config.md、deploy.md、troubleshoot.md），目录上下文足以消歧时不在文件名重复限定词 - - 每次代码变更必须执行文档影响分析： - - 用户可见行为、配置、部署、运行行为变更 → 更新 docs/user/ 对应文档 - - 开发流程、架构、测试、构建发布流程变更 → 更新 docs/development/ 对应文档 - - 项目定位、快速开始、核心能力列表、文档导航变更 → 更新 README.md - - 文档同步规则或文档归属矩阵变更 → 更新 docs/README.md 和本文件 - - 无需更新文档时必须在收尾说明中说明原因 - - 新增代码优先复用已有组件、工具、依赖库，不引入新依赖 - - 新增的逻辑必须编写完善的测试，并保证测试的正确性，不允许跳过任何测试 - - 这是基于bun实现的前端后一体化项目，使用bun作为唯一包管理器，严禁使用pnpm、npm，使用bunx运行工具，严禁使用npx、pnpx - - src/server目录下是基于bun实现的后端代码 - - 后端库使用优先级：Bun 内置 API > es-toolkit > 主流三方库 > 项目公共工具 > 自行实现 - - src/web目录下是基于Bun HTML import、React、Ant Design实现的前端代码 - - 前端最高规约：优先使用 antd 组件默认能力和组件 props 组合界面，具体组件、样式、数据流和测试细节遵循 docs/development/frontend.md - - 前端样式管理：antd 组件/props/token 优先，AppShell 使用最小全局 CSS，页面和自有组件样式增长后使用就近 CSS Modules，默认不引入 Tailwind、UnoCSS、Sass、Less、CSS-in-JS 等额外样式体系 - - 前端样式红线：禁止组件内联 style、覆盖 antd 内部类名、使用 !important、硬编码色值 - - Git提交: 仅中文; 格式"类型: 简短描述", 类型: feat/fix/refactor/docs/style/test/chore; 多行描述空行后写详细说明 - - 禁止创建git操作task - - 积极使用subagents精心设计并行任务，节省上下文空间，加速任务执行 - - 优先使用提问工具对用户进行提问 - - 本项目为 Bun 全栈应用（Alfred·阿福），docs/user/ 记录用户使用方法，docs/development/ 记录开发技术细节 - 本项目无需考虑向前兼容性 + ## 文档入口（按顺序阅读） + - **优先阅读 docs/README.md** 获取文档路由、归属矩阵和影响分析规则 + - **其次阅读 docs/development/README.md** 获取完整开发规范、常用命令和质量门禁 + + ## 全局红线 + - 前端禁止导入 src/server/ 的后端运行时实现 + - 后端运行时代码禁止直接使用 console.*，通过 Logger 实例输出 + - 新增逻辑必须编写完善的测试，不允许跳过任何测试 + - 每次代码变更必须执行文档影响分析（详见 docs/README.md） + - 新增代码优先复用已有组件、工具、依赖库，不轻易引入新依赖 + + ## Git 规范 + - 提交信息中文，格式"类型: 简短描述"，类型：feat/fix/refactor/docs/style/test/chore + - 禁止创建 git 操作 task + + ## 工作方式 + - 积极使用 subagents 并行任务，节省上下文空间 + - 优先使用提问工具对用户确认 + rules: design: - fast-drive的design.md章节标题和正文使用中文；仅OpenSpec术语、文件名、schema字段名、命令和代码符号保留英文