visual-spec 0.1.0 → 0.1.1

package/skills/visual-spec-skill/SKILL-zh-CN.md

@@ -0,0 +1,261 @@
+---
+name: "visual-spec-skill"
+description: "将原始需求分析为可评审的视觉规格，并生成相关产物。当用户运行 /vspec:new 进行分析或运行 /vspec:verify 生成模型与原型时调用。"
+---
+
+# Visual Spec Skill（中文）
+
+基于用户输入分析视觉规格，把简短的业务请求转化为结构化的需求输出。
+
+## 何时使用
+
+在以下情况调用本 Skill：
+- 业务侧给出的需求描述非常简略。
+- 用户运行 `/vspec:new` 开始新的需求分析流程。
+
+## 本 Skill 定义的内容
+
+- 使用“场景驱动拆解”的方式补齐细节。
+- 设计数据模型。
+- 基于补齐后的细节生成 UI 原型。
+- 以可视化/结构化形式生成业务逻辑细节。
+
+## Commands
+
+### `/vspec:new`
+
+用于创建一轮新的需求分析会话。
+
+流程：
+0. 确保 `/docs/` 存在，并确保子目录存在：
+   - `/docs/legacy/`
+   - `/docs/current/`
+   - `/docs/change/`
+   - `/docs/refine/`
+0.5 尽早创建可编辑的项目约束文件，便于用户提前调整（若已存在则不得覆盖）：
+   - 若缺失则创建 `/scheme.yaml`（包含原型选栈 + catalog）
+   - 若缺失则创建 `/prototype_ui_convention.md`（与 `/scheme.yaml` 同级）
+1. 提示用户输入原始需求。
+2. 当用户按下回车，将输入视为原始需求来源。
+3. 加载提示词文件 `prompts/vspec_new/background.md`。
+4. 使用该提示词分析需求并扩展业务背景。
+5. 将原始需求与背景分析写入 `/specs/background/original.md`。
+6. 提示用户回答 `待确认问题` 章节中的问题。
+7. 用户回复后，加载 `prompts/vspec_new/stakeholders.md` 分析干系人。
+8. 将干系人结果写入 `/specs/background/stakeholder.md`（markdown 表格）。
+9. 加载 `prompts/vspec_new/roles.md` 分析系统用户角色（直接用户）及其工作任务。
+10. 将角色结果写入 `/specs/background/roles.md`。
+11. 加载 `prompts/vspec_new/terms.md` 抽取关键术语与定义。
+12. 将术语结果写入 `/specs/background/terms.md`（markdown 表格）。
+13. 加载 `prompts/vspec_new/flows.md` 分析业务流程并生成 PlantUML 泳道图。
+14. 将图写入 `/specs/flows/*.puml`。
+15. 加载 `prompts/vspec_new/scenarios.md` 按节点组合枚举业务场景。
+16. 将场景结果写入 `/specs/background/scenarios.md`（markdown 表格）。
+17. 加载 `prompts/vspec_new/details_pre_post.md` 创建按节点拆分的详情目录，并为每个节点生成 `pre_post.md`。
+18. 加载 `prompts/vspec_new/details_constraints.md` 为每个节点生成 `constraints.md`。
+19. 加载 `prompts/vspec_new/details_variations.md` 为每个节点生成 `variations.md`。
+20. 加载 `prompts/vspec_new/details_boundaries.md` 为每个节点生成 `boundaries.md`。
+21. 加载 `prompts/vspec_new/details_symmetry.md` 为每个节点生成 `symmetry.md`。
+22. 确保按节点拆分的输出都写到 `/specs/background/scenario_details/`。
+23. 加载 `prompts/vspec_new/dependencies.md` 分析外部依赖系统。
+24. 将依赖结果写入 `/specs/background/dependencies.md`。
+25. 加载 `prompts/vspec_new/functions.md` 生成按模块与外部依赖系统分组的功能/特性清单。
+26. 将功能清单写入 `/specs/functions/`。
+27. 加载 `prompts/vspec_new/questions.md` 生成问题清单与所需业务材料清单。
+28. 将问题清单写入 `/specs/background/questions.md`（markdown 列表）。
+29. 返回结构化分析结果，并进入下一步需求设计流程。
+
+### `/vspec:refine`
+
+用于基于 `/docs/refine/` 下的补充/澄清材料，或基于命令参数提供的一个/多个输入文件或目录，对需求进行补充与更新。
+
+流程：
+0. 确保 `/specs/details/` 存在且非空；若缺失则停止并提示用户先运行 `/vspec:detail`。
+1. 读取 refine 输入：
+   - 若命令参数提供了路径，将其视为 refine 输入源（文件/目录）。
+   - 否则读取 `/docs/refine/`（若存在优先读 `/docs/refine/file_list.md`；否则按文件名顺序读取）。
+2. 加载 `prompts/vspec_refine/refine.md` 应用补充信息、更新需求口径并同步更新受影响的产物。
+3. 将 refine 结果追加到 `/specs/background/original.md`，并更新受影响的 `/specs/details/` 与 `/specs/prototypes/`。
+
+### `/vspec:refine-q`
+
+用于基于“已回答的问题”补充与更新需求。
+
+流程：
+1. 读取 `/specs/background/questions.md` 并选择已回答项。
+2. 加载 `prompts/vspec_refine/refine_q.md` 将答案合并进最新口径。
+3. 将结果追加到 `/specs/background/original.md`。
+4. 更新 `/specs/background/questions.md`，标记本次运行中已视为回答的条目：
+   - 用 `<mark>...</mark>` 包裹 `回答` 与 `状态`，以高亮已回答项。
+
+### `/vspec:detail`
+
+用于基于功能清单展开需求细节。
+
+流程：
+1. 读取 `/specs/functions/*` 中的功能清单。
+2. 尽可能读取可用的上下文产物：`/specs/background/*`、`/specs/flows/*.puml`、`/specs/background/scenario_details/`、`/specs/background/roles.md`，以及已有的 `/specs/models/*.md`（若存在）。
+3. 对每个功能（页面或非页面任务），先判断哪些详情产物真正涉及，再只生成涉及的部分；对不涉及的部分不得生成空文档。
+   - 始终生成基础文档：
+     - `rbac.md`：RBAC 权限下沉到页面区域与控件级。
+     - `data_permission.md`：数据权限规则与范围。
+   - 仅页面类功能生成：
+     - `page_load.md`：页面加载逻辑。
+      - `interaction.md`：页面交互逻辑。
+     - `validation_matrix.md`：矩阵形式的校验逻辑（仅提交类页面/动作；若页面无 submit/save/approve/reject/cancel/change 等动作则跳过）。
+     - `post_submit_check.md`：提交后检查（若页面存在提交）。
+     - `post_submit_processing.md`：提交后处理（若页面存在提交）。
+     - `post_submit_navigation.md`：提交后返回与跳转（若页面存在提交）。
+   - 条件生成（仅当该功能的逻辑/场景/模型/依赖涉及时才生成）：
+     - `logging_matrix.md`：操作/审计日志（仅在业务需要保留变更历史、合规审计或不可抵赖时生成，否则跳过）。
+     - `decision_matrix.md`：决策矩阵（用于状态机下各状态/角色的操作可用性）。
+     - `notification_matrix.md`：通知（存在通知需求时生成）。
+     - `mq.md`：MQ topic/event/消息 schema/可靠性细节（存在异步事件、队列或跨系统事件时生成）。
+     - `file_import.md`：导入（存在导入入口/需求时生成）。
+     - `file_export.md`：导出（存在导出入口/需求时生成）。
+     - `formula.md`：计算公式与指标语义（存在计算/指标时生成）。
+     - `expression_tree.md`：表达式树（HTML）（存在多层嵌套分支逻辑时生成）。
+     - `code_rules.md`：编号/编码生成规则（存在编码生成时生成）。
+     - `judgemental_matrix.md`：判定矩阵（2+ 因素共同决定结果的多因子分支时生成）。
+   - 模块级（每模块最多生成一次，且仅当涉及时生成）：
+     - `timeline.md`：时间轴（HTML）用于整体流程影响分析（存在跨较长时间跨度影响决策的逻辑，如生效/失效、截止期、宽限期、跨天规则等时生成）。
+      - `state_machine.md`：状态列表 + 迁移 + PlantUML 状态图（模块整体，不按功能拆分）。
+     - `nfp.md`：模块非功能需求总结（模块整体，不按功能拆分）。
+     - `cron_job.md`：模块定时任务总结（模块整体，不按功能拆分）。
+4. 仅写入生成的（涉及的）详情文档：
+   - 单功能：`/specs/details/<module_slug>/<logic_type>/<function_slug>.(md|html)`
+   - 模块级：`/specs/details/<module_slug>/<logic_type>/overall.(md|html)`
+
+### `/vspec:verify`
+
+用于生成模型与可运行原型，用于快速验证与评审。
+
+流程：
+0. 确保 `/specs/details/` 存在且非空；若缺失则停止并提示用户先运行 `/vspec:detail`。
+1. 若 `/specs/background/questions.md` 存在且仍有未回答的问题，先要求用户回答再继续（允许逐条跳过，但必须保证不存在“未处理”的问题）。
+2. 加载 `prompts/vspec_verify/model.md` 生成数据模型。
+3. 将模型文件写入 `/specs/models/*.md`。
+4. 基于 functions/details/models/roles 生成可运行的页面原型；原型技术栈由 `/scheme.yaml` 选择（若缺失则按默认值自动创建）。
+   - 加载 `prompts/vspec_verify/prototype.md` 执行原型生成规则（必须遵循 `scheme.yaml` 技术栈；禁止只生成 html-only）。
+5. 将原型工程写入 `/specs/prototypes/`。
+6. 加载 `prompts/vspec_verify/validation.md` 生成场景验证网页。
+7. 将验证页面写入 `/specs/prototypes/`，并提供 `scenario.html` 作为访问入口。
+
+### `/vspec:qc`
+
+用于对 `/specs/` 下生成的需求产物进行质量检查。
+
+流程：
+1. 读取内置标准 `prompts/vspec_qc/quality_standard.md`。
+2. 若项目 `qc/` 下存在“需求质量错误簿”，则据此生成/更新项目根目录的 `quality_standard.md`。
+3. 若项目根目录存在 `quality_standard.md`，则将其作为补充/覆盖标准合并。
+4. 加载 `prompts/vspec_qc/qc.md` 生成不符合项清单。
+5. 将报告写入 `/specs/qc_report.md`。
+
+### `/vspec:accept`
+
+用于生成验收测试用例。
+
+流程：
+1. 读取 `/specs/functions/*`、`/specs/background/scenarios.md`、`/specs/background/scenario_details/`、`/specs/background/roles.md`、`/specs/models/*.md`。
+2. 加载 `prompts/vspec_accept/accept.md` 生成验收用例，覆盖主流程、异常、边界、权限与数据范围。
+3. 将结果写入 `/specs/acceptance/`（按功能建子目录），并生成 `/specs/acceptance/index.md` 索引。
+
+### `/vspec:test`
+
+用于基于验收用例与规格生成自动化测试代码。
+
+流程：
+1. 读取 `/specs/acceptance/`、`/specs/functions/*`、`/specs/details/`，并识别仓库中已有的测试框架。
+2. 加载 `prompts/vspec_test/test.md`，按既有框架与约定生成自动化测试。
+3. 将测试代码写入项目测试目录（若不存在标准目录则写入 `/tests/`），并确保能通过已有脚本运行。
+
+### `/vspec:impl`
+
+用于基于 specs 生成前后端集成实现代码。
+
+流程：
+1. 读取 `/specs/functions/*`、`/specs/details/`、`/specs/models/*.md`、`/specs/background/dependencies.md`，并识别当前前后端技术栈与代码约定。
+2. 加载 `prompts/vspec_impl/implement.md` 并按后端优先实现：先在 `/specs/backend/` 生成可运行后端工程（health check + 核心 API/service），再在后端 API 可用后生成前端集成对接。
+3. 仅允许在 `/specs/` 下写代码，并尽量保持差异最小且可审查；后端必须在 `/specs/backend/`，原型前端在 `/specs/prototypes/`。
+
+### `/vspec:upgrade`
+
+用于基于 `/docs/` 下材料（`/docs/legacy` 遗留系统、`/docs/current` 新输入）进行升级/改造分析，并按 `/vspec:new` 相同结构重新生成 `/specs/` 产物。
+
+流程：
+1. 确保 `/docs/current/file_list.md` 入口文件存在；若缺失则按模板生成。
+2. 读取 `/docs/current/file_list.md`，再按顺序读取 `/docs/` 下列出的输入（通常 `/docs/legacy/*`、`/docs/current/*`，可选 `/docs/templates/*`、`/docs/texts/*`、`/docs/assets/*`）并抽取结构化信息（功能、依赖、UI 风格、角色/权限、技术规格）。
+3. 若 `/specs/background/original.md` 已存在，则将其视为当前需求口径并作为 diff 基线（继承/新增/变更/废弃）。
+4. 加载 `prompts/vspec_upgrade/upgrade.md`，按 `/vspec:new` 产物约定生成/更新 `/specs/`。
+5. 将抽取到的技术规格同步到 `/scheme.yaml`，供 `/vspec:verify` 与 `/vspec:impl` 使用。
+
+### `/vspec:change`
+
+用于响应需求变更并更新受影响产物。
+
+流程：
+1. 读取 `/docs/change/` 下的变更输入（若存在优先用 `/docs/change/file_list.md` 作为入口；若仅存在 `/docs/changes/` 则兼容读取）。
+2. 若目标仓库为 git 仓库，在写入任何更新前先创建变更前快照提交，保证 diff 可审查。
+3. 读取已存在的 `/specs/` 产物（包括 `/specs/details/`、`/specs/models/`、`/specs/prototypes/`）。
+4. 加载 `prompts/vspec_change/change.md` 做影响分析并更新受影响文档，优先更新 `/specs/details/<module_slug>/` 下的模块详情文档。
+5. 写入更新后的产物，并将变更日志写入 `/specs/change_log.md`。
+
+### `/vspec:plan`
+
+用于把需求拆解为故事地图并进行估算与排期。
+
+流程：
+1. 读取 `/specs/functions/*`、`/specs/background/roles.md`、`/specs/background/scenarios.md`、`/specs/details/`、`/specs/background/dependencies.md`。
+2. 加载 `prompts/vspec_plan/estimate.md`，按功能清单生成估算。
+3. 将估算写入 `/specs/plan/plan_estimate.md`。
+4. 加载 `prompts/vspec_plan/schedule.md` 生成排期与交付地图。
+5. 将排期 HTML 写入 `/specs/plan/plan_schedule.html`。
+
+## Prompt Files
+
+- `prompts/vspec_new/background.md`：`/vspec:new` 接收原始需求后立即使用的提示词。
+- `prompts/vspec_new/stakeholders.md`：用户回答 `待确认问题` 后生成 `/specs/background/stakeholder.md` 的提示词。
+- `prompts/vspec_new/roles.md`：生成 `/specs/background/roles.md` 的提示词。
+- `prompts/vspec_new/terms.md`：生成 `/specs/background/terms.md` 的提示词。
+- `prompts/vspec_new/flows.md`：生成 `/specs/flows/*.puml` 的提示词。
+- `prompts/vspec_new/scenarios.md`：生成 `/specs/background/scenarios.md` 的提示词。
+- `prompts/vspec_new/details_pre_post.md`：生成按节点拆分的 `pre_post.md` 的提示词。
+- `prompts/vspec_new/details_constraints.md`：生成按节点拆分的 `constraints.md` 的提示词。
+- `prompts/vspec_new/details_variations.md`：生成按节点拆分的 `variations.md` 的提示词。
+- `prompts/vspec_new/details_boundaries.md`：生成按节点拆分的 `boundaries.md` 的提示词。
+- `prompts/vspec_new/details_symmetry.md`：生成按节点拆分的 `symmetry.md` 的提示词。
+- `prompts/vspec_new/dependencies.md`：生成 `/specs/background/dependencies.md` 的提示词。
+- `prompts/vspec_new/functions.md`：生成 `/specs/functions/` 的提示词。
+- `prompts/vspec_new/questions.md`：生成 `/specs/background/questions.md` 的提示词。
+- `prompts/vspec_refine/refine.md`：`/vspec:refine` 使用的提示词。
+- `prompts/vspec_refine/refine_q.md`：`/vspec:refine-q` 使用的提示词。
+- `prompts/vspec_verify/model.md`：生成 `/specs/models/*.md` 的提示词。
+- `prompts/vspec_verify/prototype.md`：生成按选栈的可运行原型工程（`/specs/prototypes/`）的提示词（必须遵循 `scheme.yaml`）。
+- `prompts/vspec_verify/validation.md`：生成 `scenario.html` 场景评审页的提示词。
+- `prompts/vspec_detail/rbac.md`：生成 RBAC 详情的提示词。
+- `prompts/vspec_detail/data_permission.md`：生成数据权限详情的提示词。
+- `prompts/vspec_detail/page_load.md`：生成页面加载逻辑的提示词。
+- `prompts/vspec_detail/interaction.md`：生成页面交互逻辑的提示词。
+- `prompts/vspec_detail/timeline.md`：生成时间轴 HTML 的提示词。
+- `prompts/vspec_detail/formula.md`：生成公式说明的提示词。
+- `prompts/vspec_detail/expression_tree.md`：生成表达式树 HTML 的提示词。
+- `prompts/vspec_detail/code_rules.md`：生成编号/编码规则的提示词。
+- `prompts/vspec_detail/judgemental_matrix.md`：生成判定矩阵的提示词。
+- `prompts/vspec_detail/validation_matrix.md`：生成校验矩阵的提示词。
+- `prompts/vspec_detail/post_submit_check.md`：生成提交后检查的提示词。
+- `prompts/vspec_detail/post_submit_processing.md`：生成提交后处理的提示词。
+- `prompts/vspec_detail/post_submit_navigation.md`：生成提交后跳转规则的提示词。
+- `prompts/vspec_detail/mq.md`：生成 MQ 设计的提示词。
+- `prompts/vspec_detail/logging_matrix.md`：生成日志矩阵的提示词。
+- `prompts/vspec_detail/notification_matrix.md`：生成通知矩阵的提示词。
+- `prompts/vspec_detail/nfp.md`：生成非功能需求的提示词。
+- `prompts/vspec_detail/file_import.md`：生成导入设计的提示词。
+- `prompts/vspec_detail/file_export.md`：生成导出设计的提示词。
+- `prompts/vspec_detail/cron_job.md`：生成定时任务设计的提示词。
+- `prompts/vspec_accept/accept.md`：生成验收用例的提示词。
+- `prompts/vspec_test/test.md`：生成自动化测试的提示词。
+- `prompts/vspec_impl/implement.md`：生成前后端集成实现的提示词。
+- `prompts/vspec_upgrade/upgrade.md`：生成升级/改造规格的提示词。
+- `prompts/vspec_change/change.md`：处理变更的提示词。
+- `prompts/vspec_plan/estimate.md`：生成估算的提示词。

