# Forge项目用户偏好

## 1. 前端 Node 版本

**记录日期**: 2026-05-07

运行前端相关命令（如 `pnpm install`、`pnpm exec eslint`、`pnpm build`）前，先执行：

```bash
source ~/.nvm/nvm.sh && nvm use v20.19.0
```

避免使用系统默认 Node 12 导致 pnpm 版本不兼容。

**2026-07-07 纠正**：当前机器已安装并验证可用 `v20.19.0`，未安装 `v20.20.0`。前端校验和构建仍优先使用：

```bash
source ~/.nvm/nvm.sh && nvm use v20.19.0
```

## 2. 前端样式变更偏好

**记录日期**: 2026-05-14

用户对“看起来像 AI 生成”的后台页面较敏感，尤其反感只改 CSS 但视觉无明显变化的结果。涉及页面美化时需要做可感知的结构、布局和交互改动，并通过 lint/build 或本地预览验证后再反馈。

## 3. 自动化测试执行偏好

**记录日期**: 2026-06-02

用户希望自动化测试流程标准化、可复用。后续执行 `/test`、阶段验证或归档前验证时，必须先读取 `code-copilot/rules/automated-testing-standard.md`，复用当前变更已有 `test-spec.md`、`execution-log.md`、`spec.md`、`tasks.md`，根据本轮差异做增量验证，不要每次从零开始。

## 4. 低代码表单设计器交互偏好

**记录日期**: 2026-06-15

用户希望低代码表单设计器前端操作便捷简单，拖拉拽体验要接近飞书多维表格的顺滑感；拖动过程需要有精心设计的动画反馈，包括跟手镜像、原位幽灵、落点提示和“后面的双胞胎阴影”，不能只是基础拖拽和静态样式调整。

用户特别强调布局必须合理、组件必须细分、注释和逻辑必须清晰、交互必须简单一目了然。可拖拽区域在鼠标 hover 时必须有明显反馈，例如拖拽图标、手柄、背景/边框变化或鼠标样式变化，不能让用户猜测哪里可以操作。

字段相关配置优先采用飞书多维表格风格：属性面板外层展示摘要行（如“展示字段 + N 个字段 + 设置图标”），点击设置后在浮层中展示字段行；字段行应包含拖拽手柄、字段类型图标、字段名/编码和显示/隐藏等图标按钮，避免把大量开关或字段列表直接堆在属性面板中。

## 5. 首页社区入口与登录页动效偏好

**记录日期**: 2026-06-28

登录页需要优先保证低端设备流畅，不要添加无业务价值的持续动画、扫光、流光边框、重滤镜或大面积模糊效果。首页可以放社区运营入口，但二维码区域必须明显、可点击放大；涉及收款/打赏/维护支持时，文案要委婉，优先使用“支持维护”“请维护者喝杯咖啡”“随心支持”等表达，避免硬性催付感。

登录页减少动效后不能退化成普通表单页。需要用静态主视觉、产品定位、能力矩阵、信任信息和更强的空间层次体现专业感；专业感优先来自信息架构和视觉结构，而不是持续动画。

用户对登录页信息密度敏感：右侧登录区不要堆“安全登录、租户隔离、权限审计、会话保护”等弱价值文案，尽量少用英文。桌面端更偏好左侧产品视觉大、右侧登录表单小的布局；小屏下优先隐藏左侧视觉，保持登录表单紧凑并允许竖向滚动。

## 6. 流程设计器配置偏好

**记录日期**: 2026-06-28

流程设计器必须优先站在业务人员视角设计配置项。审批分支、驳回、退回、会签、节点表单权限等高频配置默认用“选择/开关/向导/业务文案”完成，不能把 `${approvalResult == 'reject'}`、SPEL 或脚本表达式作为普通用户主入口。表达式能力可以保留，但应放在“高级配置”里，作为开发者兜底。

## 7. 平台能力开发偏好

