@dev-workflow/skill 0.1.0

package/skills/execution/devFlow/domains/frontend/references/product-design-specs/fields-number-date.md

@@ -0,0 +1,106 @@
+# 数字、金额、时间、日期字段规范
+
+## 数字 / 金额
+
+### 适用范围
+
+- 金额、数量、利润率、税率、百分比、单价、合计等。
+
+### 录入方式
+
+- 手动输入。
+- 自动计算且可修改。
+- 默认值：无，或按规则自动计算。
+- 字符限制：仅支持数字字符、小数点 `.`、负号 `-`。
+- 大小限制：如有范围限制，超出范围的数值禁止输入，或处理成最大值/最小值。
+- 负数：未特殊说明时，一般不支持输入负数。
+
+### 格式化
+
+- 金额：一般保留 2 位小数，显示千分符，例如 `123,123,123.12`。
+- 税率：一般保留 2 位小数，显示百分比，例如 `6%`。
+- 其他率：一般保留 4 位小数，显示百分比，例如 `23.12%`。
+- 小数位数一般不超过 6 位。
+- 千分符和百分比按需开启。
+- 录入时自动进行格式化处理。
+- 可带单位，例如元、%、次。
+
+### 字段说明
+
+- 提示文本：请输入。
+- 自动计算字段可按需说明计算规则。
+
+### 字段校验
+
+- 范围校验：按需设定字段范围，超出显示错误提示。
+- 格式校验：禁止多个 0 开头。
+
+### 列表显示
+
+- 按需显示。
+- 筛选：区间筛选。
+- 高级筛选：等于、不等于、介于、为空、不为空。
+- 排序：按数值大小正序或倒序。
+
+### 产品要点
+
+- 必须明确小数位数。
+- 必须明确是否支持负数。
+- 必须明确是否需要千分符。
+- 必须明确是否自动计算及计算公式。
+- 退款、冲销、调整等场景如果需要负数，必须明确说明。
+
+### UI 与体验要点
+
+- 自动计算可修改时，应显性显示自动计算结果，提示用户当前值与计算值存在差异。
+
+### 研发要点
+
+- 千分符和百分比不影响实际存储值。例如前端显示 `15%`，后端存储 `0.15`。
+- 使用 decimal 类型存储，避免浮点误差。
+- 金额计算使用高精度库，禁止使用 float/double。
+
+## 时间 / 日期
+
+### 适用范围
+
+- 立项日期、结项日期、创建时间等。
+
+### 录入方式
+
+- 日期选择器：日期、日期范围、时间、时间范围。
+- 日期选择器按需支持快捷选项。
+- 日期选择器按需限制可选范围。
+- 默认值：填报当天、提交时间、自动计算。
+- 支持格式化处理，例如输入 `2026/01/12` 可处理成 `2026-01-12`。
+
+### 字段说明
+
+- 提示文本：请选择。
+- 自动计算字段可按需说明计算规则。
+
+### 字段校验
+
+- 逻辑校验：结束日期不得早于开始日期。
+
+### 列表显示
+
+- 按需显示。
+- 筛选：区间筛选。
+- 高级筛选：等于、不等于、介于、为空、不为空。
+- 排序：按时间正序或倒序。
+
+### 产品要点
+
+- 必须明确显示精度：年、年月、年月日、年月日时分、年月日时分秒。
+- 必须明确筛选精度。
+
+### UI 与体验要点
+
+- 创建时如果填写的是日期范围或时间范围，列表呈现时需拆分为开始时间、结束时间两列，便于筛选。
+
+### 研发要点
+
+- 存储统一使用 UTC 时间戳或 ISO 8601 格式。
+- 前端按用户时区展示。
+- 日期比较需要统一精度后再比较。

package/skills/execution/devFlow/domains/frontend/references/product-design-specs/fields-relation.md