package/{.trae/skills/starter-skill → skills/visual-spec-skill}/SKILL.md

@@ -33,6 +33,9 @@ Flow:
    - `/docs/current/`
    - `/docs/change/`
    - `/docs/refine/`
+0.5 Create editable project constraints so the user can tweak them early (do not overwrite if they already exist):
+   - Create `/scheme.yaml` with defaults (prototype stack selection + catalog) if missing
+   - Create `/prototype_ui_convention.md` (same directory as `/scheme.yaml`) if missing
 1. Ask the user to input the original requirement.
 2. When the user presses Enter, treat the input as the raw requirement source.
 3. Load the prompt file at `prompts/vspec_new/background.md`.
@@ -60,7 +63,7 @@ Flow:
 25. Load `prompts/vspec_new/functions.md` to generate feature/function lists grouped by modules and external dependency systems.
 26. Write the function lists to `/specs/functions/`.
 27. Load `prompts/vspec_new/questions.md` to generate question lists and required business materials.
-28. Write the questions result to `/specs/background/questions.md` (markdown table).
+28. Write the questions result to `/specs/background/questions.md` (markdown list).
 29. Return the structured analysis result and continue to the next requirement-design step.
 
 ### `/vspec:refine`
@@ -80,62 +83,11 @@ Flow:
 Use this command to refine and update the requirement based on answered questions.
 
 Flow:
-1. Read `/specs/background/questions.md` and pick answered rows.
+1. Read `/specs/background/questions.md` and pick answered items.
 2. Load `prompts/vspec_refine/refine_q.md` to merge answers into the canonical requirement.
 3. Append the refinement result to `/specs/background/original.md`.
-
-### `/vspec:verify`
-
-Use this command to verify and prototype based on the analysis artifacts.
-
-Flow:
-0. If `/specs/background/questions.md` exists and contains unanswered questions, ask the user to answer them before continuing (allow skip per question, but ensure none remains unanswered).
-1. Load `prompts/vspec_verify/model.md` to generate data models.
-2. Write model files to `/specs/models/*.md`.
-3. Generate a runnable page prototype based on functions, models, and roles; the prototype tech stack can be selected via `/scheme.yaml` (auto-created with defaults if missing).
-4. Write the prototype to `/specs/prototypes/`.
-5. Load `prompts/vspec_verify/validation.md` to generate a scenario validation web page.
-6. Write the validation page to `/specs/prototypes/` and provide a `scenario.html` entry for access.
-
-### `/vspec:proto-apply`
-
-Use this command to generate/update the prototype focusing on “申请（Apply）” flow and pages.
-
-Flow:
-0. If `/specs/background/questions.md` exists and contains unanswered questions, ask the user to answer them before continuing (allow skip per question, but ensure none remains unanswered).
-1. Ensure `/specs/models/` exists; if missing, load `prompts/vspec_verify/model.md` to generate models first.
-2. Load `prompts/vspec_verify/prototype_apply.md` to generate/update the prototype.
-3. Write changes to `/specs/prototypes/`.
-
-### `/vspec:proto-approve`
-
-Use this command to generate/update the prototype focusing on “审批（Approve）” flow and pages.
-
-Flow:
-0. If `/specs/background/questions.md` exists and contains unanswered questions, ask the user to answer them before continuing (allow skip per question, but ensure none remains unanswered).
-1. Ensure `/specs/models/` exists; if missing, load `prompts/vspec_verify/model.md` to generate models first.
-2. Load `prompts/vspec_verify/prototype_approve.md` to generate/update the prototype.
-3. Write changes to `/specs/prototypes/`.
-
-### `/vspec:proto-execute`
-
-Use this command to generate/update the prototype focusing on “执行（Execute）” flow and pages (including mobile `/m/*` when applicable).
-
-Flow:
-0. If `/specs/background/questions.md` exists and contains unanswered questions, ask the user to answer them before continuing (allow skip per question, but ensure none remains unanswered).
-1. Ensure `/specs/models/` exists; if missing, load `prompts/vspec_verify/model.md` to generate models first.
-2. Load `prompts/vspec_verify/prototype_execute.md` to generate/update the prototype.
-3. Write changes to `/specs/prototypes/`.
-
-### `/vspec:proto-crud`
-
-Use this command to generate/update the prototype focusing on generic CRUD admin pages (list/detail/create/edit) for configuration/master-data modules.
-
-Flow:
-0. If `/specs/background/questions.md` exists and contains unanswered questions, ask the user to answer them before continuing (allow skip per question, but ensure none remains unanswered).
-1. Ensure `/specs/models/` exists; if missing, load `prompts/vspec_verify/model.md` to generate models first.
-2. Load `prompts/vspec_verify/prototype_crud.md` to generate/update the prototype.
-3. Write changes to `/specs/prototypes/`.
+4. Update `/specs/background/questions.md` to mark items that are treated as answered in this run:
+   - Wrap the `回答` and `状态` values with `<mark>...</mark>` so the answered items are visually highlighted.
 
 ### `/vspec:detail`
 