**记录日期**: 2026-07-02

用户明确要求低代码应用补能力时必须做平台级通用功能，不要只针对某一个业务原型或单一需求硬编码。采购仓储、合同财务、人事、CRM 等只能作为验收场景，平台服务、接口、表结构和前端组件命名都应按通用能力抽象。

涉及较大能力建设时必须按 SDD 方式推进：先在 `code-copilot/changes/[变更名]/` 创建 `spec.md`、`tasks.md`、`test-spec.md`、`execution-log.md`，确认范围后再进入编码。

## 8. 应用中心概览与设计页交互偏好

**记录日期**: 2026-07-05

应用中心概览页左侧业务域需要保留树形层级、独立滚动和顶部“新建业务域”入口，宽度不能过窄。用户倾向于从概览页点击业务单元设计或访问入口预览时新开浏览器页签，让设计器或运行页面独立占用空间，避免概览页左侧业务域导航挤占画布。

## 9. Agent Skill 目录偏好

**记录日期**: 2026-07-07

Forge 项目级 Skill 统一识别并维护在 `.agents/skills/` 目录，项目规范不要放到 `superpowers/`。如果某些 Agent 默认查找 `.agent/skills/`，应在适配层映射到仓库已有的 `.agents/skills/`，不要在仓库内复制两套 Skill。

## 10. 企业配置页视觉偏好

**记录日期**: 2026-07-11

供应商配置、系统设置等企业后台页面应优先采用克制的主从配置工作台：左侧紧凑列表，右侧详情/配置页签，使用清晰边框、状态和表单层级。不要堆叠大标题、统计卡、英文装饰标签、渐变背景、步骤引导或无业务价值的视觉元素；参考成熟云平台控制台，信息直给、操作集中、不过度设计。

## 11. Forge AI 中枢联调分工

**记录日期**: 2026-07-12

Forge AI 中枢的真实 Flyway、Admin/Flow 服务启动、MCP Streamable HTTP 客户端联调和端到端业务验收由用户自行执行。后续 AI 会话优先负责 Proposal、代码实现、自动化测试和静态/聚合构建验证；除非用户再次明确授权，不自动启动真实服务、不执行会改动数据库或流程运行态的全链路联调，也不将未由用户回填的 E2E 结果表述为已通过。

## 12. 低代码开发工作台以数据库表为可见锚点

**记录日期**: 2026-07-13

用户明确反馈，低代码开发者进入业务对象设计时需要先看见数据库表及字段结构，不能把表名、列名、数据源和数据库同步状态长期藏在“高级配置”里。表结构、表单设计、列表/详情设计、按钮与动作、JS/CSS 增强、Java/服务端扩展、发布与历史应围绕同一个业务对象集中组织，减少在多个菜单和属性面板之间寻找配置的成本。

该偏好不等于取消业务对象和表单优先能力：普通业务用户仍可使用业务语言和拖拽表单；开发者视图则应默认展示“业务字段 ↔ 字段编码 ↔ 数据库列”的映射，并提供明确的数据库变更预览、同步确认和扩展治理入口。后续低代码信息架构优先参考成熟表驱动工作台的集中式体验，但不得照搬任意 SQL/Java 在线执行等高风险机制。

## 13. Forge 页面设计不使用 ui-ux-pro-max

**记录日期**: 2026-07-13

用户明确要求 Forge 页面分析、设计和改版不要使用 `ui-ux-pro-max` Skill，认为该 Skill 生成的页面视觉效果过于模板化且不符合当前产品审美。后续应直接结合 Forge 真实业务结构、现有组件规范和成熟企业控制台案例进行判断；除非用户以后主动撤销该要求，否则不要再次启用该 Skill。

## 14. 应用中心主题、滚动与发布入口偏好

**记录日期**: 2026-07-14

