53 lines
3.5 KiB
Markdown
53 lines
3.5 KiB
Markdown
# 前端协作指南
|
||
|
||
## Local Purpose
|
||
|
||
本目录维护简体中文 Angular 网页，包括 Flash/Pro/探索、人工示范、插件、精选任务、模型配置、批次、历史、报告与跨端证据。
|
||
|
||
## Inherits
|
||
|
||
继承仓库根目录 AGENTS.md；本文件仅补充前端规则，当前用户指令优先。
|
||
|
||
修改 UI 前阅读根目录 [DESIGN.md](../../DESIGN.md) 的视觉与交互约定；本应用没有独立的局部 DESIGN.md。SDK 的同名文件描述远程协议，不是网页设计来源。
|
||
|
||
## Local Commands
|
||
|
||
在本目录执行，包管理器使用 npm 和现有 package-lock.json：
|
||
|
||
```sh
|
||
npm ci
|
||
npm start
|
||
```
|
||
|
||
完成前端改动后执行以下检查；无头测试需要已安装 Chrome：
|
||
|
||
```sh
|
||
npm test -- --watch=false --browsers=ChromeHeadless
|
||
npm run build
|
||
```
|
||
|
||
开发服务器通过 proxy.conf.json 连接本地后端；需要联调时同时启动根目录的网页服务。
|
||
|
||
## Local Conventions
|
||
|
||
- 发版遵守根指南的 Release Gates。前端应用版本只改 package.json 顶层 `version` 和 package-lock.json 顶层及 `packages[""].version`；禁止把相同数字的第三方依赖一并替换。
|
||
- Node 支持范围以锁定的 Angular CLI/构建依赖实际 `engines` 为准，核对启动脚本的主、次、补丁版本边界和提示；不要只判断“Node 22/24/26”。
|
||
- 安装或依赖变更需在隔离目录、独立空 npm 缓存下运行 `npm ci`，再运行上述测试和构建；国内入口同时核验镜像安装。不得以关闭完整性校验、强制安装或删除锁文件掩盖不一致，也不得用已装依赖的构建结果宣称全新安装通过。
|
||
- 页面组件在 src/app/components，服务在 src/app/services；先复用已有组件、样式及 API 服务。
|
||
- 保持现有简体中文文案、颜色、间距和控件样式，菜单、弹窗和表单必须清晰可读。
|
||
- 修改任务或配置交互时覆盖加载、保存、失败和空状态；不要将执行中误标成录屏中或把完成误标成验证通过。
|
||
- 使用相邻的 .spec.ts 测试交互和请求数据；不要只测试实现细节。
|
||
- 后端字段调整需同时核对类型、请求和响应；设备序列号、报告格式、批次编号等不能在前端猜测。
|
||
- UI 有明显变化时在浏览器验证实际布局和关键操作，构建通过不能代替可读性检查。
|
||
- 工作区底部输入框服务当前任务；探索建议只填入草稿，用户发送后再提交。用例编辑和配置按需展开，复跑固定保存版本。
|
||
- 主模型、兜底模型及精选任务复用现有模型选择组件；收藏使用已保存的独立配置，设备离线时给出可操作的选择提示。
|
||
- 星标仅占标题区域，后续状态行正常左对齐；人工示范来源与按钮保持等高、居中，窄屏可换行。执行、等待回答、示范准备/录制/分析、最终验收及未验证各有明确文字。
|
||
- 电脑步骤使用电脑证据，录像缺口明确展示。播放器按真实来源和时间定位，跳转保留原播放/暂停状态。
|
||
- 列表后台刷新保留选中项、滚动及折叠状态，不用反复插入的加载行挤动布局；实时连接沿用现有共享机制和页面可见性管理。
|
||
|
||
## Local Risks
|
||
|
||
- 不读取或展示已保存密钥；模型配置的空密钥表示保留原值，测试连接与保存配置保持分离。
|
||
- 不为查看历史而启动真实任务，不自动重试业务用例，不恢复已移除的设备动作回放。
|
||
- 不编辑 dist 或 node_modules；提交源码及必要锁文件。源码包不携带编译后的网页。
|