@@ -0,0 +1,144 @@
+# 关联选择字段规范
+
+## 跨表选取
+
+### 适用范围
+
+- 项目、合同、供应商、收款账户、付款账户等。
+
+### 录入方式
+
+- 下拉单选、弹窗单选、下拉多选、弹窗多选、快捷操作直接写入。
+- 默认值：无，或按规则自动计算。
+- 输入限制：按需设置是否支持输入。
+
+### 字段说明
+
+- 仅选取：提示文本为“请选择”。
+- 支持输入：提示文本为“请选择/输入”。
+- 自动计算：提示文本为“选择XX后自动带出”。
+- 帮助文本：一般无帮助文本，如有要求按需说明。
+
+### 列表显示
+
+- 按需显示。
+- 筛选：模糊查询。
+- 高级筛选：等于、不等于、包含、不包含、为空、不为空。
+- 排序：按字母升序或降序。
+
+### 产品要点
+
+- 必须明确单选或多选。
+- 选择关键信息时，需要明确辅助信息，尤其在关键信息可能重复时，例如重名用户增加工号、部门、岗位。
+- 必须明确选项是否全量显示。
+- 必须明确选项数据范围，以及是否与用户数据权限关联。
+- 必须明确来源数据值变更后，本表数据如何处理：实时更新或快照冻结。
+
+### UI 与体验要点
+
+- 辅助信息较少或选项较少时，优先使用下拉选取。
+- 辅助信息较多或来源数据量较大时，优先使用弹窗选取。
+- 一般单选场景回显选项值即可。
+- 多选且信息简单时，以 Tag 形式回显。
+- 多选且信息复杂时，以表格形式呈现。
+- 选项较多时，支持关键词检索。
+- 不支持输入时，输入信息仅用于关键词模糊查询，失焦后清空输入框。
+- 多选时，已选项支持删除，全部选项支持清空。
+
+### 研发要点
+
+- 选项列表返回结构需要包含关键字段及辅助信息。
+- 存储选项 ID，而不是选项值。
+- 大数据量场景需要支持分页加载或虚拟滚动。
+
+## 用户选择
+
+### 适用范围
+
+- 项目经理、销售人员等。
+
+### 录入方式
+
+- 用户选择器，支持单选或多选。
+- 选项范围按需设置条件，例如仅在职用户、仅业务销售部用户。
+- 默认值：无、当前用户、按规则自动计算。
+
+### 字段说明
+
+- 提示文本：请选择。
+- 帮助文本：一般无帮助文本。
+
+### 字段校验
+
+- 无。
+
+### 列表显示
+
+- 按需显示，一般显示用户头像和用户名。
+- 筛选：下拉多选。
+- 高级筛选：等于、不等于、包含任意一个、不包含、同时包含、为空、不为空。
+- 排序：按用户名拼音升序或降序。
+
+### 产品要点
+
+- 必须明确人员范围：全公司、本部门、指定部门、指定角色。
+- 必须明确是否支持选择已离职人员。
+- 必须明确人员变更后历史数据处理方式：保留原值或同步更新。
+
+### UI 与体验要点
+
+- 显示用户姓名和头像。
+- 悬浮显示部门、岗位等辅助信息。
+- 支持关键词检索。
+- 多选时采用穿梭框，可见已选项。
+- 多选回显使用 Tag，支持逐个删除和一键清空。
+- 已离职人员需有明确标识，例如灰色或标签。
+
+### 研发要点
+
+- 存储用户 ID，显示时关联查询用户姓名等信息。
+- 需要支持根据角色、部门、岗位过滤可选人员列表。
+
+## 部门选择
+
+### 适用范围
+
+- 所属部门、归属组织、成本中心等。
+
+### 录入方式
+
+- 部门选择器，支持单选或多选。
+- 选项范围按需设置。
+- 默认值：无、当前用户所属部门、按规则自动计算。
+
+### 字段说明
+
+- 提示文本：请选择。
+- 帮助文本：一般无帮助文本。
+
+### 字段校验
+
+- 无。
+
+### 列表显示
+
+- 按需显示。
+- 筛选：下拉多选。
+- 高级筛选：等于、不等于、包含任意一个、不包含、同时包含、为空、不为空。
+- 排序：按部门编码或部门名称拼音升序/降序。
+
+### 产品要点
+
+- 必须明确选择范围。
+- 必须明确部门变更后历史数据处理方式：保留原值或同步更新。
+
+### UI 与体验要点
+
+- 支持关键词检索。
+- 多选时采用穿梭框，可见已选项。
+- 多选回显使用 Tag，支持逐个删除和一键清空。
+- 已撤销部门需有明确标识，例如灰色或标签。
+
+### 研发要点
+
+- 存储部门 ID，显示时关联查询部门名称。