应用中心左侧业务域不得使用独立绿色体系，必须跟随 Forge 当前明暗主题和用户主色；业务域树需要在固定工作区内独立纵向滚动。右侧应用列表不要重复堆“全部业务域、应用总览、说明文案”等标题内容，筛选和主操作应直接可见。发布应用属于高频关键动作，需要在应用工作台顶部提供显眼主入口，不能只藏在左侧“发布历史”分区中。

## 15. 下载代码必须自动跟随低代码协议演进

**记录日期**: 2026-07-15

用户要求应用管理下载的代码与低代码 JSON 配置完全对应，单表、左树右表、主子表以及后续新增的低代码能力不能由多个下载入口分别维护生成分支。前端应复用在线低代码解释器，后端应进入统一静态协议编译器并完整携带协议；共享解释器或静态编译规则升级后重新下载即可适配，禁止静默忽略未知协议字段或只保证当前几个示例页面。

补充确认：前端继续复用在线低代码解释器；下载后端必须生成普通 MyBatis-Plus Service、Mapper 和 Mapper XML，不能让业务 Controller 统一依赖 `DynamicCrudService`。用户需要能直接修改复杂查询和复杂新增逻辑，并通过生成器永不覆盖的业务扩展实现持续二次开发。新增后端低代码能力应进入统一静态编译器/贡献器，所有下载入口重新生成后自动适配。

## 16. 下载源码不生成无意义注解并提供高价值工程设置

**记录日期**: 2026-07-15

用户要求未配置脱敏的实体字段不能生成 `@Desensitize(type = DesensitizeType.NONE)`，实体也不应保留无用 import。下载设置需要支持业务类名前缀、物理表前缀剥离、前后端输出目录和生成范围等真实工程落位选项；类名前缀必须统一影响 Entity、DTO、Mapper、Service、Controller 和关联对象，不能只改实体模板。框架固定的 Service/Mapper 后缀、基础实体和注解约定不应无边界开放。

## 17. 复杂结构化配置优先使用全屏工作台

**记录日期**: 2026-07-16

用户明确反馈，包含基础信息、可排序明细、高级参数和实时预览的结构化配置不适合放在侧边抽屉中。此类页面应从列表进入同路由或独立路由的全屏工作台，主要操作集中在顶部，明细末尾操作必须固定可见；抽屉只用于字段较少、单一职责的轻量编辑。

## 18. 明细行的关联映射使用局部弹窗

**记录日期**: 2026-07-17

当可排序明细行需要配置“对象 → 字段”、“资源 → 属性”等多级关联时，入口应跟随当前行，并使用局部弹窗完成选择。不要把关联对象选择器放在表格顶部或远离当前行的基础信息区，否则用户滚动到目标行后看不到入口。弹窗打开和取消不应修改草稿，只有确认才原子应用映射结果。

## 19. 低代码普通用户只使用表单语言

**记录日期**: 2026-07-28

用户明确要求低代码普通主路径只暴露“页面、表单、数据存储”等直观概念。创建数据页面后应直接设计并保存表单，由系统自动准备内部业务对象和数据绑定；不能要求用户再理解业务对象、主对象、数据源或对象角色，也不能连续打开数据对象抽屉和对象创建抽屉。

业务对象、已有对象复用、数据库表导入、数据源切换和对象角色继续保留，但统一归入高级数据设置，供开发者或复杂场景使用。普通表单保存后，系统应自动完成受控数据表创建或安全字段追加，只有数据存储真实可用后才提示准备完成；对象和应用发布仍保持独立。

## 20. 低代码技术编码默认由系统生成

**记录日期**: 2026-07-28

用户不应在新建低代码应用、表单数据存储等普通路径中手工理解和维护应用编码、模型编码等技术标识。系统应根据业务上下文自动生成合法且唯一的稳定编码，并在需要固定路由或外部对接时把可选覆盖入口放入高级设置；创建完成后的跳转和绑定必须使用后端最终落库值。