3.5 KiB
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/组件接口调整;
- 改变业务交互路径或数据语义;
- 大规模迁移页面或删除历史实现。