219 篇博文 含有标签「iCoding」

通过AI写脚本​

主要全量测试，集成测试，逐步提高 AI 编写测试；

通过测试用列编写脚本​

• 提示语：

/opsx-explore 硬件履约 e2e 测试脚本编写 请按照这个@硬件履约_测试用例1.1.md ，编写e2e 测试脚本,编写技术请参考: https://playwright.net.cn/docs e2e 测试脚本编写路径：yunfun-ui-admin-vben/apps/web-antd/e2e

在需求中分析测试用例（TDD）​

• 提示语：

/opsx-explore 硬件履约 @docs/订单管理/硬件履约需求设计文档.md 编写技术请参考: https://playwright.net.cn/docs，e2e 测试脚本编写路径：yunfun-ui-admin-vben/apps/web-antd/e2e

用他们设计的智能体编写测试脚本 (效果不好)​

https://playwright.net.cn/docs/test-agents

定时任务​

每天晚上跑全量测试脚本，如果有 bug，先 AI 修复一版，再让人工确认后提交；

报告可以推送到前端公共库；或者 netlify;

人工生成​

主要为了复现 bug，精细化测试，补充全量测试脚本；

文档：https://playwright.net.cn/docs/codegen-intro 作业目录：e2e

配置说明​

• fieldName： 字段必须是字符串，会塞入 json 格式的内容；
• 必须搭配国家/地区（customerCountry）使用；

使用说明​

模态框交互的详细地址组件​

• 组件代码路径：yunfun-ui-admin-vben/apps/web-antd/src/views/crm/customer/components/DetailByAddressFormat.vue

form-data.ts/data.ts 配置如下：

    {
      fieldName: 'detailByAddressFormat',
      label: $t('web.crmCustomer.create.form.detailByAddressFormat', {
        defaultValue: '地址格式的地址',
      }),
      component: 'DetailByAddressFormat',
      componentProps: {
        countryCode: undefined,
      },
      dependencies: {
        triggerFields: ['customerCountry'],
        show: (values: any) => !!(values.customerCountry ?? '').trim(),
        componentProps: (values: any) => ({
          countryCode: (values.customerCountry ?? '').trim() || undefined,
        }),
        rules: () => z.string().optional(),
      },
      defaultValue: undefined,
      rules: z.string().optional(),
      formItemClass: 'col-span-2',
    }

平铺详细地址组件​

• 组件代码路径：yunfun-ui-admin-vben/apps/web-antd/src/views/crm/customer/components/DetailByAddressFormatFlat.vue

form-data.ts/data.ts 配置如下：

  {
    fieldName: 'detailByAddressFormatFlat',
    component: 'DetailByAddressFormatFlat',
    componentProps: {
      countryCode: undefined,
    },
    dependencies: {
      triggerFields: ['customerCountry'],
      show: (values: any) => !!(values.customerCountry ?? '').trim(),
      componentProps: (values: any) => ({
        countryCode: (values.customerCountry ?? '').trim() || undefined,
      }),
      rules: () => z.string().optional(),
    },
    labelWidth: 0, // 这样可以对齐排版
    defaultValue: undefined,
    rules: z.string().optional(),
    formItemClass: 'col-span-2',
  },

相关解析函数​

function parseDetailByAddressFormatValue(raw: unknown): null | {
  components?: {
    adminDiv?: string;
    city?: string;
    postalCode?: string;
  };
  fullText?: string;
} {
  if (typeof raw !== 'string' || !raw.trim()) return null;
  try {
    const parsed = JSON.parse(raw);
    if (!parsed || typeof parsed !== 'object') return null;
    return parsed as {
      components?: { adminDiv?: string; city?: string; postalCode?: string };
      fullText?: string;
    };
  } catch {
    return null;
  }
}

function mergeDetailedAddressMl(
  fullText: string | undefined,
  currentMl: Record<string, string>,
) {
  const next = { ...(currentMl || {}) } as Record<string, string>;
  const zh = (fullText ?? '').trim();
  if (zh) {
    next['zh-CN'] = zh;
  }
  return next;
}

演示说明​

• 页面：http://22.50.5.181:5666//#/crm/customer/address-debug
• 演示代码： yunfun-ui-admin-vben/apps/web-antd/src/views/crm/customer/address-debug.vue

表单使用​

• 必须跟着一个国家选择器
• 联动规则：
  • 当国家选择器值变化时，联动组件的 label 值会变化（如果接口有返回该国家的行政区名称的话），如果没有返回则显示默认文案「行政区」。
  • 当国家选择器有值时，联动组件必填；当国家选择器无值时，联动组件非必填。
