nex_design_system/docs/13-project-stack-defaults.md

117 lines
4.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 13. Project Stack Defaults
## 1. 目的
NEX 0.1.5 修正 0.1.4 的一个问题:降低配置填写量,不等于移除新项目的技术选型。
新项目需要有明确、可执行的技术栈默认值。Agent 不应在空项目中自行猜测前后端框架、数据库或 UI 组件库;也不应要求用户从零填写整张技术清单。
因此,NEX 采用两种不同策略:
- **新项目(New)**:`nex.config.yaml` 中的默认技术栈就是默认实施目标。只有用户明确覆盖时才使用其他选型。
- **已有项目(Existing)**:真实代码、锁文件和构建配置代表当前技术事实。默认技术栈仅供参考,不得据此擅自迁移或替换现有技术。
## 2. 默认全栈方案
`config/project-profile.example.yaml` 提供以下默认方案:
| 层次 | 默认技术 | 用途 |
|---|---|---|
| 前端框架 | React | Web UI |
| 前端语言 | TypeScript | 类型安全 |
| 构建工具 | Vite | 开发与构建 |
| 包管理器 | npm | 依赖管理 |
| UI 组件库 | Ant Design | 企业级基础组件 |
| 样式方案 | Tailwind CSS v4 + CSS Variables | 布局工具类与语义化设计变量 |
| 状态管理 | Zustand | 跨组件状态 |
| 路由 | React Router | 前端路由 |
| HTTP 客户端 | Axios | API 通信 |
| 后端语言 | Python | 服务端开发 |
| 后端框架 | FastAPI | REST API |
| 数据校验 | Pydantic | 请求/响应模型 |
| ORM | SQLAlchemy | 数据访问 |
| 数据库迁移 | Alembic | Schema 版本管理 |
| 开发数据库 | SQLite | 本地开发与轻量部署 |
| 生产数据库 | PostgreSQL | 生产持久化 |
| API 风格 | REST + OpenAPI | 接口契约 |
| 本地静态资源 | `./data` | 媒体及文件资源 |
| 前端质量工具 | ESLint、Prettier、Vitest、Playwright | 代码、格式、单测和端到端测试 |
| 后端测试 | Pytest | 后端测试 |
具体依赖版本采用创建时兼容的稳定版本,并必须提交 lockfile。不得使用无版本约束的通配符依赖;具体版本选择应考虑所选框架、组件库和插件之间的兼容性。
## 3. 项目类型
默认 `project.type: fullstack`。
如项目不是全栈,只需修改一个字段:
```yaml
project:
type: frontend-only
```
或:
```yaml
project:
type: backend-only
```
不适用的部分不应初始化。例如 `frontend-only` 不应创建无用的 FastAPI 服务;`backend-only` 不应创建 React 前端。
## 4. 生命周期自动识别
默认 `project.lifecycle: auto`:
- 空仓库或尚无实际应用代码:按 `new` 处理,采用默认技术栈。
- 已存在可识别的应用代码、锁文件或构建配置:按 `existing` 处理,以当前代码为准。
- 仓库状态模糊且会影响是否创建/迁移技术栈时,先进行只读检查;必要时提出一个明确问题,不得擅自覆盖。
也可以手动设置 `new` 或 `existing`。
## 5. 覆盖默认技术栈
用户不需要填写整套配置。只需修改不符合当前项目意图的字段。例如希望使用 PostgreSQL 作为开发数据库:
```yaml
stack:
database:
development: PostgreSQL
production: PostgreSQL
```
例如希望采用其他 UI 方案:
```yaml
stack:
frontend:
ui_library: None
styling: Tailwind CSS v4 + CSS Variables
```
实际修改时应保留完整 YAML 层级,并仅覆盖有意变更的值。Agent 不得将未修改字段理解为“未指定”。
## 6. 新项目与已有项目的执行规则
### New
- 将 `stack` 视为技术选型约束,不要自行替换。
- 根据 `project.type` 初始化对应层次。
- 在创建代码前确认依赖兼容性、目录结构和本地运行方式。
- 可以提出必要的安全/部署问题,但不要重复询问配置里已经明确给出的技术选型。
- 如发现某项默认方案与明确需求冲突,先说明冲突并提出最小调整,不得静默改变栈。
### Existing
- 以锁文件、依赖清单、源码、构建配置和运行结果确认当前技术栈。
- 将自动发现结果写入审计报告,并与默认 profile 对比。
- 不因默认方案与现状不同而升级、替换或迁移。
- 只有用户明确授权技术迁移时,才制定单独迁移方案。
## 7. NEX 不统一项目技术栈的边界
以上是新项目的默认起步方案,不是对所有项目的强制技术栈。
用户可以通过少量字段覆盖默认值;已有项目可以完整保留自己的技术选型。NEX Core 仍然约束设计质量、组件复用、Token 单一来源、交互一致性、可访问性、响应式和质量证据,而不要求所有项目都采用同一套框架。