package/skills/execution/devFlow/domains/frontend/references/product-design-specs/fields-selectors.md

@@ -0,0 +1,102 @@
+# 选择器字段规范
+
+## 下拉选择
+
+### 适用范围
+
+- 类别、状态等。
+
+### 录入方式
+
+- 下拉选择，支持单选或多选。
+- 数据来源：枚举值、数据字典。
+
+### 字段说明
+
+- 提示文本：请选择。
+- 帮助文本：按需说明各选项含义。
+
+### 字段校验
+
+- 需要明确数据来源是枚举还是字典。
+- 需要明确是否支持多选。
+- 需要明确选项是否可扩展。
+
+### 列表显示
+
+- 按需显示。
+- 筛选：下拉多选，目标数据中包含任意一个所选选项的数据。
+- 高级筛选：等于、不等于、包含任意一个、不包含、同时包含、为空、不为空。
+- 排序：
+  - 枚举值：按选项名称字母正序或倒序。
+  - 数据字典：按选项编码或选项排序排列。
+
+### 产品要点
+
+- 必须明确数据来源、是否多选、选项是否可扩展。
+- 选项扩展交互需要明确：
+  - 选择其他，填写其他信息，存储为其他。
+  - 选择其他，填写其他信息后，存储为填写的值。
+
+### UI 与体验要点
+
+- 状态等关键信息选项需要按不同颜色显示。
+- 同个业务字段在不同页面的颜色需要保持一致。
+- 选项大于等于 10 个时，一般不区分颜色，避免干扰。
+- 选项大于等于 10 个时，需要支持选项搜索、全选、已选列表。
+
+### 研发要点
+
+- 枚举值存储选项值即可。
+- 数据字典类需要存储选项编码和选项值。
+- 字典数据建议前端缓存，避免重复请求。
+
+## 级联选择
+
+### 适用范围
+
+- 省/市/区、多级分类。
+
+### 录入方式
+
+- 级联选择器，支持单选或多选，逐级展开子选项。
+- 默认值：无，或按规则自动带出。
+- 数据来源：树形数据字典。
+
+### 字段说明
+
+- 提示文本：请选择 / 请选择至末级。
+- 帮助文本：按需说明各选项含义。
+
+### 字段校验
+
+- 如果要求必须选至末级，需要校验所选节点是否为叶子节点。
+
+### 列表显示
+
+- 按需显示。
+- 可显示完整路径，或仅显示末级。
+- 筛选：树形下拉多选。
+- 选中父级时，筛选包含其所有子级的数据。
+- 高级筛选：等于、不等于、包含任意一个、不包含、为空、不为空。
+- 排序：按选项编码或选项排序排列。
+
+### 产品要点
+
+- 必须明确层级数量。
+- 必须明确是否必须选到末级。
+- 必须明确层级数据维护方式：系统预置或管理员配置。
+
+### UI 与体验要点
+
+- 逐级展开，每级面板宽度一致。
+- 支持关键词搜索，搜索结果显示完整路径。
+- 选中后输入框显示完整路径，以 `/` 分隔。
+- 数据量较大时，每级支持滚动加载。
+
+### 研发要点
+
+- 存储末级节点 ID。
+- 查询时通过路径字段还原完整层级。
+- 层级数据建议前端缓存，按需懒加载子级。
+- 需要支持根据父级 ID 查询子级列表的接口。