• 联动组件的 options 由接口返回，接口参数为国家选择器的值，接口返回的 options 中包含 label 和 value 两个字段。
• 联动组件的 label 默认文案为「行政区」，可自定义文案。

 {
      fieldName: 'customerCountry',
      label: $t('web.crmCustomer.create.form.customerCountry', {
        defaultValue: '注册地国家/地区',
      }),
      component: 'ApiSelect',
      componentProps: {
        api: async () => {
          const countries = await getSimpleCountryList();
          return (countries || []).map((c) => ({
            label: `${c.text} (${c.countryCode})`,
            value: c.countryCode,
          }));
        },
        labelField: 'label',
        valueField: 'value',
        placeholder: $t(
          'web.crmCustomer.create.form.placeholder.selectCustomerCountry',
          { defaultValue: '请选择注册地国家/地区' },
        ),
        showSearch: true,
        optionFilterProp: 'label',
        getPopupContainer: getSelectPopupContainer,
      },
      defaultValue: undefined,
      rules: z
        .string({
          required_error: $t(
            'web.crmCustomer.create.form.validation.customerCountryRequired',
            { defaultValue: '注册地国家/地区不能为空' },
          ),
          invalid_type_error: $t(
            'web.crmCustomer.create.form.validation.customerCountryRequired',
            { defaultValue: '注册地国家/地区不能为空' },
          ),
        })
        .trim()
        .min(
          1,
          $t('web.crmCustomer.create.form.validation.customerCountryRequired', {
            defaultValue: '注册地国家/地区不能为空',
          }),
        ),
      formItemClass: 'col-span-1',
    },
    {
      fieldName: 'adminDiv',
      label: getAdminDivDefaultName(),
      component: 'AdminDivSelector',
      componentProps: {
        countryCode: undefined,
      },
      dependencies: {
        triggerFields: ['customerCountry'],
        show: (values: any) => !!(values.customerCountry ?? '').trim(),
        trigger: async (values: any, actions: any) => {
          const countryCode = (values?.customerCountry ?? '').trim();
          const locale = preferences.app.locale || 'zh-CN';
          const nextLabel = countryCode
            ? (
                await getAdminDivDisplayName({
                  countryCode,
                  locale,
                })
              )?.displayName || getAdminDivDefaultName()
            : getAdminDivDefaultName();

          const currentSchema = actions?.state?.schema ?? [];
          const currentLabel = currentSchema.find(
            (item: any) => item?.fieldName === 'adminDiv',
          )?.label;

          // 仅在文案变化时更新，避免重复 setState 触发联动抖动
          if (
            typeof currentLabel === 'string' &&
            currentLabel.trim() === nextLabel.trim()
          ) {
            return;
          }

          actions?.updateSchema?.([
            {
              fieldName: 'adminDiv',
              label: nextLabel,
            },
          ]);
        },
        componentProps: (values: any) => ({
          countryCode: (values.customerCountry ?? '').trim() || undefined,
        }),
        rules: (values: any) => {
          // 提交时在 create.vue 中做显式校验，避免国家切换时即时触发必填报错
          return z.string().optional();
        },
      },
      defaultValue: undefined,
      rules: z.string().optional(),
      formItemClass: 'col-span-1',
    },

表单详情使用​

行政区的 code，拼装好传到接口，后端去查，然后把显示名称组织好返回前端 ，需要加个这样的接口，根据请求的语言，返回对应的内容

我来搜索关于 OpenSpec 和 Superpowers 的相关信息。Superpowers 可能指的是 Superpowers.js（JavaScript 解析器库）或其他相关技术。 这两个项目代表了 AI 辅助编程领域的两种截然不同的技术路径，它们并非竞品关系，而是分层协作的"兄弟俩" ：

核心定位对比​

OpenSpec：规范驱动的变更治理​

由 Fission AI 开发，核心理念是**"先写规范，再写代码"**，通过 Delta 机制管理增量变更 。

核心特性：

• 棕地优先（Brownfield-first）：专为改造现有代码库设计，分离 openspec/specs/（当前事实）和 openspec/changes/（提案变更）
• Delta 规范：用 ADDED/MODIFIED/REMOVED 标记追踪增量，而非重写全部规范
• 四阶段工作流：Draft Proposal → Review → Apply → Archive
• 多工具支持：兼容 Claude Code、Cursor、GitHub Copilot 等 20+ 种 AI 工具
• 零依赖：MIT 开源，无需 API 密钥

适用场景：需求复杂、边界不清的老项目改造；需要长期维护、严格架构规范、强调团队协作的大型项目 。

Superpowers：流程强制的执行质量保障​

由 Obra 开发，核心理念是**"流程即法律"**，通过不可跳过的"技能"约束 AI 行为，强制遵循 TDD、Code Review 等最佳实践 。

核心特性：

• 强制技能调用：brainstorming → writing-plans → test-driven-development → code-review → finishing-a-development-branch
• TDD 强制：必须遵循 Red-Green-Refactor 循环，即使是修小 Bug 也会触发全套流程
• 任务细化与并发：自动拆分任务粒度，决定哪些适合并行推进
• 系统化调试：systematic-debugging 技能避免"胡试"式调 Bug
• 验证与收尾纪律：verification-before-completion 确保代码真正跑过验证

适用场景：从 0 到 1 的需求探索；对代码质量、测试覆盖有极高要求的项目；需要养成良好编码习惯的新手 。

关键差异：不是竞品，是分层互补​

一句话总结：

OpenSpec 负责"写清楚"，Superpowers 负责"做干净"

组合使用：企业级 AI 编码工作流​

真正复杂的项目往往需要两者配合 ：

需求与变更对齐      → OpenSpec（/opsx:new → /opsx:ff）
执行质量控制        → Superpowers（brainstorming → TDD → review）
团队协作与长期沉淀   → OpenSpec + Superpowers 共同补位

典型组合场景：

1. 老项目重构：先用 OpenSpec 对齐 change 的范围和设计，再用 Superpowers 保证实施质量
2. 中大型功能上线：OpenSpec 保证需求清楚，Superpowers 保证测试、验证不掉链子
3. 又怕跑偏又怕返工：OpenSpec 稳住方向，Superpowers 稳住执行

选择建议​

正如社区开发者所言：它们不是"谁更好"的关系，而是**"变更治理"与"执行质量"两个维度的互补** 。

日期：2025-02-09
状态：已确认

第一节：目标与范围​

目标

• 系统侧：在现有芋道后台中增加「技能包」管理能力，运营/管理员可创建、编辑、发布技能包（业务数据落库，供 AI Agent 或其它业务消费）。
• 开发侧：在 Cursor 中提供一个「创建技能包（管理模块）」的 skill，能像 biz-crud-create-page 一样一键生成「技能包」的整条管理链路（表结构 + 字典 + 菜单 + 后端 CRUD + 前端列表/表单/详情），并遵循项目既有规范。