@@ -143,7 +95,8 @@ Use this command to expand requirement details based on the function list.
 
 Flow:
 1. Read the feature/function list from `/specs/functions/*`.
-2. For each function (page or non-page job), first determine which detail artifacts are actually involved, then only generate those artifacts; do not generate documents for non-involved parts.
+2. Read supporting artifacts when available: `/specs/background/*`, `/specs/flows/*.puml`, `/specs/background/scenario_details/`, `/specs/background/roles.md`, and existing `/specs/models/*.md` (if any).
+3. For each function (page or non-page job), first determine which detail artifacts are actually involved, then only generate those artifacts; do not generate documents for non-involved parts.
    - Always generate the baseline docs:
      - `rbac.md`: RBAC permissions down to page areas and controls.
      - `data_permission.md`: data permission rules and scope.
@@ -170,10 +123,25 @@ Flow:
       - `state_machine.md`: status list + transitions + PlantUML state diagram (overall; not per function).
      - `nfp.md`: non-functional requirements summary for the module (overall; not per function).
      - `cron_job.md`: scheduled jobs summary for the module (overall; not per function).
-3. Write only the generated (involved) detail documents:
+4. Write only the generated (involved) detail documents:
    - Per-function: `/specs/details/<module_slug>/<logic_type>/<function_slug>.(md|html)`
    - Module-level: `/specs/details/<module_slug>/<logic_type>/overall.(md|html)`
 