package/skills/execution/devFlow/domains/frontend/references/product-design-specs/fields-text.md

@@ -0,0 +1,130 @@
+# 文本字段规范
+
+## 短文本
+
+### 适用范围
+
+- 标题、名称、身份证号、邮箱号码、手机号码、固定电话等。
+
+### 录入方式
+
+- 文本输入、扫码输入、语音输入。
+- 默认值：无、自动计算、固定文本。
+- 通用输入限制：
+  - 禁止空格、换行。
+  - 长度限制：20 或 100 字符，具体按需求确认。
+- 特殊输入限制：
+  - 手机号码（中国大陆）：等于 11 位，仅允许数字字符。
+  - 固定电话：不含分机符号部分不超过 15 位；仅允许数字字符、连字符、分机标识 `#`
+    或 `ext`。
+  - 手机号（全球）：仅过滤明显非法字符，例如字母、表情符号。
+  - 邮箱：小于等于 100 字符。
+  - 身份证号（中国大陆）：等于 18 位，仅允许数字字符和 `X`。
+  - 统一社会信用代码：`^[159]\d[0-9]{6}[0-9A-Z]{9}[0-9A-Z]$`
+  - 组织机构代码：`^[0-9A-HJ-NP-RT-UW-Y]{8}[0-9X]$`
+
+### 字段说明
+
+- 提示文本：请输入。
+- 帮助文本：一般无帮助文本，如有要求按需说明。
+
+### 字段校验
+
+- 手机号码（中国大陆）：`^1(3\d|4[5-9]|5[0-35-9]|6[2567]|7[0-8]|8\d|9[0-35-9])\d{8}$`
+- 固定电话：`^0\d{2,3}-?\d{7,8}(#\d{1,6})?$`
+- 身份证号（中国大陆）：`^[1-9]\d{5}(18|19|20)?\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])\d{3}[\dXx]$`
+- 身份证号（中国大陆）必须实现 GB 11643-1999 校验码验证，不能只靠正则。
+
+### 列表显示
+
+- 显示：按需显示。
+- 筛选：模糊查询。
+- 高级筛选：等于、不等于、包含、不包含、为空、不为空。
+- 排序：按字母升序或降序。
+
+### UI 与体验要点
+
+- 邮箱号码可支持自动补全常用域名。
+- 手机号（全球）支持国际区号下拉选择，默认 `+86`，或根据 IP、浏览器语言推荐。
+
+## 长文本
+
+### 适用范围
+
+- 备注、说明、简介等。
+
+### 录入方式
+
+- 手动输入，支持空格、换行。
+- 支持语音输入。
+- 默认值：无。
+- 无特殊说明时，默认限制 200 或 2000 字符，超出禁止输入。
+
+### 字段说明
+
+- 提示文本：请输入。
+- 帮助文本：一般无帮助文本，如有要求按需说明。
+
+### 字段校验
+
+- 无。
+
+### 列表显示
+
+- 一般不支持显示，如有需求需特殊说明。
+- 一般不支持筛选。
+- 高级筛选：不支持。
+- 排序：不支持。
+
+### UI 与体验要点
+
+- 编辑态默认 5 行，超出可滚动。
+- 底部显示已输入字数和总字数。
+- 详情态按内容高度自适应。
+
+### 研发要点
+
+- 存储时保留换行符。
+- 展示时转义。
+- 需要防范 XSS 注入。
+
+## 富文本
+
+### 适用范围
+
+- 公告、通知、详情描述、邮件内容等。
+
+### 录入方式
+
+- 富文本编辑器。
+- 基础能力：缩进、对齐、加粗、斜体、下划线、有序列表、无序列表、图片、超链接。
+- 高级能力：表格、清除格式、全屏、快捷键。
+- 默认值：无；如有模版规范，可按需设置模版。
+
+### 字段说明
+
+- 无。
+
+### 字段校验
+
+- 无。
+
+### 列表显示
+
+- 不支持显示。
+
+### 产品要点
+
+- 需要明确是否支持模版。
+- 需要明确是否需要 @ 人员。
+- 需要明确是否支持附件插入。
+
+### UI 与体验要点
+
+- 工具栏保持简洁，默认收起部分高级功能。
+
+### 研发要点
+
+- 输出 HTML 或 JSON 格式。
+- 需要做 XSS 过滤。
+- 图片上传需要支持压缩与附件存储。