范围

• 技能包在系统内视为一种业务实体：有名称、编码、描述、状态（草稿/已发布等）、版本、所属分类等可配置字段；具体字段在第二节数据模型中确定。
• 管理能力：列表（含筛选）、新增、编辑、删除、发布/下架；详情页可展示包内「技能」列表或配置摘要（首期做简单列表，复杂编排可后期扩展）。
• 生成器 skill：只负责生成「技能包管理」这条 CRUD 链路（含一个技能包表及必要字典/菜单），不生成「包内单个 skill 的 SKILL.md 文件」；若以后需要「从管理页导出为 Cursor skill 目录」，再单独做导出功能。
• 消费方式本期只做数据就绪：表与 API 先有，供前端或内部调用；若已有或计划有 Agent 服务，可直接读同一套 API。

不包含（YAGNI）

• 包内技能的在线编辑器、版本 diff、审批流、多租户隔离（除非现有项目已强依赖租户）。
• 技能包市场、分享、权限到「包内单条技能」的细粒度控制。

成功标准

• 用 skill 生成一遍后，能在后台看到技能包菜单，完成列表/增删改/发布状态切换。
• 生成物符合现有数据库、后端、前端规则（与 lead/source 或 lead/personal 风格一致）。

第二节：数据模型与字典​

主表 ai_skill_package

• 与现有规范一致：主键 id（雪花）、creator/create_time/updater/update_time/deleted、tenant_id（多租户）。
• 业务字段：name（名称）、code（编码，租户内唯一，用于 API/导出）、description（描述，VARCHAR(500) 或 TEXT）、status（状态，见下）、sort（排序，INT 默认 0）、content（TEXT，可选，存包内技能摘要或 JSON，后续可扩展）。
• 索引：uk_ai_skill_package_code_tenant (code, tenant_id, deleted)，idx_ai_skill_package_status (status)，idx_ai_skill_package_sort (sort)。

字典

• skill_package_status：草稿（DRAFT）、已发布（PUBLISHED）、已下架（OFFLINE）。列表筛选、详情、发布/下架操作均用该字典。
• （可选）skill_package_category：如「业务生成」「Agent 技能」等，便于后续分类筛选；若首期不做分类，可不建该字典。

包内技能（首期从简）

• 不单独建「技能项」表，用主表 content 存一段文本或 JSON 即可（例如技能名称列表 + 简要说明），详情页只读展示。若后续需要逐条增删改「包内技能」，再增加 ai_skill_package_item 表与前后端。

菜单与权限

• 一级菜单（示例）：「AI 技能」或放在现有某父级下，path 如 /ai/skill-package。
• 二级：技能包管理，permission 前缀 ai:skill-package:query/create/update/delete，并可加 ai:skill-package:publish 控制发布/下架。

第三节：后端与前端实现要点​

后端

• 模块：放在现有 yudao-module-ai，若当前只有 pom，则在该模块下按规范建包：controller.admin、dal.dataobject.skill、dal.mysql.skill、service.skill、convert.skill、controller.admin.vo.skill（PageReqVO/RespVO/SaveReqVO，按需 SimpleRespVO）。
• 接口约定：Base URL /admin-api/ai/skill-package。提供：分页查询 getPage、详情 get、新增 create、修改 update、删除 delete、发布 publish、下架 offline。权限标识：ai:skill-package:query/create/update/delete，发布/下架可用 ai:skill-package:publish 或复用 update。
• 实现要点：DO 继承 TenantBaseDO，表名 ai_skill_package。发布/下架即把 status 置为 PUBLISHED/OFFLINE 并做幂等与状态校验（如仅草稿可发布、仅已发布可下架）。错误码在 yudao-module-ai 的 ErrorCodeConstants 中新增，Controller 用 @PreAuthorize 与现有风格一致。

前端

• 路由：在 router/routes/modules 下新增 ai.ts（或并入已有 AI 路由），path 如 /ai/skill-package，组件 ai/skill-package/index；列表、新增/编辑、详情对应同一模块下的 index、create、edit、detail。
• 列表页：Page + useVbenVxeGrid，查询项：名称（Input）、编码（Input）、状态（Select，DICT_TYPE.skill_package_status）。表格列：名称、编码、状态（CellDict）、排序、更新时间、操作（编辑/删除/发布/下架，按状态显隐）。API 与后端分页约定一致（pageNo、pageSize、表单条件、排序）。
• 表单（新增/编辑）：名称、编码、描述、排序、状态（草稿时可选）、content（可选，Textarea）。编码新增时必填，编辑时只读或禁用。校验：编码格式、名称非空。
• 详情页：只读展示上述字段；若有 content，以只读区块或简单 JSON/文本展示「包内技能」摘要。
• 发布/下架：列表操作列按钮，调用 publish/offline 接口后刷新列表；可加二次确认（如「确认发布？」）。

与现有风格对齐

• 后端 VO 命名、分页参数、统一返回与 CRM 模块一致；前端 data.ts 中 formSchema/columns、TableAction、权限 ai:skill-package:xxx、i18n key 前缀统一（如 ai.skillPackage.xxx）。组件与数据源遵守 .cursor/skills/biz-crud-create-page/component-data-mapping.md（本业务若无特殊下拉可仅用字典）。

第四节：生成器 Skill 设计​

定位与触发

