visual-spec 0.1.0

package/.trae/skills/starter-skill/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: "visual-spec-skill"
+description: "Analyzes raw requirements into visual specs and generates artifacts. Invoke when user runs /vspec:new for analysis or /vspec:verify for models and prototypes."
+---
+
+# Visual Spec Skill
+
+Analyzes visual specifications based on user input and turns brief business requests into structured requirement output.
+
+
+## When to Use
+
+Invoke this skill when:
+- Business side provided a very simple described requirements.
+- User runs `/vspec:new` to start a new requirement analysis flow.
+
+## What This Skill Defines
+
+- Fill in details based on scenario-based-facilitation method.
+- Design the data models.
+- Generate UI mockups based on the details filled in.
+- Generate business logic details in visual formats.
+
+## Commands
+
+### `/vspec:new`
+
+Use this command to create a new requirement analysis session.
+
+Flow:
+0. Ensure `/docs/` exists, and ensure subfolders exist:
+   - `/docs/legacy/`
+   - `/docs/current/`
+   - `/docs/change/`
+   - `/docs/refine/`
+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`.
+4. Use that prompt to analyze the requirement and expand the business context.
+5. Write the raw requirement and background analysis output to `/specs/background/original.md`.
+6. Ask the user to answer the questions from the `待确认问题` section.
+7. After the user replies, load `prompts/vspec_new/stakeholders.md` to analyze stakeholders.
+8. Write the stakeholder result to `/specs/background/stakeholder.md` (markdown table).
+9. Load `prompts/vspec_new/roles.md` to analyze system user roles (direct users) and their work tasks.
+10. Write the roles result to `/specs/background/roles.md`.
+11. Load `prompts/vspec_new/terms.md` to extract key terms and definitions.
+12. Write the terms result to `/specs/background/terms.md` (markdown table).
+13. Load `prompts/vspec_new/flows.md` to analyze business workflows and generate PlantUML swimlane diagrams.
+14. Write the diagrams to `/specs/flows/*.puml`.
+15. Load `prompts/vspec_new/scenarios.md` to enumerate business scenarios by node combinations.
+16. Write the scenarios result to `/specs/background/scenarios.md` (markdown table).
+17. Load `prompts/vspec_new/details_pre_post.md` to create per-node detail folders and generate `pre_post.md` for each node.
+18. Load `prompts/vspec_new/details_constraints.md` to generate `constraints.md` for each node.
+19. Load `prompts/vspec_new/details_variations.md` to generate `variations.md` for each node.
+20. Load `prompts/vspec_new/details_boundaries.md` to generate `boundaries.md` for each node.
+21. Load `prompts/vspec_new/details_symmetry.md` to generate `symmetry.md` for each node.
+22. Ensure the per-node outputs are written under `/specs/background/scenario_details/`.
+23. Load `prompts/vspec_new/dependencies.md` to analyze external dependency systems.
+24. Write the dependencies result to `/specs/background/dependencies.md`.
+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).
+29. Return the structured analysis result and continue to the next requirement-design step.
+
+### `/vspec:refine`
+
+Use this command to refine and update the requirement based on refine materials stored under `/docs/refine/`, or based on one or more input files/directories provided as command arguments.
+
+Flow:
+0. Ensure `/specs/details/` exists and is non-empty; if missing, stop and ask the user to run `/vspec:detail` first.
+1. Read refine inputs:
+   - If command arguments are provided, treat them as refine input sources (files/directories).
+   - Otherwise, read `/docs/refine/` (prefer `/docs/refine/file_list.md` as the entry if present; else read files in name order).
+2. Load `prompts/vspec_refine/refine.md` to apply the refinement, update the canonical requirement, and update impacted artifacts.
+3. Append the refinement result to `/specs/background/original.md`, and update impacted `/specs/details/` and `/specs/prototypes/` accordingly.
+
+### `/vspec:refine-q`
+
+Use this command to refine and update the requirement based on answered questions.
+
+Flow:
+1. Read `/specs/background/questions.md` and pick answered rows.
+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/`.
+
+### `/vspec:detail`
+
+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.
+   - Always generate the baseline docs:
+     - `rbac.md`: RBAC permissions down to page areas and controls.
+     - `data_permission.md`: data permission rules and scope.
+   - Page-only:
+     - `page_load.md`: page loading logic.
+      - `interaction.md`: page interaction logic.
+     - `validation_matrix.md`: validation logic in matrix format (only for submit-type pages/actions; if the page has no submit/save/approve/reject/cancel/change actions, skip).
+     - `post_submit_check.md`: checks after submit (if the page has submit).
+     - `post_submit_processing.md`: processing logic after submit (if the page has submit).
+     - `post_submit_navigation.md`: post-submit return and navigation (if the page has submit).
+   - Conditional (generate only if involved by the current function’s logic/scenarios/models/dependencies):
+     - `logging_matrix.md`: operation/audit logging (only when the business requires change history retention, compliance audit, or non-repudiation; otherwise skip).
+     - `decision_matrix.md`: decision matrix (决策矩阵) for operation availability under each status (if there is a status machine and operations vary by status/role).
+     - `notification_matrix.md`: notifications (if there is any notification requirement).
+     - `mq.md`: MQ topics/events/message schema/reliability details (if there is async events, queues, or cross-system eventing).
+     - `file_import.md`: file import details (if there is any import entry/requirement).
+     - `file_export.md`: file export details (if there is any export entry/requirement).
+     - `formula.md`: calculation formulas and metric semantics (if there are any calculations/metrics).
+     - `expression_tree.md`: expression tree (HTML) (if there is multi-level nested branching logic).
+     - `code_rules.md`: numbering/code generation rules (if any codes/serial numbers are generated/assigned).
+     - `judgemental_matrix.md`: judgemental matrix (判定矩阵) for multi-factor logic branching (if 2+ factors jointly decide outcomes).
+   - Module-level (generate at most once per module, and only if involved):
+     - `timeline.md`: time-axis visualization (HTML) for overall flow impact analysis (only when there is long time-span logic that affects flow decisions, e.g. effective/expiry, deadlines, grace periods, cross-day rules).
+      - `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:
+   - Per-function: `/specs/details/<module_slug>/<logic_type>/<function_slug>.(md|html)`
+   - Module-level: `/specs/details/<module_slug>/<logic_type>/overall.(md|html)`
+
+### `/vspec:qc`
+
+Use this command to run a quality check on the generated requirement artifacts under `/specs/`.
+
+Flow:
+1. Read built-in standard at `prompts/vspec_qc/quality_standard.md`.
+2. If a requirement quality error book exists under project `qc/`, generate/update project root `quality_standard.md` based on it.
+3. If project root `quality_standard.md` exists, merge it as supplementary/overriding standard.
+4. Load `prompts/vspec_qc/qc.md` and generate a non-conformance checklist.
+5. Write the report to `/specs/qc_report.md`.
+
+### `/vspec:accept`
+
+Use this command to generate acceptance test cases.
+
+Flow:
+1. Read `/specs/functions/*`, `/specs/background/scenarios.md`, `/specs/background/scenario_details/`, `/specs/background/roles.md`, `/specs/models/*.md`.
+2. Load `prompts/vspec_accept/accept.md` to generate acceptance test cases covering core flows, exceptions, boundary, permissions, and data scope.
+3. Write results to `/specs/acceptance/` (one subfolder per function) and generate an index at `/specs/acceptance/index.md`.
+
+### `/vspec:test`
+
+Use this command to generate automation test code based on acceptance cases and specs.
+
+Flow:
+1. Read `/specs/acceptance/`, `/specs/functions/*`, `/specs/details/`, and detect the existing test frameworks in the repository.
+2. Load `prompts/vspec_test/test.md` to generate automation tests using the existing frameworks and conventions.
+3. Write test code to the project test directories (or `/tests/` if no standard exists) and ensure it can run with existing scripts.
+
+### `/vspec:impl`
+
+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.
+
+### `/vspec:upgrade`
+
+Use this command to upgrade/retrofit requirements based on materials stored under `/docs/` (`/docs/legacy` for legacy system, `/docs/current` for new inputs), and regenerate the `/specs/` artifacts in the same structure as `/vspec:new`.
+
+Flow:
+1. Ensure the input entry file exists at `/docs/current/file_list.md`; if missing, generate it with the expected input list template.
+2. Read `/docs/current/file_list.md`, then read the listed sources under `/docs/` (typically `/docs/legacy/*`, `/docs/current/*`, optionally `/docs/templates/*`, `/docs/texts/*`, `/docs/assets/*`) in order and extract structured information (functions, dependencies, UI style, roles/permissions, technical spec).
+3. If `/specs/background/original.md` exists, treat it as the current canonical requirement and use it as baseline for diff (inherit/new/change/deprecate).
+4. Load `prompts/vspec_upgrade/upgrade.md` and generate/update artifacts under `/specs/`, reusing `/vspec:new` output conventions.
+5. Sync extracted technical spec into `/scheme.yaml` so it can be used by `/vspec:verify` and `/vspec:impl`.
+
+### `/vspec:change`
+
+Use this command to respond to requirement changes and update impacted artifacts.
+
+Flow:
+1. Read change inputs under `/docs/change/` (prefer `/docs/change/file_list.md` as the entry if present; if only `/docs/changes/` exists, read from there for compatibility).
+2. If the target repository is a git repo, create a pre-change snapshot commit before writing any updates, so diffs are reviewable.
+3. Read existing artifacts under `/specs/` (including `/specs/details/`, `/specs/models/`, `/specs/prototypes/`) if present.
+4. Load `prompts/vspec_change/change.md` to analyze impact and update affected documents, focusing on updating impacted module detail docs under `/specs/details/<module_slug>/`.
+5. Write updated artifacts and a change log to `/specs/change_log.md`.
+
+### `/vspec:plan`
+
+Use this command to break down requirements, estimate efforts, and schedule via a user story map.
+
+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`.
+4. Load `prompts/vspec_plan/schedule.md` to generate the schedule and delivery map.
+5. Write schedule HTML to `/specs/plan_schedule.html`.
+
+## Prompt Files
+
+- `prompts/vspec_new/background.md`: the prompt used right after `/vspec:new` receives the raw requirement.
+- `prompts/vspec_new/stakeholders.md`: the prompt used after the user answers `待确认问题` to generate `/specs/background/stakeholder.md`.
+- `prompts/vspec_new/roles.md`: the prompt used after stakeholder analysis to generate `/specs/background/roles.md`.
+- `prompts/vspec_new/terms.md`: the prompt used after roles analysis to generate `/specs/background/terms.md`.
+- `prompts/vspec_new/flows.md`: the prompt used after terms analysis to generate `/specs/flows/*.puml`.
+- `prompts/vspec_new/scenarios.md`: the prompt used after flows analysis to generate `/specs/background/scenarios.md`.
+- `prompts/vspec_new/details_pre_post.md`: the prompt used after scenarios analysis to generate per-node `pre_post.md` under `/specs/background/scenario_details/`.
+- `prompts/vspec_new/details_constraints.md`: the prompt used after Pre/Post to generate per-node `constraints.md` under `/specs/background/scenario_details/`.
+- `prompts/vspec_new/details_variations.md`: the prompt used after Constraints to generate per-node `variations.md` under `/specs/background/scenario_details/`.
+- `prompts/vspec_new/details_boundaries.md`: the prompt used after Variations to generate per-node `boundaries.md` under `/specs/background/scenario_details/`.
+- `prompts/vspec_new/details_symmetry.md`: the prompt used after Boundaries to generate per-node `symmetry.md` under `/specs/background/scenario_details/`.
+- `prompts/vspec_new/dependencies.md`: the prompt used after details analysis to generate `/specs/background/dependencies.md`.
+- `prompts/vspec_new/functions.md`: the prompt used after dependencies analysis to generate `/specs/functions/`.
+- `prompts/vspec_new/questions.md`: the prompt used after functions analysis to generate `/specs/background/questions.md`.
+- `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/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.
+- `prompts/vspec_detail/page_load.md`: the prompt used by `/vspec:detail` to generate page loading logic docs.
+- `prompts/vspec_detail/interaction.md`: the prompt used by `/vspec:detail` to generate page interaction logic docs.
+- `prompts/vspec_detail/timeline.md`: the prompt used by `/vspec:detail` to generate time-axis HTML docs.
+- `prompts/vspec_detail/formula.md`: the prompt used by `/vspec:detail` to generate formula docs.
+- `prompts/vspec_detail/expression_tree.md`: the prompt used by `/vspec:detail` to generate expression tree docs.
+- `prompts/vspec_detail/code_rules.md`: the prompt used by `/vspec:detail` to generate numbering/code rules docs.
+- `prompts/vspec_detail/judgemental_matrix.md`: the prompt used by `/vspec:detail` to generate decision matrix docs.
+- `prompts/vspec_detail/validation_matrix.md`: the prompt used by `/vspec:detail` to generate validation matrix docs.
+- `prompts/vspec_detail/post_submit_check.md`: the prompt used by `/vspec:detail` to generate post-submit checks docs.
+- `prompts/vspec_detail/post_submit_processing.md`: the prompt used by `/vspec:detail` to generate post-submit processing docs.
+- `prompts/vspec_detail/post_submit_navigation.md`: the prompt used by `/vspec:detail` to generate post-submit navigation docs.
+- `prompts/vspec_detail/mq.md`: the prompt used by `/vspec:detail` to generate MQ message design docs.
+- `prompts/vspec_detail/logging_matrix.md`: the prompt used by `/vspec:detail` to generate logging matrix docs.
+- `prompts/vspec_detail/notification_matrix.md`: the prompt used by `/vspec:detail` to generate notification matrix docs.
+- `prompts/vspec_detail/nfp.md`: the prompt used by `/vspec:detail` to generate non-functional requirements docs.
+- `prompts/vspec_detail/file_import.md`: the prompt used by `/vspec:detail` to generate file import docs.
+- `prompts/vspec_detail/file_export.md`: the prompt used by `/vspec:detail` to generate file export docs.
+- `prompts/vspec_detail/cron_job.md`: the prompt used by `/vspec:detail` to generate scheduled job docs.
+- `prompts/vspec_accept/accept.md`: the prompt used by `/vspec:accept` to generate acceptance test cases.
+- `prompts/vspec_test/test.md`: the prompt used by `/vspec:test` to generate automation test code.
+- `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_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`.
+
+## Suggested Workflow
+
+1. Install this skill.
+2. Run `/vspec:new`.
+3. Ask the user to input the original requirement and wait for Enter.
+4. Load `prompts/vspec_new/background.md` and start requirement analysis.
+5. Ask the user to answer `待确认问题`.
+6. Load `prompts/vspec_new/stakeholders.md` and generate `/specs/background/stakeholder.md`.
+7. Load `prompts/vspec_new/roles.md` and generate `/specs/background/roles.md`.
+8. Load `prompts/vspec_new/terms.md` and generate `/specs/background/terms.md`.
+9. Load `prompts/vspec_new/flows.md` and generate `/specs/flows/*.puml`.
+10. Load `prompts/vspec_new/scenarios.md` and generate `/specs/background/scenarios.md`.
+11. Load `prompts/vspec_new/details_pre_post.md` and generate per-node `pre_post.md` under `/specs/background/scenario_details/`.
+12. Load `prompts/vspec_new/details_constraints.md` and generate per-node `constraints.md` under `/specs/background/scenario_details/`.
+13. Load `prompts/vspec_new/details_variations.md` and generate per-node `variations.md` under `/specs/background/scenario_details/`.
+14. Load `prompts/vspec_new/details_boundaries.md` and generate per-node `boundaries.md` under `/specs/background/scenario_details/`.
+15. Load `prompts/vspec_new/details_symmetry.md` and generate per-node `symmetry.md` under `/specs/background/scenario_details/`.
+16. Load `prompts/vspec_new/dependencies.md` and generate `/specs/background/dependencies.md`.
+17. Load `prompts/vspec_new/functions.md` and generate `/specs/functions/`.
+18. Load `prompts/vspec_new/questions.md` and generate `/specs/background/questions.md`.
+19. Follow the generated analysis steps to continue the project.
+
+## Output Goal
+
+- Clarify business objective and core user scenario.
+- Identify key roles, page modules, and interaction flow.
+- Extract entities and main data fields.
+- Produce a visual-spec-oriented requirement draft for the next step.

package/.trae/skills/starter-skill/prompts/vspec_accept/accept.md

@@ -0,0 +1,52 @@
+你是一名资深测试分析师（偏业务验收）。你的任务是：基于现有需求分析产物，生成可直接用于验收的测试用例，并写入指定目录。
+
+输入信息包含：
+- 功能清单（`/specs/functions/*`）
+- 场景列表与节点（`/specs/background/scenarios.md`）
+- 需求细节（`/specs/background/scenario_details/` 或 `/specs/background/scenario_details.md`（旧版）与 `/specs/details/` 如存在）
+- 角色与任务（`/specs/background/roles.md`）
+- 数据模型（`/specs/models/*.md`）
+
+生成规则：
+1. 按“功能点”逐个生成用例；同一功能点至少覆盖：
+   - 主流程（正常路径）
+   - 异常/失败（校验失败、权限不足、依赖失败、并发冲突）
+   - 边界（上下限、空值、枚举边界、最大长度）
+   - 权限（RBAC：区域/控件级；数据权限：范围过滤）
+2. 用例描述要可执行：写清前置条件、操作步骤、期望结果、数据准备/清理。
+3. 用例编号规则：`<function_slug>-AT-###`
+4. 每个功能点输出一个 markdown 文件，并生成汇总索引。
+
+输出与写入要求：
+1. 输出目录：`/specs/acceptance/<function_slug>/`
+2. 文件名：`acceptance_cases.md`
+3. 索引文件：`/specs/acceptance/index.md`
+4. 每个功能点文件结构固定如下：
+
+# 验收用例：<模块>/<功能>/<子功能>
+
+## 覆盖范围
+- 关联场景：
+- 关键角色：
+- 关键数据对象：
+
+## 用例（表格）
+1. 用例必须且只能用 markdown 表格输出，不允许改成列表/分段叙述。
+2. 表头固定如下（字段名不得改动、不得增删列）：
+| 编号 | 场景 | 用例标题 | 前置条件 | 操作步骤 | 期望结果 | 数据准备 | 优先级（P0/P1/P2） | 类型（主流程/异常/边界/权限/数据权限） | 备注 |
+|:--|:--|:--|:--|:--|:--|:--|:--:|:--|:--|
+3. 单元格填充规则（必须）：
+   - 操作步骤：用 `1. ...<br/>2. ...` 的形式在同一单元格内按序号列出（不要拆成多段文本）
+   - 期望结果：用 `- ...<br/>- ...` 或 `1. ...<br/>2. ...` 的形式列出关键可验收点
+   - 前置条件/数据准备：尽量具体到角色、状态、关键字段取值与权限范围
+4. 每个功能点至少输出 12 条用例；若功能简单也不得少于 8 条。
+
+## 非功能性检查（如适用）
+- 性能：响应时间/导入导出耗时
+- 审计：日志/追踪
+- 通知：站内信/邮件/短信等
+
+索引文件输出格式（必须）：
+- `/specs/acceptance/index.md` 必须用 markdown 表格汇总所有功能点的用例文件入口：
+| 功能点 | 用例文件 | 覆盖要点 | P0 数量 | P1 数量 | P2 数量 |
+|:--|:--|:--|:--:|:--:|:--:|

package/.trae/skills/starter-skill/prompts/vspec_change/change.md

@@ -0,0 +1,40 @@
+你是一名资深产品经理 + 系统分析师。你的任务是：响应需求变更，做影响分析，并更新相关规格/模型/原型/测试产物，最后产出变更日志。
+
+输入信息包含：
+- 变更材料：`/docs/change/` 下的文件（必须读取并结构化；若仅存在 `/docs/changes/`，则兼容读取）
+- 用户提供的补充变更描述（如有）
+- 现有产物：`/specs/`（含 `/specs/models/`、`/specs/prototypes/`）
+
+执行步骤：
+0. 读取变更输入（必须）：
+   - 必须读取 `/docs/change/` 目录下的文件作为变更来源（若仅存在 `/docs/changes/`，则从 `/docs/changes/` 读取）
+   - 若存在 `file_list.md`：必须按其顺序逐个读取；否则按文件名排序读取
+   - 读取时必须抽取：变更背景、目标、影响范围、功能变更点、规则/字段变更、角色权限变更、接口/依赖变更、迁移/兼容性要求
+1. 更新前版本快照（必须）：
+   - 若当前项目处于 git 仓库中：在写入任何更新之前，必须先提交一次快照，以便清晰对比本次变更
+   - 快照提交要求：
+     - 提交内容：仅包含本次变更应用前的当前状态（禁止把本次变更的更新混入该提交）
+     - 提交信息建议：`chore: pre-change snapshot`（可附加变更编号/日期）
+2. 结构化变更输入（必须输出表格）：
+| 变更项 | 类型（新增/修改/删除） | 原行为/原规则 | 新行为/新规则 | 影响角色 | 影响数据对象 | 备注 |
+| --- | --- | --- | --- | --- | --- | --- |
+3. 影响分析（必须输出表格）：
+| 产物/模块 | 文件路径 | 影响类型（更新/新增/废弃） | 影响说明 | 风险 | 对应验收用例变更 |
+| --- | --- | --- | --- | --- | --- |
+4. 更新策略：
+   - 优先更新已有文件，避免不必要的新文件
+   - 对被废弃的规则/功能点，标记为废弃但保留可追溯
+   - 变更落地优先级：
+     - 优先更新 `/specs/details/<module_slug>/` 下受影响的明细规格（RBAC、数据权限、交互、校验矩阵、决策矩阵、状态机等）
+     - 若变更影响功能清单/场景：同步更新 `/specs/functions/*` 与 `/specs/background/scenarios.md`
+     - 若变更影响数据结构：同步更新 `/specs/models/*.md`
+     - 若变更影响原型：同步更新 `/specs/prototypes/`
+5. 产出变更日志（写入 `/specs/change_log.md`，表头固定）：
+| 日期 | 变更摘要 | 影响范围 | 产物更新清单 | 待确认问题 |
+| --- | --- | --- | --- | --- |
+6. 若变更影响到测试：
+   - 更新 `/specs/acceptance/` 中相关用例
+   - 标记受影响的自动化测试用例编号
+
+输出写入：
+- 更新相关规格文件并写入 `/specs/change_log.md`

package/.trae/skills/starter-skill/prompts/vspec_detail/code_rules.md

@@ -0,0 +1,32 @@
+你是一名资深系统分析师 + 后端架构师。你的任务是：针对“单个功能点”（页面或非页面），输出涉及“生成编号/单号/流水号/编码”的规则与实现约束，确保编号唯一、可追溯、可扩展，并写入指定的输出文件。
+
+输入信息（由上游提供）：
+- 当前功能点：模块/功能/子功能/说明（来自 `/specs/functions/*`）
+- 术语与口径（`/specs/background/terms.md`）
+- 场景与流程（`/specs/flows/*.puml`、`/specs/background/scenarios.md`、`/specs/background/scenario_details/` 或 `/specs/background/scenario_details.md`（旧版））
+- 外部依赖（`/specs/background/dependencies.md`）
+
+适用性判断：
+- 若该功能点不涉及任何编号生成（包括：单据号、编码、批次号、任务号、审批号、对账号、发票/收据号等），输出“本功能无编号规则：不适用”，并给出 1 句话依据即可。
+
+产出要求（涉及编号生成时必须全部满足）：
+1. 编号清单（必须，用表格）：
+| 编号类型 | 使用场景 | 编号格式（模板） | 组成段说明 | 生成时机 | 唯一性范围 | 递增与重置规则 | 并发与一致性 | 回收/作废规则 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+2. 编号策略偏好（必须遵守）：
+   - 优先选择“顺序号/递增序列”（例如按日重置的流水号、全局递增、按租户递增、号段递增），不要优先选随机号（UUID/随机串）。
+   - 仅在确有必要时才使用随机号（例如离线生成、跨机房强一致不可用、需要不可预测性等），且必须写明原因与替代方案（例如“顺序号 + 防枚举保护”）。
+2. 编号格式必须明确到“每一段”：
+   - 固定前缀、业务线/组织/地区段、日期段（yyyyMMdd/yyMM 等）、序列段（位数、补零）、校验位（如有）
+3. 唯一性与并发必须可落地：
+   - 唯一性范围：全局/按租户/按组织/按业务线/按日期段等
+   - 并发策略：数据库唯一约束、乐观锁、号段（segment）、分布式 ID、缓存预取等（选择其一并给出理由）
+   - 失败处理：冲突重试、超时、依赖不可用时的降级策略（如依赖外部编码服务）
+4. 重置与回收必须有边界：
+   - 是否允许重置（按日/月/年/不重置）、重置点的时间口径与时区
+   - 作废单据是否占号、是否允许回收复用（默认不允许；若允许必须说明风险与审计要求）
+5. 安全与合规：
+   - 编号是否包含敏感信息（人员、手机号等）；如有必须脱敏或改用映射段
+
+输出写入：
+- 将结果写入上游指定的 markdown 文件路径（通常在 `/specs/details/<module_slug>/code_rules/<function_slug>.md`）

package/.trae/skills/starter-skill/prompts/vspec_detail/cron_job.md

@@ -0,0 +1,24 @@
+你是一名资深系统分析师。你的任务是：针对“当前模块”，汇总输出所有定时任务/批处理/后台作业的规格；若该模块无任何定时任务，输出单行：`SKIP`。结果写入指定的输出文件。
+
+输入信息（由上游提供）：
+- 当前模块：模块名 + 该模块下功能点清单（来自 `/specs/functions/*`，其中可能包含 job/batch/cron）
+- 数据模型（`/specs/models/*.md`）
+- 外部依赖（`/specs/background/dependencies.md`）
+- 日志/通知要求（如有）
+
+产出要求（必须）：
+1. 输出中只包含“定时任务模块”的内容，不要输出其他无关模块或长篇解释。
+2. 每个定时任务用同一套 markdown 表格输出（必须严格用两列：参数/数据；对齐行必须为 `|:--|:--|`），字段固定如下：
+| 参数 | 数据 |
+|:--|:--|
+| 编号 | {JOB-001...} |
+| 名称 | {中文名（英文key）} |
+| 启动时间 | {首次启动时间/运行窗口/时区} |
+| 启动周期 | {cron 表达式/固定间隔/事件触发说明} |
+| 主要逻辑 | {用 3~7 条要点概括处理流程与输入输出/关键数据变更} |
+| 日志处理 | {关键日志点 + 关键字段（trace_id/job_run_id/biz_id 等）+ 日志级别} |
+| 出错处理 | {失败重试/退避/DLQ(如有)/补偿/人工介入/告警通知} |
+3. 若同一模块有多个任务，按任务分段输出（可用二级标题 `## {名称}`），每段仅包含上述表格，不要额外追加其他表格结构。
+
+输出写入：
+- 将结果写入上游指定的 markdown 文件路径（通常在 `/specs/details/<module_slug>/cron_job/overall.md`）

package/.trae/skills/starter-skill/prompts/vspec_detail/data_permission.md

@@ -0,0 +1,30 @@
+你是一名资深业务分析师 + 数据治理专家。你的任务是：针对“单个功能点”，输出数据权限设计（行/列/范围/状态/组织等维度），并写入指定的输出文件。
+
+输入信息（由上游提供）：
+- 当前功能点：模块/功能/子功能/说明（来自 `/specs/functions/*`）
+- 角色与组织结构假设（`/specs/background/roles.md`）
+- 数据模型（`/specs/models/*.md`）
+- 场景与流程（`/specs/background/scenarios.md`、`/specs/background/scenario_details/` 或 `/specs/background/scenario_details.md`（旧版））
+
+产出要求：
+1. 明确该功能点涉及的数据对象（实体/表），以及主要操作（读/新建/编辑/审批/删除/导出）。
+2. 必须以“矩阵表”输出数据权限（重点是范围/可见性/可操作性），要求如下：
+   - 纵轴：角色（来自 `/specs/background/roles.md`）
+   - 横轴：数据（以“数据对象”为主；如需区分，可在列名中附加关键视图/操作，例如“申请单(列表/详情)”或“行程明细(编辑)”）
+   - 单元格：仅用符号表示范围
+3. 符号含义（必须逐字使用）：
+   - `○` 全部
+   - `□` 仅自己的
+   - `△` 自己及下属
+   - `-` 无权限
+4. 输出最少包含 1 张矩阵表：
+   - 表 1：读范围矩阵（必须）
+5. 若本功能点存在“写入/操作”且其范围与读取不同，再补充第 2 张矩阵表：
+   - 表 2：操作范围矩阵（按需；操作包含 新建/编辑/审批/删除/导出 中与本功能点相关的部分）
+6. 规则补充（必须，避免只有矩阵无法落地）：
+   - 给出每一列“数据”的判定口径（1~2 句/列）：什么叫“自己的”、下属口径如何定义、组织/项目/城市等维度如何参与过滤、不同状态是否变化
+   - 给出最小可实现的过滤表达式示例（按需列出 3~6 条即可）：例如 `record.owner_id == current_user.id`、`record.org_path startsWith current_user.org_path`、`record.approver_ids contains current_user.id`
+7. 若与 RBAC 权限点存在组合关系（先通过 RBAC 再做数据权限过滤），必须写明顺序与失败行为（无权限提示/空列表/字段置灰）。
+
+输出写入：
+- 将结果写入上游指定的 markdown 文件路径（通常在 `/specs/details/<module_slug>/data_permission/<function_slug>.md`）

package/.trae/skills/starter-skill/prompts/vspec_detail/decision_matrix.md

@@ -0,0 +1,38 @@
+你是一名资深业务分析师 + 系统分析师。你的任务是：针对“单个功能点”（页面或非页面），把“状态机下的可操作性”用“决策矩阵”表达清楚，避免遗漏哪些操作在哪些状态可用，并写入指定的输出文件。
+
+输入信息（由上游提供）：
+- 当前功能点：模块/功能/子功能/说明（来自 `/specs/functions/*`）
+- 场景与流程（`/specs/flows/*.puml`、`/specs/background/scenarios.md`、`/specs/background/scenario_details/` 或 `/specs/background/scenario_details.md`（旧版））
+- 角色与权限（`/specs/background/roles.md`、RBAC 产物如有）
+- 数据模型与状态机（`/specs/models/*.md`，以及本功能点相关的 status 字段枚举）
+- 交互与提交后处理细节（如有：interaction/post_submit_*）
+
+适用性判断（必须）：
+- 若本功能点没有任何“状态驱动的操作可用性差异”（例如无 status 字段，或所有操作不受状态影响），输出单行：`SKIP`
+
+产出要求（必须）：
+1. 先列出“状态列表”（必须）：
+   - 只列出本功能点会用到的状态（来自模型/流程/交互），按流程顺序排列
+2. 再列出“操作列表”（必须）：
+   - 只列出本功能点在 UI/接口层真实存在的用户操作与系统操作
+   - 操作必须使用动词开头（例如：提交、撤回、取消、变更、审批通过、驳回、开始执行、结束执行、紧急叫停、导出、导入、分配资源 等）
+3. 输出“决策矩阵”表格（必须，严格格式）：
+   - 表头（横轴）是状态列表
+   - 左侧（纵轴）是操作列表
+   - 矩阵单元格仅用符号表示是否允许：
+     - `√`：在该状态下允许执行该操作
+     - `-`：在该状态下不允许执行该操作
+4. 若角色会影响可操作性（常见于审批/执行/管理后台），必须按角色分别输出矩阵：
+   - 用二级标题分段：`## {角色}`
+   - 每段只输出 1 个矩阵表
+5. 结果必须可落地：
+   - 任一 `√` 必须能在原型/实现中体现为按钮可用或接口允许；任一 `-` 必须体现为隐藏/置灰/拦截并提示
+
+表格模板（必须逐字遵守；仅填充状态列名与单元格符号，不要新增列）：
+| 操作 \\ 状态 | {状态1} | {状态2} | {状态3} |
+|:--|:--:|:--:|:--:|
+| {操作1} | √ | - | - |
+| {操作2} | - | √ | - |
+
+输出写入：
+- 将结果写入上游指定的 markdown 文件路径（通常在 `/specs/details/<module_slug>/decision_matrix/<function_slug>.md`）

package/.trae/skills/starter-skill/prompts/vspec_detail/expression_tree.md

@@ -0,0 +1,44 @@
+你是一名资深系统分析师。你的任务是：针对“单个功能点”（页面或非页面），当业务逻辑存在多层嵌套判定（AND/OR/NOT、优先级、短路、默认分支）时，用“表达式树”把逻辑结构表达清楚，避免文字描述造成歧义，并写入指定的输出文件。
+
+输入信息（由上游提供）：
+- 当前功能点：模块/功能/子功能/说明（来自 `/specs/functions/*`）
+- 场景与流程（`/specs/flows/*.puml`、`/specs/background/scenarios.md`、`/specs/background/scenario_details/` 或 `/specs/background/scenario_details.md`（旧版））
+- 角色与权限（`/specs/background/roles.md`、RBAC 产物如有）
+- 数据模型（`/specs/models/*.md`）
+
+适用性判断：
+- 若本功能不存在多层嵌套判定（可用简单规则或单层 if 说明清楚），输出“本功能无需表达式树：不适用”，并给出 1 句话依据即可。
+
+产出要求（涉及表达式树时必须满足）：
+1. 条件与原子表达式定义（必须，用表格）：
+| 代号 | 原子条件（不可再拆） | 取值来源 | 示例 | 备注 |
+| --- | --- | --- | --- | --- |
+
+2. 表达式树（必须，用固定 ASCII 树格式；不要用 mermaid，不要用图片）：
+   - 每个内部节点必须标明：运算符（AND/OR/NOT）或 IF/ELSE 分支
+   - 每个叶子节点必须标明：命中的结果（走向/动作/结果）
+   - 固定格式示例（必须按此风格输出）：
+
+```text
+表达式树：{逻辑名称}
+ROOT
+├─ IF {条件组合/运算符节点}
+│  ├─ THEN {走向/动作/结果}
+│  └─ ELSE {下一个判定/兜底}
+└─ DEFAULT {默认走向/动作/结果}
+```
+
+3. 叶子结果表（必须，用表格，便于验收覆盖）：
+| 结果ID | 命中条件（引用代号 + AND/OR/NOT） | 走向/动作/结果 | 优先级 | 备注 |
+| --- | --- | --- | --- | --- |
+
+4. 冲突与优先级（必须）：
+   - 若可能同时命中多个结果，必须给出优先级规则（例如：权限拦截优先于状态机；异常优先于正常；越具体优先于越泛化）
+   - 必须包含 DEFAULT 兜底结果
+
+输出写入：
+- 输出必须为完整的 HTML 文档（可直接浏览器打开），并包含必要的内联样式（不要引用外部资源）。
+- 页面结构要求（必须）：
+  - 标题：功能点名称 + “表达式树”
+  - 三个区域：条件表 / 表达式树（用 `<pre>` 保留等宽布局）/ 叶子结果表 + 冲突与优先级
+- 将结果写入上游指定的 HTML 文件路径（通常在 `/specs/details/<module_slug>/expression_tree/<function_slug>.html`）

package/.trae/skills/starter-skill/prompts/vspec_detail/file_export.md

@@ -0,0 +1,25 @@
+你是一名资深系统分析师。你的任务是：当“单个功能点涉及文件导出”时，输出文件导出的详细规格；若不涉及，输出“不涉及导出”即可。结果写入指定的输出文件。
+
+输入信息（由上游提供）：
+- 当前功能点：模块/功能/子功能/说明（来自 `/specs/functions/*`）
+- 数据模型（`/specs/models/*.md`）
+- 数据权限规则（如有）
+
+产出要求（涉及导出时）：
+1. 导出场景：入口位置（列表/详情/报表）、导出目的（对账/留档/分析）
+2. 导出范围：当前筛选/选中记录/全量（需结合数据权限）
+3. 文件格式：xlsx/csv/pdf（如适用），编码，大小限制，超时策略
+4. 导出字段清单（必须用表格）：
+| 列名 | 字段映射 | 类型 | 是否脱敏 | 说明 | 备注 |
+| --- | --- | --- | --- | --- | --- |
+5. 排序/分页/分片策略：
+   - 大数据导出：异步任务、分片、生成后下载链接、有效期
+6. 审计与风控：
+   - 是否记录导出日志（引用 logging_matrix）
+   - 是否需要二次确认/审批
+7. 失败与降级：
+   - 超时、部分失败、文件生成失败
+   - 重试与通知策略
+
+输出写入：
+- 将结果写入上游指定的 markdown 文件路径（通常在 `/specs/details/<module_slug>/file_export/<function_slug>.md`）