package/skills/execution/devFlow/domains/frontend/references/product-design-specs/index.md

@@ -0,0 +1,42 @@
+# 产品设计规范索引
+
+本目录用于存放产品给出的字段、校验、展示和交互规范。使用时先读本索引，再根据页面涉及的字段类型读取对应分册。不要一次性加载全部规范。
+
+## 读取流程
+
+1. 先识别页面中涉及的字段类型、列表能力、详情展示、表单提交、筛选、上传、选择器、弹窗和操作反馈。
+2. 先读取
+   `field-common.md`，它是字段布局、必填、校验、错误提示、只读、列表展示的通用规范。
+3. 根据字段类型读取对应分册。
+4. 页面涉及默认值、空状态、操作反馈、弹窗、文案或中断恢复时，读取
+   `interaction.md`。
+5. 如果字段类型无法判断，不要套用规范，写入待确认项。
+
+## 字段类型路由
+
+| 页面字段 / 能力                                                                                                | 读取文件                |
+| -------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| 任意字段、表单、详情、列表展示                                                                                 | `field-common.md`       |
+| ID、合同ID、补充协议ID、订单号、交易流水、凭证号、服务编码、员工工号、地区代码、国家代码                       | `fields-id-code.md`     |
+| 标题、名称、身份证号、邮箱、手机号、固定电话、统一社会信用代码、组织机构代码                                   | `fields-text.md`        |
+| 备注、说明、简介                                                                                               | `fields-text.md`        |
+| 公告、通知、详情描述、邮件内容、富文本编辑器                                                                   | `fields-text.md`        |
+| 金额、数量、利润率、税率、百分比、单价、合计                                                                   | `fields-number-date.md` |
+| 日期、时间、日期范围、时间范围、创建时间、立项日期、结项日期                                                   | `fields-number-date.md` |
+| 类别、状态、枚举、数据字典、单选、多选                                                                         | `fields-selectors.md`   |
+| 省市区、多级分类、树形字典                                                                                     | `fields-selectors.md`   |
+| 项目、合同、供应商、账户、外部对象选择                                                                         | `fields-relation.md`    |
+| 项目经理、销售人员、用户选择                                                                                   | `fields-relation.md`    |
+| 所属部门、归属组织、成本中心、部门选择                                                                         | `fields-relation.md`    |
+| 开票明细、结算明细、可编辑表格、子表                                                                           | `fields-complex.md`     |
+| 附件、图片、文件上传                                                                                           | `fields-complex.md`     |
+| 默认值、空状态、查询、筛选、编辑、保存、删除、通过、驳回、撤回、注销、清空、弹窗、按钮文案、错误文案、中断恢复 | `interaction.md`        |
+
+## 输出要求
+
+在页面技术方案中引用这些规范时：
+
+- 不要整段复制规范正文。
+- 只提炼和当前页面相关的约束。
+- 如果页面字段与规范冲突，优先写入“风险与待确认项”。
+- 如果规范要求产品确认某项内容，例如小数位数、数据来源、人员范围，应明确列为待确认问题。

package/skills/execution/devFlow/domains/frontend/references/product-design-specs/interaction.md