• 新建项目内 skill：.cursor/skills/create-skill-package-module/，内含 SKILL.md。触发场景：用户说「生成技能包管理模块」「创建技能包管理页」「按 createPage 风格做技能包」等时，Agent 优先使用该 skill。
• 与 biz-crud-create-page 的关系：不替代，复用其规则与参考。本 skill 只针对「技能包」这一固定业务，产出表名、实体名、模块名、菜单/权限前缀、字典类型等均写死在 skill 内，无需用户再走「查询项→表格→功能清单」多步交互；若以后要支持「自定义实体名的技能包」，再考虑引入类似 create-page 的交互。

生成顺序（与 create-page 一致，严禁颠倒）

1. SQL：sql/mysql/ 下新增 ai_skill_package.sql（建表）、ai_skill_package_dict.sql（skill_package_status 等字典，幂等）、ai_skill_package_menu.sql（AI 技能 / 技能包管理菜单及 ai:skill-package:query 等按钮权限，含 role_id=1 的 system_role_menu）。
2. 后端：在 yudao-module-ai 中生成 DO（TenantBaseDO）→ Mapper → Service 接口与 Impl → Controller（/admin-api/ai/skill-package）→ VO（PageReqVO、RespVO、SaveReqVO）；ErrorCodeConstants 中新增错误码；发布/下架在 Service 内做状态流转与校验。
3. 前端：router/routes/modules/ai.ts 中注册列表与 detail/create/edit 路由；views/ai/skill-package/ 下 index.vue、data.ts、create.vue、edit.vue、detail.vue（弹窗 CRUD 则用 modules/form.vue）；api/ai/skill-package/index.ts；i18n 键与菜单名称一致。

Skill 文档必须写清的内容

• 本模块固定参数表：表名 ai_skill_package、模块名 ai、实体名 skillPackage（前端）、权限前缀 ai:skill-package、字典类型 skill_package_status、参考实现路径（可与本设计文档互相引用）。
• 必读规则：.cursor/rules/backend/database.mdc、backend-project-structure.mdc、.cursor/rules/frontend/biz-crud-page-standard.mdc；参考实现指向「技能包」生成后的代码或现有 lead/source 的目录结构说明。
• 生成后校验：要求执行 node .cursor/skills/biz-crud-create-page/scripts/validate-page.mjs ai skill_package --backend（若 validate-page 支持 ai 模块）；或在本 skill 下提供专用 validate-skill-package.mjs，检查 SQL、菜单、路由、views、API、后端 DO/Controller 是否存在且符合约定。

可选

• 本 skill 的 reference.md 中列出「技能包管理」字段与接口清单，便于 Agent 一次生成完整；scripts/ 下仅保留校验脚本，不提供通用代码生成引擎。

第五节：错误处理与验收​

错误处理

• 后端：编码重复返回 400 及明确错误码；发布/下架状态不合法（如对已下架再下架）返回 400 并提示当前状态；删除前可做关联校验（若未来有包内技能表则先判空）。
• 前端：接口失败用项目统一提示；列表加载失败可重试或空状态提示。
• 生成器：校验脚本以非 0 退出并打印缺失项（如「缺少 ai_skill_package_menu.sql」），Agent 按提示补全后重新运行直至通过。

验收标准

• 执行 skill 生成一遍后：执行 SQL、启动后端与前端，能在「AI 技能」下看到「技能包管理」，完成列表筛选、新增、编辑、删除、发布、下架、详情查看；数据落库且状态正确。
• 生成代码通过项目既有 Lint/编译；菜单与权限与设计一致。

总体思路​

目标就是两件事：

1. 减少「自动带进来但其实用不到」的上下文
2. 减少「每次对话需要重复扫描的大文件/大结构」

一、项目结构 / 忽略规则层面​

扩充 .cursorignore​

把"永远不需要读"的东西都排掉（你已经忽略了 node_modules 和 backend/target，不错）：

可以考虑再加：

# 编译产物
frontend/web/dist
frontend/app/android
frontend/app/ios
*.log