+### `/vspec:verify`
+
+Use this command to generate models and a runnable prototype for validation.
+
+Flow:
+0. Ensure `/specs/details/` exists and is non-empty; if missing, stop and ask the user to run `/vspec:detail` first.
+1. If `/specs/background/questions.md` exists and contains unanswered questions, ask the user to answer them before continuing (allow skip per question, but ensure none remains unanswered).
+2. Load `prompts/vspec_verify/model.md` to generate data models.
+3. Write model files to `/specs/models/*.md`.
+4. Generate a runnable page prototype based on functions, details, models, and roles; the prototype tech stack can be selected via `/scheme.yaml` (auto-created with defaults if missing).
+   - Load `prompts/vspec_verify/prototype.md` for the prototype generation rules (must follow `scheme.yaml` stack; do not output html-only).
+5. Write the prototype to `/specs/prototypes/`.
+6. Load `prompts/vspec_verify/validation.md` to generate a scenario validation web page.
+7. Write the validation page to `/specs/prototypes/` and provide a `scenario.html` entry for access.
+
 ### `/vspec:qc`
 
 Use this command to run a quality check on the generated requirement artifacts under `/specs/`.
@@ -209,8 +177,8 @@ Use this command to generate integrated frontend/backend code based on the specs
 
 Flow:
 1. Read `/specs/functions/*`, `/specs/details/`, `/specs/models/*.md`, `/specs/background/dependencies.md`, and detect the current frontend/backend stacks and code conventions.