@@ -0,0 +1,61 @@
+# 交互规范
+
+## 默认值设计
+
+- 需要考虑首次使用。
+- 需要考虑空数据。
+- 需要考虑无历史记录。
+
+## 空状态设计
+
+- 空状态应提供操作引导。
+- 空状态可提供帮助说明。
+- 适合时可提供示例数据。
+
+## 操作类型
+
+常见操作包括：
+
+- 查询
+- 筛选
+- 高级筛选
+- 编辑
+- 保存
+- 删除
+- 通过
+- 驳回
+- 撤回
+- 注销
+- 清空
+
+涉及风险的操作需要考虑：
+
+- 风险提示
+- 二次确认
+- 撤销机制
+
+## 操作反馈
+
+- 成功反馈。
+- 失败反馈。
+- 等待反馈。
+
+## 弹窗规范
+
+弹窗类型包括：
+
+- 提示弹窗
+- 确认弹窗
+- 表单弹窗
+- 详情弹窗
+
+## 文案规范
+
+- 按钮文案：动词 + 名称。
+- 错误提示：发生了什么 + 原因 + 建议。
+
+## 中断恢复
+
+- 页面关闭：考虑草稿保存。
+- 浏览器崩溃：考虑自动恢复。
+- 网络异常：考虑重试机制。

package/skills/execution/devFlow/domains/frontend/scripts/check_page_tech_doc.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+
+const filePath = process.argv[2]
+
+if (!filePath) {
+  console.error('Usage: node check_page_tech_doc.mjs <markdown-file>')
+  process.exit(2)
+}
+
+const markdown = fs.readFileSync(filePath, 'utf8')
+const issues = []
+
+function hasSection(title) {
+  return new RegExp(`^#{2,4}\\s+${escapeRegExp(title)}\\s*$`, 'm').test(markdown)
+}
+
+function getSection(title) {
+  const pattern = new RegExp(`^#{2,4}\\s+${escapeRegExp(title)}\\s*$`, 'm')
+  const match = pattern.exec(markdown)
+  if (!match) return ''
+
+  const start = match.index + match[0].length
+  const rest = markdown.slice(start)
+  const next = /^#{2,4}\s+/m.exec(rest)
+  return next ? rest.slice(0, next.index) : rest
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function countApiMentions() {
+  const matches = markdown.match(/\b(GET|POST|PUT|PATCH|DELETE)\s+[\w./:-]+|\bapi\/[\w./:-]+/g)
+  return matches ? matches.length : 0
+}
+
+function hasMarkdownTable(section) {
+  return /\|.+\|\s*\n\|[\s:-]+\|/.test(section)
+}
+
+function hasMermaid(section) {
+  return /```mermaid[\s\S]*?```/.test(section)
+}
+
+const mappingSection = getSection('3.1 功能与接口映射')
+if (!mappingSection) {
+  issues.push('缺少 3.1 功能与接口映射章节')
+} else if (!hasMarkdownTable(mappingSection)) {
+  issues.push('3.1 功能与接口映射必须使用 Markdown 表格')
+}
+
+const interactionSection = getSection('3.3 关键交互')
+if (!interactionSection) {
+  issues.push('缺少 3.3 关键交互章节')
+} else if (!hasMarkdownTable(interactionSection) && interactionSection.trim().length < 80) {
+  issues.push('3.3 关键交互内容不足，需逐项覆盖 PRD 交互')
+}
+
+const dataFlowSection = getSection('5.6 数据流')
+const apiCount = countApiMentions()
+if (!dataFlowSection) {
+  issues.push('缺少 5.6 数据流章节')
+} else if (apiCount >= 2 && !hasMermaid(dataFlowSection)) {
+  issues.push('检测到多个接口，但 5.6 数据流缺少 Mermaid 数据流转图')
+}
+
+if (!hasSection('10. 风险与待确认项')) {
+  issues.push('缺少 10. 风险与待确认项章节')
+}
+
+if (!/PRD|prd/.test(markdown)) {
+  issues.push('正文未出现 PRD 标识，请确认是否已对齐需求来源和交互项')
+}
+
+if (issues.length > 0) {
+  console.error(JSON.stringify({ ok: false, issues }, null, 2))
+  process.exit(1)
+}
+
+console.log(JSON.stringify({ ok: true, issues: [] }, null, 2))