# 大型静态资源（如果你几乎不会问这些）
**/*.png
**/*.jpg
**/*.mp4

# 测试快照、coverage
**/__snapshots__/**
coverage/**

文档/规范集中到少数文件​

把"项目规范、工作流"集中到 CLAUDE.md + 少数 docs/plans/*.md，避免在很多散文件里重复长说明，每次都要被模型扫一遍。

二、Cursor / Claude 配置层面（减少自动上下文）​

这些不需要改代码，只是你使用 Cursor 时的习惯：

少用/慎用「自动附加大 Skill」​

这次聊天你手动附了 brainstorming，它本身字数不多还好。但类似 superpowers 的大 skill，如果不是每次都需要，可以：

• 真要用时再贴；
• 或者把你自己常用的 1–2 个写成更短版 Skill。

控制自动附加的文件数量与大小​

在实际使用中：

• 问问题前，尽量只打开/高亮与你问题最相关的 1–2 个文件；
• Cursor 会优先把"当前打开文件 + 最近文件"丢给模型，开太多大文件会明显增大 token。

分阶段问问题，而不是一次性贴超长 diff / 多个大文件​

比如 App 导航、某一模块的 UI、某个 API 层，尽量拆开问。

• 对"结构性问题"先问高层（架构、目录），再 drill down 到具体实现。

三、日常使用习惯层面（你和我的交互方式）​

这些是你现在就可以改变的操作方式，会立刻省 token：

尽量引用"路径 + 行号"而不是整文件粘贴​

在 Cursor 里说：

看下 frontend/app/src/navigation/index.tsx 的路由结构

让我自己用只读工具去读，比你复制整个文件到聊天里便宜很多。

大文件只问一个点​

不要说"帮我 review 整个线索模块"，而是：

• 先："帮我理解 ClueOrigin 这块的筛选逻辑"
• 再："再看下它和 ClueMain 的关系"

这样每次只需要一小部分上下文。

控制回答详细程度​

像你现在这样不要求超长讲解，其实就已经在省 token 了；如果后面你觉得"回答太长"，可以直说：

"只给结论和关键代码引用，不要铺垫"

我会按你要求压缩输出。

四、如果你愿意再进阶一点的做法​

给 Cursor/Claude 写更短的 RULE / Skill​

例如专门为这个项目写一个 RULE.md：

• 只说明技术栈、目录结构、OpenSpec 工作流的"精简版"；
• 把长篇解释放在仓库的 docs/，需要时你再手动提示我去看。

把「经常要看的大文档」拆成多个小文件​

比如一个 2000 行的 spec，可以拆成按模块的 3–4 个； 这样每次只会读到相关那一份。

简单总结​

减少 token 的核心就是"缩小自动上下文 + 精准地引用需要看的文件/片段"。

如果你愿意，我可以帮你草拟一版更"节省 token"风格的 .cursorignore 和一个精简版的 RULE 模板，你自己手动去改就行。

Tailscale 是一种基于 WireGuard 协议构建的**零配置虚拟专用网络（VPN）**解决方案，专注于为个人用户和企业提供简单、安全的网络连接。

核心功能​

典型使用场景​

• 远程访问内网服务：从外网安全访问家中的 NAS、Raspberry Pi、服务器等
• 跨地域团队协作：将分布在全球的办公网络和员工设备组成统一网络
• 开发测试环境：快速搭建安全的开发/测试网络，模拟生产环境
• IoT 设备管理：统一管理分散的智能设备，无需公网 IP

技术原理​

1. 基于 WireGuard：使用现代加密协议，性能优于传统 VPN（如 OpenVPN、IPsec）
2. Coordination Server：Tailscale 的控制平面仅负责密钥分发和 NAT 穿透协调
3. DERP Relay：当 P2P 直连失败时，通过中继服务器转发流量（加密）
4. NAT Traversal：自动处理各种 NAT 环境，最大化实现直连

定价模式​

• 个人免费版：最多 20 个设备，基础功能齐全
• 个人 Pro：$4/月，无限设备 + 子网路由
• Team/Business：按用户收费，提供 SSO、审计日志、API 等高级功能

与同类产品对比​

如果你是想搭建一个完全私有的 Tailscale 网络（不依赖 Tailscale 官方服务器），可以了解 Headscale —— 它是 Tailscale 控制服务器的开源实现，支持完全自托管。

Web → App 基于 OpenSpec 的开发流程​

创建日期： 2026-02-04
适用范围： 线索 / 客户等 CRM 业务，从 Web 需求演进到 App 实现

1. 流程总览​

从一个功能/改动诞生，到 App 上线闭环，推荐遵循下面的主流程：

1. 需求进入（通常先在 Web 上提出或实现）
2. 统一业务到主 Spec（openspec/specs/*）
3. 评估是否需要 App 跟进
4. 为 App 创建 / 更新对应的 OpenSpec change（openspec/changes/app-*）
5. 在 change 的 design.md 中完成 App UX 设计（信息架构 + 页面流程 + 布局）
6. 从 design.md 拆分实施任务到 tasks.md
7. 按任务开发、测试 App，并持续回填 Spec / 设计 / 任务
8. 使用 openspec verify 验证，再 archive 完成变更归档

2. 需求进入 → 统一到主 Spec​

目标： 无论 Web 或 App，所有业务规则以 openspec/specs/* 为唯一真源。

• 当有新需求或 Web 行为变更时，先检查：
  • 当前业务是否已经有对应 Spec（例如：lead-pool、personal-leads、customer-conversion 等）。
  • Web 实际行为与 Spec 是否一致。
• 若不一致：
  • 创建一个小的业务同步 change（如 2026-02-xx-sync-lead-spec）。
  • 在该 change 中仅做两件事：
    • 修正/补充主 Spec：更新 openspec/specs/* 中的字段、状态流转、规则说明。
    • 记录原因：在 proposal.md / design.md 中说明“为什么要改 Spec（与历史实现的差异）”。

完成后，Web 与 App 后续均以更新后的主 Spec 为准。

3. 决定是否需要 App 跟进​

在业务 Spec 更新后，进行一次轻量评估：

• 该改动是否影响移动端的核心场景？
  • 例如：线索列表字段调整、转化规则变化、客户关键信息修改等。
• 评估结果：
  • 必须跟进：影响主流程或数据一致性，必须在 App 中同步。
  • 推荐跟进：改善体验，但不是硬性要求，可以合并到后续 App 迭代。
  • 暂不需要：仅 Web 端特有的桌面场景，可暂不做 App 支持。

当结论为“必须/推荐跟进”时，进入下一步，为 App 创建/更新 change。

4. 为 App 创建 / 更新 OpenSpec change​

命名建议：

• openspec/changes/app-<模块>-<目标>，例如：
  • app-lead-mobile-list（线索列表移动端版本）
  • app-customer-conversion-flow（客户转化流程）

proposal.md 建议内容：

• 背景： 关联哪些业务 Spec（链接到 openspec/specs/*）。
• 目标用户： 例如一线销售 / 经理。
• 业务目标： 希望这次在 App 上达成的业务效果（而非技术细节）。
• 范围边界： 这次 App 改动包含/不包含哪些屏幕和操作。

5. 在 design.md 中完成 App UX 设计（先设计再开发）​

design.md 是这条 Web → App 变更在 App 侧的“设计真源”，推荐固定结构如下：

5.1 关联主 Spec 与场景​

• 列出本次改动关联的业务 Spec：
  • 例如：[lead-pool](../../specs/lead-pool/spec.md)、[customer-conversion](../../specs/customer-conversion/spec.md)。
• 用 1–2 句话说明本次在 App 上解决的核心场景：
  • 如：“让销售在移动端快速筛选高意向线索并发起跟进/转化”。

5.2 信息架构（App IA）​

• 列出涉及的 App 屏幕及一句话职责，例如：
  • LeadListScreen：我的线索列表，帮助销售快速找到“现在最值得处理”的线索。
  • LeadDetailScreen：线索详情 + 跟进记录，集中展示决策所需信息。
  • LeadConvertScreen：转化流程，减少误操作，用最少步骤完成转客户。

5.3 用户流程（User Flow）​

• 用步骤方式描述从入口到完成任务的路径，例如：
  • 首页 → 点“线索”入口 → 线索列表 → 筛选 → 详情 → 新增跟进 → 转为客户。
• 对应线索/客户等核心流程可以只写 1–2 条“标准路径”，其余放到 tasks.md 验收里。

5.4 屏幕布局与组件粒度​

• 对关键屏幕（例如线索列表、线索详情）写到组件级：
  • 顶部搜索、快捷筛选 Chips、列表卡片的字段排布、底部主按钮等。
• 对次要屏幕可只写区块级：
  • 顶部标题区、中部表单区、底部操作区。
• 不要求画高保真，只需说明信息密度、主次层级与主要交互。

5.5 状态与反馈​

• 加载中、空数据、错误、权限不足时的表现：
  • 是否有 Skeleton 占位、空态文案、重试按钮等。
• 哪些操作需要 Toast，哪些需要确认弹窗。

5.6 与 Web 的 UX 对齐与差异​

• 明确哪些行为必须与 Web 一致（例如：校验规则、必填字段）。
• 明确为移动端刻意做的差异（例如：字段裁剪、操作合并到底部按钮栏）。

6. 从 design.md 拆分到 tasks.md​

tasks.md 用于驱动实施与测试，建议按以下维度拆分：

1. 屏幕与导航
   • 创建/调整相应的 Screen 与路由。
   • 配置 Tab / Stack 结构与入口位置。
2. 组件与状态
   • 列表卡片、详情块、过滤组件、表单等 UI 任务。
   • 本地 UI 状态（loading/error/selected item 等）。
3. API 与数据流
   • 调用哪些后端接口，如何与 shared API 连接。
   • 使用 Jotai / Zustand 管理哪些业务状态。
4. 验收与测试
   • 从 design.md 的用户流程中抽取手工验收用例。
   • 设计 e2e 场景（登录 → 打开模块 → 执行核心路径）。

开发以 tasks.md 为 TODO 清单执行，过程中有变更应回填：

• 业务规则问题 → 优先修改主 Spec（openspec/specs/*）。
• 只是 UX/实现细节微调 → 更新 design.md / tasks.md。

7. 开发、验证与归档​

7.1 开发与自检​

• 按 tasks.md 完成所有实现任务：
  • 屏幕/组件/导航/状态管理/API 调用。
• 在 App 项目中执行基础自检：
  • npx tsc --noEmit
  • yarn lint
  • 关键路径的手工走查。

7.2 使用 openspec verify​

• 在 verify 阶段对照以下内容逐条检查：
  • proposal.md 中的业务目标是否达成。
  • design.md 中的信息架构、流程、关键 UX 是否已实现。
  • tasks.md 中的实施任务与测试任务是否全部完成。
  • 与主 Spec 的行为是否保持一致，差异是否在设计中有记录。

7.3 archive 归档​

• 验证通过后执行归档，将 change 移入 openspec/changes/archive。
• 归档后的 change 就是这次 Web → App 能力同步的完整“变更记录”，便于后续审计与演进。

8. 推荐落地顺序（线索 / 客户试点）​

1. 选择一条业务（推荐：线索列表 + 线索详情 + 转化）。
2. 校准相关主 Spec（lead-pool、personal-leads、customer-conversion 等）。
3. 新建 openspec/changes/app-<lead-module> change。
4. 按本指南格式完善该 change 的 design.md 与 tasks.md。
5. 驱动一次完整的 App 实施与验收闭环。

完成这条试点后，可以将本文件作为团队在其他模块（待办、机会、Dashboard 等）的共用开发流程规范。

1. 整体架构示意 ┌─────────────────────────────────────────────────────────────────────────────────┐│ 云帆 CRM 技术架构 │├─────────────────────────────────────────────────────────────────────────────────┤│ ││ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││ │ Web (Vite) │ │ App (RN) │ │ 后端 (SB) │ ││ │ React 19 │ ──ajax─▶│ axios │ ──▶ │ context │ ││ │ Ant Design │ │ Jotai │ │ /api │ ││ └─────────────┘ └─────────────┘ └──────┬──────┘ ││ │ │ │ ││ │ baseUrl: /api │ │ ││ └────────────────────────┴────────────────────────┘ ││ │ ││ ┌─────────────┼─────────────┐ ││ ▼ ▼ ▼ ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ MySQL │ │ Redis │ │ RabbitMQ │ │ 存储/CDN │ ││ │ 8.0 │ │ 7 │ │ (可选?) │ │ 本地/OSS │ ││ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ││ │└─────────────────────────────────────────────────────────────────────────────────┘
2. 后端架构（Java + Spring Boot） 2.1 分层与职责 层 位置 职责 Controller controller/ REST 接口，参数校验，调用 Service Service service/ + impl/ 业务逻辑，事务边界 Mapper mapper/ MyBatis-Plus，单表/批量 Entity entity/ 表映射；DTO 在 dto/、common/ 下 Common common/ 缓存、安全、审计、消息、通知、存储、调度等 统一响应：Result（code / message / data / timestamp）。全局异常：GlobalExceptionHandler。 2.2 已做得不错的地方 分层清晰：Controller → Service → Mapper，DTO 与 Entity 分离。 统一出口：Result、全局异常、Knife4j 文档。 基础设施：Redis 缓存（枚举/国家/配置）、Druid 连接池与监控、MyBatis-Plus 分页与逻辑删除。 扩展模块：审计、GDPR、数据隔离（按国家）、消息（RabbitMQ）、通知（邮件/企微）、定时任务、存储抽象（本地/OSS）。 部署：docker-compose 含 MySQL、Redis、应用，环境变量清晰。 2.3 可优化点（架构层面） 点 现状 建议 API 版本与路径 大部分接口无版本（如 /api/lead-pool），仅 AiCrawlerSourceController 用 /api/v1/ai-crawler-sources 统一约定：要么全加 /api/v1/ 前缀，要么全不加，并文档化，便于以后做 v2 不破坏现有前端。 安全 SecurityConfig 当前 anyRequest().permitAll()，仅靠请求头 auth-token 若已上生产，建议在 Security 里显式配置需认证的路径、放行文档/健康检查等，避免“默认全放行”的误用。 RabbitMQ 与部署 代码里有 RabbitMQ 配置与消费者，但 docker-compose 未包含 RabbitMQ 要么在 docker-compose 中增加 RabbitMQ 服务，要么用 @ConditionalOnProperty 等让消息模块在未配置时不可用，避免本地/测试环境因连不上 MQ 启动失败。 MyBatis 二级缓存 application.yml 里 cache-enabled: false 保持关闭是稳妥的；若以后要开，需考虑多实例与 Redis 等集中缓存，避免本地缓存不一致。
3. 前端 Web 架构（React + Vite） 3.1 结构 入口：AppRouter 用 ~pages-config 生成路由，根级 Suspense + useRoutes。 请求：统一 axios 实例，baseUrl /api，请求头带 auth-token，拦截器处理 loading/成功/错误/取消。 页面：pages/ 下按业务分目录（lead-pool、personal-leads、todos、users 等），列表页多为「Form 筛 + Table 分页」。 配置：config-hoc（权限、标题、抽屉、弹窗）、menus、多环境 config。 3.2 可优化点 点 说明 路由懒加载 需确认 @ts-max/vite-plugin-pages-config 生成的路由是否按页面 React.lazy；若否，首屏会包含所有页面 chunk，可考虑按路由懒加载以减小首包。 请求缓存 未使用 React Query/SWR 等，重复进入同一列表会重复请求；可对只读列表/详情做短时缓存或 stale-while-revalidate，减轻后端压力、提升体验。 类型与接口 列表/详情类型多在各自 pages/xxx/types.ts；若后端有 OpenAPI/Knife4j 生成类型，可考虑统一生成前端类型，减少手写不一致。
4. App 架构（React Native） 4.1 结构 API：api/ 下按领域拆模块（todo、customer、clue、brand 等），client 统一请求。 状态：Jotai + Zustand，MMKV 持久化。 列表：FlashList；图片：fast-image。 导航：React Navigation v7 静态导航；大量 screens/ 与业务组件。 4.2 可优化点 点 说明 与后端对齐 App 的 api 模块（如 approval、contract、invoice）若与当前后端 controller 不完全对应，需确认是历史模块、多后端，还是待收敛；对齐后可减少重复与歧义。 共享类型 若 Web 与 App 共用同一套后端 API，可考虑把通用类型/接口定义放到 monorepo 公共包或从 OpenAPI 生成双端类型，避免两套定义漂移。
5. 跨端与一致性 维度 现状 可优化 认证 Web：auth-token 头；App：需看 authService 是否同一套 统一 token 存储、刷新、过期处理与错误码，便于双端体验一致。 API 契约 后端 Knife4j/OpenAPI，前端手写类型 用 OpenAPI 生成 TS 类型或 SDK，减少手写、保证与文档一致。 错误与多语言 后端统一异常、前端拦截器处理；i18n 各端自有 错误码与 key 统一约定，便于前端做统一错误文案与多语言映射。

整体设计思路很成熟：先设计后开发、TDD、AI 辅助、分层架构清晰、技术栈选型合理，尤其是前后端均有明确的目录与职责划分，工程化意识强。以下是我认为可以进一步增强的点（按优先级排序）：

1. 设计与需求阶段（最关键） 问题：目前流程偏“文档驱动”，但缺少“可验证”的设计输出。 建议改进：

需求文档增加可执行验收标准（类似 BDD 的 Given/When/Then） 接口设计先行：OpenAPI/Swagger 规范文件先落地，再联动前后端生成骨架（提升一致性） UI 设计到组件库：明确把 Figma/Google Stitch 的组件映射到 src/components/ui，形成“设计-代码”映射表 2) 测试策略（覆盖层面可以更系统化） 问题：测试说明较全，但缺少“测试金字塔”与覆盖标准 建议改进：

明确测试层级覆盖率要求（Unit 70%+ / Integration 30%+ / E2E 关键路径） 前端补充：组件快照测试 + 交互测试标准 后端补充：数据库迁移 + Repository 层集成测试 加入测试基线指标（如每个模块至少 X 条关键用例） 3) API 与契约治理（前后端协作效率核心） 建议改进：

引入 API Contract：例如 OpenAPI + 自动生成 TypeScript Client 确保 Response/Error Schema 统一，减少“前端猜字段” 约定分页、筛选、排序的统一格式（目前未明确） 4) 技术栈维持与演进策略 建议改进：

明确 依赖升级策略（如每季度升级 Node/React Native / Spring Boot） 关键基础库（如状态管理、UI组件、网络层）要明确“替换成本与治理原则” 5) AI 辅助流程可量化 建议改进：

增加 AI 产出校验指标（例如：自动生成代码必须通过 lint/test、覆盖率达标） 建议引入 Prompt 模版规范（特别是针对生成测试/接口/组件） 6) 数据与缓存策略 建议补充：

前端：离线策略、缓存过期、断网行为未描述 后端：Redis 缓存失效策略、热点数据处理方式 我对整体评分（主观） 架构合理性：9/10 工程可执行性：8/10 协作效率与质量保障：7.5/10（改进空间主要在契约、测试、AI流程量化） 如果你愿意，我可以帮你进一步完善以下内容之一：

输出一份完整的“前后端接口契约模板” 输出可直接使用的“测试策略与覆盖率指标” 整理成可执行的“AI辅助开发流程规范”文档 想先从哪一部分强化？

✅ 前后端接口契约模板（OpenAPI 3.1） 目标：统一字段、响应结构、分页规则、错误码与安全策略 适配你当前后端 Spring Boot + 前端 TS 项目

一、契约约定（必须遵守）

1. URL 规范 基础路径：/api 资源名使用复数名词：/users、/orders 查询条件用 query string：/users?status=active
2. 时间格式 全部使用 ISO 8601：2026-01-21T12:30:45+08:00
3. 统一响应结构

{
  "code": 0,
  "message": "success",
  "data": { },
  "traceId": "8f9a..."
}

4. 分页标准 参数：page（默认 1），pageSize（默认 20） 返回：

{
  "list": [],
  "page": 1,
  "pageSize": 20,
  "total": 128
}

5. 错误返回 所有错误走统一结构 HTTP 状态码区分错误类型（401/403/404/422/500） 二、OpenAPI 3.1 模板（可直接使用）

openapi: 3.1.0
info:
  title: AiDrive API Contract
  version: 1.0.0
  description: |
    前后端统一接口契约。所有接口返回统一结构。
servers:
  - url: /api
tags:
  - name: Auth
  - name: User
 
security:
  - bearerAuth: []
 
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
 
  parameters:
    Page:
      name: page
      in: query
      schema: { type: integer, minimum: 1, default: 1 }
    PageSize:
      name: pageSize
      in: query
      schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
    Sort:
      name: sort
      in: query
      description: "如: createdAt desc"
      schema: { type: string }
 
  schemas:
    ApiResponse:
      type: object
      required: [code, message, data, traceId]
      properties:
        code: { type: integer, description: "0=成功，非0=失败" }
        message: { type: string }
        data: {}
        traceId: { type: string }
 
    ErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                fieldErrors:
                  type: array
                  items:
                    type: object
                    properties:
                      field: { type: string }
                      message: { type: string }
 
    PageResult:
      type: object
      required: [list, page, pageSize, total]
      properties:
        list:
          type: array
          items: {}
        page: { type: integer }
        pageSize: { type: integer }
        total: { type: integer }
 
    User:
      type: object
      required: [id, username, name, role, createdAt]
      properties:
        id: { type: integer }
        username: { type: string }
        name: { type: string }
        role: { type: string, example: "ADMIN" }
        status: { type: string, example: "ACTIVE" }
        createdAt: { type: string, format: date-time }
 
    LoginRequest:
      type: object
      required: [username, password]
      properties:
        username: { type: string }
        password: { type: string }
 
    LoginResponse:
      type: object
      required: [token, expiresIn]
      properties:
        token: { type: string }
        expiresIn: { type: integer, description: "秒" }
 
    CreateUserRequest:
      type: object
      required: [username, name, role]
      properties:
        username: { type: string }
        name: { type: string }
        role: { type: string }
 
  responses:
    Unauthorized:
      description: 未登录/Token失效
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    Forbidden:
      description: 无权限
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    NotFound:
      description: 资源不存在
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    ValidationError:
      description: 参数校验失败
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
 
paths:
  /auth/login:
    post:
      tags: [Auth]
      summary: 用户登录
      security: []  # 登录接口不需要JWT
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LoginRequest' }
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data: { $ref: '#/components/schemas/LoginResponse' }
        '422': { $ref: '#/components/responses/ValidationError' }
 
  /users:
    get:
      tags: [User]
      summary: 用户分页列表
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Sort'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        allOf:
                          - $ref: '#/components/schemas/PageResult'
                          - type: object
                            properties:
                              list:
                                type: array
                                items: { $ref: '#/components/schemas/User' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
    post:
      tags: [User]
      summary: 创建用户
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateUserRequest' }
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data: { $ref: '#/components/schemas/User' }
        '422': { $ref: '#/components/responses/ValidationError' }
 
  /users/{id}:
    get:
      tags: [User]
      summary: 用户详情
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data: { $ref: '#/components/schemas/User' }
        '404': { $ref: '#/components/responses/NotFound' }

三、可选增强（建议补充） ✅ 错误码枚举表（与后端 ResultCode 对齐） ✅ 字段级校验规范（长度、格式、枚举） ✅ OpenAPI 自动生成 TS Client 推荐：openapi-generator-cli 或 openapi-typescript 如果你希望，我可以下一步帮你输出：

✅ “错误码规范与字段校验规范模板” ✅ “与 TypeScript Client 自动生成对接方案” ✅ “你现有后端 ResultCode 对应到 OpenAPI 的映射”

你要继续完善哪一块？

微信公众号​