-2. Load `prompts/vspec_impl/implement.md` to generate API contracts, backend endpoints/services, and frontend integration (API calls, pages, state) following repo patterns.
-3. Write code only under `/specs/prototypes/` (the prototype project) with minimal diffs and keep it reviewable; do not create extra top-level directories.
+2. Load `prompts/vspec_impl/implement.md` and implement backend-first: generate a runnable backend project under `/specs/backend/` (health check + core APIs/services), then generate frontend integration after backend APIs are available.
+3. Write code only under `/specs/` with minimal diffs and keep it reviewable; backend must be under `/specs/backend/` and prototype frontend under `/specs/prototypes/`.
 
 ### `/vspec:upgrade`
 
@@ -241,9 +209,9 @@ Use this command to break down requirements, estimate efforts, and schedule via
 Flow:
 1. Read `/specs/functions/*`, `/specs/background/roles.md`, `/specs/background/scenarios.md`, `/specs/details/`, `/specs/background/dependencies.md`.
 2. Load `prompts/vspec_plan/estimate.md` to generate estimates aligned to the function list.
-3. Write estimates to `/specs/plan_estimate.md`.
+3. Write estimates to `/specs/plan/plan_estimate.md`.
 4. Load `prompts/vspec_plan/schedule.md` to generate the schedule and delivery map.
-5. Write schedule HTML to `/specs/plan_schedule.html`.
+5. Write schedule HTML to `/specs/plan/plan_schedule.html`.
 
 ## Prompt Files
 
@@ -264,7 +232,7 @@ Flow:
 - `prompts/vspec_refine/refine.md`: the prompt used by `/vspec:refine` to refine the requirement based on `refine.md`.
 - `prompts/vspec_refine/refine_q.md`: the prompt used by `/vspec:refine-q` to refine the requirement based on answered questions.
 - `prompts/vspec_verify/model.md`: the prompt used by `/vspec:verify` to generate `/specs/models/*.md`.
-- `prompts/vspec_verify/prototype.md`: the prompt used by `/vspec:verify` to generate the Vue + Ant Design prototype under `/specs/prototypes/`.
+- `prompts/vspec_verify/prototype.md`: the prompt used by `/vspec:verify` to generate the stack-selected runnable prototype under `/specs/prototypes/` (must follow `scheme.yaml`).
 - `prompts/vspec_verify/validation.md`: the prompt used by `/vspec:verify` to generate the validation web page with a `scenario.html` entry.
 - `prompts/vspec_detail/rbac.md`: the prompt used by `/vspec:detail` to generate RBAC detail docs.
 - `prompts/vspec_detail/data_permission.md`: the prompt used by `/vspec:detail` to generate data permission detail docs.
@@ -291,8 +259,8 @@ Flow:
 - `prompts/vspec_impl/implement.md`: the prompt used by `/vspec:impl` to generate integrated frontend/backend code.
 - `prompts/vspec_upgrade/upgrade.md`: the prompt used by `/vspec:upgrade` to generate upgraded specs from `/docs/` inputs.
 - `prompts/vspec_change/change.md`: the prompt used by `/vspec:change` to handle requirement changes.
-- `prompts/vspec_plan/estimate.md`: the prompt used by `/vspec:plan` to generate `/specs/plan_estimate.md`.
-- `prompts/vspec_plan/schedule.md`: the prompt used by `/vspec:plan` to generate `/specs/plan_schedule.html`.
+- `prompts/vspec_plan/estimate.md`: the prompt used by `/vspec:plan` to generate `/specs/plan/plan_estimate.md`.
+- `prompts/vspec_plan/schedule.md`: the prompt used by `/vspec:plan` to generate `/specs/plan/plan_schedule.html`.
 - `prompts/vspec_qc/qc.md`: the prompt used by `/vspec:qc` to generate `/specs/qc_report.md`.
 - `prompts/vspec_qc/quality_standard.md`: built-in quality standard used by `/vspec:qc`.
 

package/{.trae/skills/starter-skill → skills/visual-spec-skill}/prompts/vspec_detail/file_export.md

@@ -9,15 +9,18 @@
 1. 导出场景：入口位置（列表/详情/报表）、导出目的（对账/留档/分析）
 2. 导出范围：当前筛选/选中记录/全量（需结合数据权限）
 3. 文件格式：xlsx/csv/pdf（如适用），编码，大小限制，超时策略
