nex_design_system/docs/11-project-onboarding.md

3.5 KiB
Raw Blame History

11. Project Onboarding & Conformance Mapping

1. 项目类型与技术栈确认

NEX 0.1.5 采用“新项目明确默认技术栈、已有项目自动识别”的双模式,避免 0.1.4 将自动发现错误地应用于新项目技术选型。

新项目

默认 project.type: fullstack,采用 config/project-profile.example.yaml 中的默认栈:

  • 前端:React、TypeScript、Vite、npm、Ant Design、Tailwind CSS v4、Zustand、React Router、Axios;
  • 后端:Python、FastAPI、Pydantic、SQLAlchemy、Alembic;
  • 数据库:开发 SQLite、生产 PostgreSQL;
  • API:REST + OpenAPI;
  • 本地资源目录:./data;
  • 工具:ESLint、Prettier、Vitest、Playwright、Pytest。

新项目 Agent 必须遵循这些明确选型。若用户只需纯前端/纯后端,只修改 project.type。若要更换某项技术,只修改 stack 的对应字段。

已有项目

以真实代码、锁文件、构建配置、CI 和运行结果为证据,自动识别:

  • 前后端框架、语言、依赖版本、构建工具和 UI/样式方案;
  • 项目 UI/UX 规范与设计决策文档;
  • Token 权威来源、主题链路、共享组件目录和布局模式;
  • 路由、断点、响应式规则、质量命令、视觉基线和 CI;
  • 适用的辅助技术验证范围及尚未执行的人工测试。

已有项目的默认技术栈只用于对比,不是迁移目标。不得因默认栈不同而升级框架、替换 UI 库或迁移数据库。需要迁移时必须取得单独授权。

project.lifecycle: auto 根据仓库情况自动识别:空仓库按新项目处理;已存在应用代码、锁文件或构建配置按已有项目处理。仓库状态模糊且会影响技术决策时,先进行只读检查,再提出一个具体问题。

2. 符合性映射

复制 templates/project-conformance-matrix.md,按 NEX Core 主题逐项记录:

  • NEX 原则/规则;
  • 项目规范对应章节;
  • 实现位置;
  • 当前状态;
  • 证据/测试;
  • 差异和行动建议。

不要将不同设计体系的数字直接比较并判定不合规。例如 Header 64px 与 Header 56px 本身不存在跨项目的合规差异;需要判断尺寸是否符合当前项目任务、规范和真实运行效果。

3. Token 映射

至少记录:

NEX 语义 项目 Token 权威来源 派生链路/消费者 状态
Brand
Text Primary
Surface
Border
Spacing
Typography
Radius
Elevation/Z-index

若项目已有成熟的单向链路,不新增同义 Token 存储。记录其语义对应关系即可。

4. 组件映射

列出 NEX 常见能力与项目已有组件之间的对应关系。允许一项能力对应一个组件,也允许多个组件共同实现;若已有能力覆盖,应标记 ADAPTED 或 COMPLIANT,不必创建 NEX 同名组件。

5. 不适用项

对不存在的功能(例如项目没有 PDF、文档、AI Chat 或流程画布)标记 NOT_APPLICABLE。不得因为 NEX 文档包含了相应模式,就新增该功能或强制创建占位页面。

6. 批准和变更

审计报告中的建议不等于自动授权。对以下内容,需取得明确任务授权:

  • 修改品牌视觉或全局布局;
  • 改变导航或移动端交互;
  • 更换组件库、样式技术或主要架构;
  • 破坏性 API/组件接口调整;
  • 改变业务交互路径或数据语义;
  • 大规模迁移页面或删除历史实现。