-4. 导出字段清单（必须用表格）：
+4. 模板/样例文件（必须）：
+   - 必须要求业务方提供对应导出模板文件或样例导出文件（xlsx/csv），至少包含表头、格式与口径说明（可脱敏）
+   - 若导出用于对外/监管/对账：必须明确模板版本号与发放渠道（下载入口/附件/线下提供）
+5. 导出字段清单（必须用表格）：
 | 列名 | 字段映射 | 类型 | 是否脱敏 | 说明 | 备注 |
 | --- | --- | --- | --- | --- | --- |
-5. 排序/分页/分片策略：
+6. 排序/分页/分片策略：
    - 大数据导出：异步任务、分片、生成后下载链接、有效期
-6. 审计与风控：
+7. 审计与风控：
    - 是否记录导出日志（引用 logging_matrix）
    - 是否需要二次确认/审批
-7. 失败与降级：
+8. 失败与降级：
    - 超时、部分失败、文件生成失败
    - 重试与通知策略
 

package/{.trae/skills/starter-skill → skills/visual-spec-skill}/prompts/vspec_detail/file_import.md

@@ -8,18 +8,21 @@
 产出要求（涉及导入时）：
 1. 导入场景：入口位置（页面/按钮）、导入目的（新增/更新/校正/批量审批等）
 2. 文件格式：xlsx/csv，编码，大小限制，行数限制
-3. 模板定义（必须用表格）：
+3. 模板文件（必须）：
+   - 必须要求业务方提供对应导入模板文件（xlsx/csv），并在规格中明确模板版本号与获取路径（如存放于项目资产目录）
+   - 必须提供 1 份带示例数据的模板样例（可脱敏），用于联调与验收
+4. 模板定义（必须用表格）：
 | 列名 | 字段映射 | 类型 | 必填 | 示例 | 校验规则 | 备注 |
 | --- | --- | --- | --- | --- | --- | --- |
-4. 处理流程：
+5. 处理流程：
    - 预检查（权限、数据权限、模板版本）
    - 解析与逐行校验（与校验矩阵联动）
    - 事务策略（全量回滚/部分成功）
    - 重复数据处理（幂等 key / 覆盖/跳过）
-5. 导入结果反馈：
+6. 导入结果反馈：
    - 成功条数/失败条数
    - 错误明细下载（是否需要，格式）
-6. 失败与降级：
+7. 失败与降级：
    - 大文件超时、解析失败、字段缺失
    - 重试与断点续传（如适用）
 

package/{.trae/skills/starter-skill → skills/visual-spec-skill}/prompts/vspec_impl/implement.md

@@ -26,27 +26,41 @@
 2. 生成“接口契约”并据此实现：
    - 定义 endpoints、method、path、request/response schema、错误码
    - 若仓库已有 OpenAPI/DTO/类型定义，必须复用并补齐
-3. 外部依赖接入（必须，按 dependencies 落地到代码）：
+3. 实现顺序（必须）：
+   - 必须后端优先：在生成任何前端页面/API 调用之前，先在 `/specs/backend/` 生成可编译、可启动的后端工程骨架，并提供健康检查接口
+   - 再按接口契约逐个实现后端：实体/DTO、Repository、Service、Controller/API 与必要的校验/权限/状态流转（Repository 与 Service 必须都有，禁止把业务逻辑直接堆在 Controller）
+   - 禁止只做前端 mock 或只写接口契约不落后端代码
+   - 后端接口可用后，再生成/改造前端页面与 API 调用，完成前后端集成联调（前端不得绕过后端直接 mock 业务数据）
+4. 外部依赖接入（必须，按 dependencies 落地到代码）：
    - 必须读取并解析 `/specs/background/dependencies.md`，把每个外部系统/第三方服务映射到业务链路中的“必要环节”（例如：提交申请、审批通过、执行开始/结束、支付成功、通知发送等）
    - 对每个依赖必须生成可替换的接入层（adapter/gateway/client，按仓库分层习惯放置）：
      - 真实外部接口已明确（域名/path/鉴权方式/字段）时：必须在关键环节调用真实接口，并对超时/失败做兜底处理
-     - 外部接口暂不明确时：必须先调用 mock 接口（本地 stub / fake service / mock server），并在调用点用 `TODO(external-api): <dependency_name> <purpose>` 做显式标记，后续可替换为真实调用
-   - 禁止跳过依赖：不能因为“没有接口”就不调用；必须做到“可运行的 mock 调用 + TODO 标记”
+     - 外部接口暂不明确时：必须先提供可运行的本地 stub / fake service / mock server，并确保后续可无侵入替换为真实实现
+   - 禁止跳过依赖：不能因为“没有接口”就不调用；必须做到“可运行的 mock 调用 + 明确的替换点（配置/实现类/注入方式）”
    - 依赖失败注入必须可测：
      - 至少为 1 个外部依赖提供失败注入开关（复用 `/tools/config` 或仓库既有配置），并在代码与测试中覆盖该失败路径
-4. 后端实现要求（按需裁剪）：
-   - 数据模型/迁移（不破坏既有迁移系统）
+5. 后端实现要求（按需裁剪）：
+   - 数据库落地（必须按 `/scheme.yaml`）：
+     - 必须根据 `selected.prototype_database` 生成可运行的数据库连接配置（如 Spring Boot 的 datasource 配置、连接池参数等，按仓库事实放置）
+     - 必须生成对应的数据库访问代码与落库方式：表结构 DDL/迁移脚本/SQL（按仓库事实选择 Flyway/Liquibase/手写迁移），并保证 Repository/DAO 的查询与表结构一致
+     - 若仓库使用 ORM：仍需明确关键查询的 SQL 语义（可通过 mapper/xml/@Query/查询构造器等方式体现），避免“只有模型没有可执行查询”
    - Service/Repository
    - Controller/API
+   - 代码组织（必须）：
+     - Model/Entity/DTO 必须“一个类型一个文件”，禁止把多个 model/DTO/实体放在同一个文件里集中声明（例如禁止 `Models.java` 内堆放所有实体）
+     - Exception 必须集中在同一目录/包下统一管理（例如 `.../exception` 或 `.../exceptions`），并提供统一的错误响应映射（全局异常处理/错误码到 HTTP 状态码映射）；禁止在各处随意定义零散异常类
    - RBAC + 数据权限校验（引用 `/specs/details/<module_slug>/rbac/<function_slug>.md` 与 `/specs/details/<module_slug>/data_permission/<function_slug>.md`）
    - 状态机流转与校验（引用 `validation_matrix.md`）
    - 日志/通知/MQ（引用对应矩阵与 `mq.md`）
-5. 前端实现要求（按需裁剪）：
+   - Java（Spring Boot）代码生成约束（`selected.prototype_backend_stack=java17_springboot3` 时必须）：
+     - 必须引入 Lombok 依赖并启用注解处理（Maven/Gradle 按仓库事实选择）
+     - 禁止为每个字段显式生成大量 getter/setter；必须优先使用 Lombok 注解（例如 DTO 用 `@Data/@Builder`，实体用 `@Getter/@Setter`，日志用 `@Slf4j`，构造器用 `@NoArgsConstructor/@AllArgsConstructor`）
+6. 前端实现要求（按需裁剪）：
    - 页面与路由入口（列表/详情/表单）
    - 表单校验与交互（引用 `/specs/details/<module_slug>/interaction/<function_slug>.md`、`/specs/details/<module_slug>/validation_matrix/<function_slug>.md`）
    - API 集成与错误处理
    - 权限控制到区域/控件级（引用 RBAC 产物）
-6. 启动与联调（必须，输出必须“可运行”而不是只生成代码片段）：
+7. 启动与联调（必须，输出必须“可运行”而不是只生成代码片段）：
    - 必须实现可启动的后端服务：
      - 提供可用的启动脚本（复用仓库既有脚本；如果不存在则补齐最小脚本）
      - 提供健康检查能力（例如 `/health` 或等价），用于本地联调与 CI 验证
@@ -56,7 +70,7 @@
      - 后端必须处理本地跨域/鉴权占位（按仓库约定），确保页面可以完成至少 1 条端到端主流程
    - 必须提供最小数据初始化能力：
      - 至少提供一套可复现的种子数据/fixture（按仓库习惯放置），保证“启动→打开页面→看到列表→可操作”能演示
-7. 自动化测试（必须，目标：全面覆盖验收口径）：
+8. 自动化测试（必须，目标：全面覆盖验收口径）：
    - 优先复用仓库既有测试框架与目录约定，禁止引入不必要的新框架
    - 测试覆盖必须与验收用例对齐：
      - 若存在 `/specs/acceptance/`：必须逐条映射到自动化测试用例（允许合并同类项，但必须说明映射关系并确保覆盖）
@@ -72,13 +86,15 @@
    - 必须确保测试可在项目现有脚本中运行：
      - 自动识别并执行仓库已有 `lint/typecheck/test/e2e` 脚本（名称不固定，需先探测）
      - 如需新增脚本，仅在缺失且必要时新增，并保持最小变更
-8. 代码写入策略：
-   - 代码写入位置必须限定在原型工程目录：只允许写入 `/specs/prototypes/` 之下；禁止在项目根目录额外新建 `backend/`、`server/`、`api/`、`frontend/` 等并列目录
-   - 若 `/specs/prototypes/` 不存在：必须先生成或补齐原型工程骨架（等价于先完成 `/vspec:verify` 的工程初始化），再在该目录内进行端到端实现
-   - 优先在 `/specs/prototypes/` 的既有模块内扩展，避免在其下新建不必要的目录
+9. 代码写入策略：
+   - 代码写入位置必须限定在 `/specs/` 之下；禁止在项目根目录额外新建 `backend/`、`server/`、`api/`、`frontend/` 等并列目录
+   - `/vspec:impl` 生成的后端代码必须放在 `/specs/backend/` 目录下（Controller/API、Service、Repository、Entity/DTO、配置、迁移、测试等）
+   - 前端代码放在 `/specs/prototypes/`（若原型工程已存在既有前端结构，则以既有结构为准）
+   - 若 `/specs/prototypes/` 不存在：必须先生成或补齐原型工程骨架（等价于先完成 `/vspec:verify` 的工程初始化），再进行端到端实现
+   - 优先复用 `/specs/prototypes/` 的既有模块与目录结构，避免新建不必要的目录
    - 不添加注释
    - 提交点保持可评审：按功能点分批次生成，确保每批可独立运行/编译
-9. 最终输出（必须可验证）：
+10. 最终输出（必须可验证）：
    - 至少完成 1-3 个核心功能点的端到端集成（优先 P0 主流程）
    - 同步更新或新增最小必要的路由、API、页面与权限点
    - 以可复现方式验证：