@double-codeing/flow2spec 2.2.2 → 3.0.7

package/templates/rules/implement-tech-design.mdc

@@ -1,177 +0,0 @@
----
-description: 当用户要求根据技术方案文档实现可运行代码时，按本规则执行（读文档、列任务、确认、实现、待完成列表与提醒）。用户会在对话中提供技术方案文档路径（MD 或 PDF）；若为 PDF，先按 f2s-doc-pdf 转为 MD 再继续。
-globs:
-  - "**/req-docs/**/*.md"
-alwaysApply: false
----
-> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
-
-# 基于技术方案实现代码
-
-当用户要求根据**技术方案文档**实现可运行代码时（用户会在对话中提供文档路径，如 **`配置根/req-docs/xxx技术方案.md`**、**`.cursor/req-docs/xxx.md`** 或 PDF 路径），按以下约定执行。
-
-**目录约定**：**`配置根/req-docs/`**（如 `.cursor/req-docs/`）放需要实现成代码的文档（技术方案等）；**`配置根/stock-docs/`** 放用于生成 Rules/Skills 的源文档，不用于「按方案实现代码」。技术方案路径请使用 **配置根下 `req-docs/`** 的 MD。
-
-**触发说明**：本规则在打开 **`req-docs/`** 目录下的 `.md` 文件时会自动加载（路径匹配 `**/req-docs/**/*.md`）。若对话前未打开技术方案文档，可在对话中 **@ 本规则文件**（如 `@implement-tech-design.mdc`）后再说明技术方案路径，即可生效。
-
-- **若用户提供的是 PDF 路径**：先读取并执行 `配置根/skills/f2s-doc-pdf/SKILL.md` 中的步骤（将 PDF 转为 MD 并保存到项目、可选补全流程说明），再以生成的 MD 路径作为技术方案，在同一轮对话中继续步骤 2～5。
-- **若用户提供的是 MD 或其它文本文档路径**：直接读取并理解技术方案，再按项目既有约定实现代码。
-
-遇文档未写清或需用户确认的项，主动向用户提问；若用户未给到答案，在完成后列出「待完成列表」供用户补齐。
-
----
-
-## 一、目标与原则
-
-- **目标**：根据技术方案文档中的需求概述、重点问题、配置说明、消息队列/定时任务流程图、重点流程、接口设计、错误码、表设计等，**实现可运行代码**（接口、消息队列消费、定时任务、数据模型、公共封装等），并符合**当前项目的目录与编码约定**。
-- **原则**：
-  1. **先列任务再动手**：完整读取并理解技术方案后，**先向用户列出「实现任务列表」**，再进入提问与实现；任务列表可根据方案内容增删，格式见下文「步骤 2.5」。
-  2. **先读后做**：实现顺序建议：表设计/模型 → 配置与枚举 → 核心逻辑与接口 → 消息队列/定时任务（若有）。
-  3. **对齐既有约定**：实现前先参考项目内已有约定（如 README、`配置根/stock-docs/`、`配置根/rules/`、架构说明等）中的接口约定、目录结构、技术栈用法，与现有模块风格一致。
-  4. **缺项即问**：文档未明确写出的、或存在多种合理实现方式的，**先向用户提问**；若用户暂未回答，先按合理默认或占位实现，并在最终**待完成列表**中列出该项。
-  5. **实现后提醒**：代码写完后，**必须**提醒用户在对应平台或环境中完成：配置中心（若使用）、消息队列（若使用）、数据库建表、API 网关/路由等（见下文「实现后提醒清单」）。
-
----
-
-## 二、技术方案中常见内容与实现对应关系
-
-| 技术方案章节 | 实现动作（按项目约定落地） |
-|--------------|----------------------------|
-| 需求概述、重点问题概述 | 理解业务目标与约束；在接口注释或 README 中体现；复杂逻辑加注释说明对应「重点问题」。 |
-| 配置说明 | 在**项目约定的配置注册处**（如配置中心 key 列表、环境变量、config 文件）注册；业务中按项目约定方式读取；**配置项名/Key 若文档未写清，向用户确认**。 |
-| 消息队列/流程图 | 在**项目约定的 MQ 定义处**定义 topic/subject 与消费映射；在**项目约定的消费代码目录**下写消费逻辑；在**项目约定的部署/订阅配置**中注册；**topic、group、确认方式等若文档未写清，向用户确认**。 |
-| 重点流程（图） | 对应到接口内或公共模块中的核心函数；关键分支与错误码与文档一致。 |
-| 定时任务/流程图 | 在**项目约定的任务代码目录**下写 job；在**项目约定的调度配置**（如 cron、云函数定时触发器、任务平台）中注册。 |
-| 接口设计 | 在**项目约定的接口/路由目录**下新增接口实现；在**项目约定的路由/网关配置**中声明路径与 handler；请求/返回与文档一致；**外部调用参数若文档未写清，向用户确认**。 |
-| 错误码 | 在**项目约定的错误码定义处**（如 constants、enum、i18n）定义；接口返回与文档一致。 |
-| 表设计（SQL 或表格） | 在**项目约定的数据模型/ORM 目录**下新增或复用模型；表名、字段与文档一致；**若文档仅给表结构未给库名/实例，向用户确认**。 |
-| **流程图** | 见下文「流程图与实现」。PDF 内嵌的流程图无法被直接解析，需用户配合提供后，再按图实现接口分支与顺序。 |
-
----
-
-### 流程图与实现（重要）
-
-技术方案中的**流程图**决定了接口内的**步骤顺序、判断分支和返回码**，必须按图实现。
-
-- **限制**：若技术方案是 **PDF**，或文档内流程图以**图片/矢量图**形式存在，AI 读取时**只能拿到文字，无法解析图中的节点、箭头与分支**，因此无法自动按流程图实现。
-- **当用户提供 PDF 时**：先按 f2s-doc-pdf 的步骤完成转 MD 与流程说明补全，实现时以该 MD 中的流程说明为准。
-- **当用户提供 MD 时**：若文档中已有「流程说明」等文字版步骤，直接按该步骤实现；若无，则向用户说明并请其提供流程图图片或文字步骤，可追加到该 MD 或同目录流程说明文档后再实现。
-- **实现时**：依据 MD 中的**流程说明**（或用户后续提供的图片解析结果），**严格按步骤顺序与分支**实现，并在关键分支处加简短注释（如 `// 流程图：xxx 判断`）。
-
----
-
-## 三、执行步骤
-
-### 步骤 1：若用户提供的是 PDF 路径——先执行 f2s-doc-pdf（必做）
-
-**仅当用户提供的路径指向 PDF 文件时执行本步骤**；若为 .md 或其它文本文档，跳过步骤 1，直接执行步骤 2。
-
-- 读取 `配置根/skills/f2s-doc-pdf/SKILL.md`，按其中所载步骤执行：将 PDF 转为 Markdown 并保存到项目、向用户提问获取流程图（可选）、将流程说明写入该 MD。
-- 执行完毕后，以本步骤生成的 **MD 文件路径** 作为技术方案文档，在同一轮对话中继续执行步骤 2～5。
-- 本规则内不重复描述 PDF 转 MD 的具体操作，以 f2s-doc-pdf 为准。
-
----
-
-### 步骤 2：读取技术方案与项目约定
-
-1. **读取技术方案文档**  
-   - 若步骤 1 已执行（用户提供的是 PDF）：读取步骤 1 中生成并保存的 **MD 文件**。  
-   - 若未执行步骤 1（用户提供的是 .md 或其它文本）：从配置根的父目录解析用户提供的路径，直接读取该文档。
-2. **读取项目约定**：若项目内有约定文档（如 README、`配置根/stock-docs/`、`配置根/rules/`、架构说明等），请读取，以便接口形式、目录结构、技术栈用法与现有项目一致。
-3. **提取并列表**：从技术方案中提取「需求概述、配置项、消息队列 topic 与消费（若有）、重点流程、接口列表、错误码、表结构」以及步骤 1 写入的流程说明（若执行了步骤 1），便于按项实现与核对。
-4. **流程图**：若文档中多处提到「流程」「流程图」但**没有文字版步骤**，在列出实现任务列表（步骤 2.5）后向用户说明并获取流程图或文字步骤，写入同目录下的流程说明或该 MD 后再实现；若用户暂不提供，可按文档现有内容实现，并在待完成列表中注明「流程图未补充，建议后续按图核对」。若步骤 1 已执行且已写入「流程说明」章节，则直接依据该章节实现。
-
-### 步骤 2.5：列出实现任务列表给用户（必做）
-
-在进入「向用户提问」或「动手写代码」之前，**必须**先向用户展示 **「实现任务列表」**，让用户清晰知道你将执行哪些任务。格式示例：
-
-```markdown
-## 实现任务列表（基于《xxx》技术方案）
-
-| 序号 | 任务项 | 说明 |
-|------|--------|------|
-| 1 | 表设计/模型 | 新增 xxx 表对应模型（路径按项目约定）；整理建表 SQL 供用户在库中执行。 |
-| 2 | 配置与枚举 | 在项目约定的配置处注册 xxx；在项目约定的错误码/枚举处定义错误码（与文档一致）。 |
-| 3 | 接口 | 新增接口 xxx、xxx，在项目约定的接口目录下实现，并在路由/网关配置中注册。 |
-| 4 | 消息队列 | 定义 topic/subject xxx，在项目约定的消费目录下实现消费逻辑，在部署/订阅配置中注册（若方案涉及）。 |
-| 5 | 定时任务 | 新增定时任务 xxx，在项目约定的调度配置中注册（若方案涉及）。 |
-| … | … | （按方案实际内容增删） |
-```
-
-- 任务项可根据技术方案实际内容**增删**。
-- 列出后可附带一句：「若以上任务列表无异议，我将按此顺序实现；若有需要补充或调整的请说明。」
-- **必须**接着执行步骤 3（列出并提问典型问题），**在用户回复或明确表示「先按默认/占位」之前，不进入步骤 4 写代码**。
-
-### 步骤 3：实现前——向用户确认的典型问题（必做，不可跳过）
-
-在进入步骤 4（动手写代码）之前，**必须**根据技术方案内容，将下列未写清的项整理为**向用户的提问**并一次性列出，请用户逐项回复或说明「暂不提供，先按默认/占位」。**未执行本步骤不得直接开始写代码。**
-
-以下项若**技术方案中未明确写出**，须在实现前**向用户提问**（可一次列多条）：
-
-- **配置**：配置项名称、所在配置中心/环境变量/文件的约定；配置中未写清的 key 或默认值。
-- **消息队列**（若方案涉及）：topic/subject、group、确认方式等；若有多个节点，每个的 topic/group；发送方与消费方的环境/region 是否一致。
-- **接口与外部依赖**：外部接口参数是否必传、传参格式；外部服务地址/接口契约若文档未写，请用户提供或说明从哪份配置/文档查阅；是否需要登录、登录态校验方式。
-- **数据库**：表所在库名/实例；若文档只给表结构未写库名，需确认；是否已有现成模型可复用，还是必须新建表。
-- **API 网关/路由**：本次新增的接口路径是否已在网关或路由中配置；若由你实现 handler，请提醒用户去配置访问权限与路由。
-- **流程图**：若文档内包含「流程」「流程图」但无文字版步骤，是否已附带流程图图片或文字版步骤并写入技术方案 MD？未提供时，先说明无法解析图中步骤，请用户补充后再按图实现；若用户选择暂不提供，则按文档现有内容实现并记入待完成列表。若步骤 1 已执行且已写入流程说明，无需再问。
-- **其他**：模块/活动目录命名约定；错误码是否与现有项目统一枚举一致；定时任务 cron 或调度配置的 name/desc 规范。
-
-**若用户对某条未回复或未在本次对话中回复**：先按合理默认或占位实现，并在最终**待完成列表**中写明「需用户确认：xxx」。若用户明确说「先按默认实现」「暂不提供」等，可视为同意按占位/默认处理，然后进入步骤 4。
-
-### 步骤 4：按顺序实现代码
-
-建议顺序（可根据方案内容增删）：
-
-1. **表设计 → 模型**：在项目约定的数据模型/ORM 目录下新增模型文件，表名、字段与文档一致；若文档给出 SQL，可整理为建表语句并写入 **`配置根/req-docs/`** 或注释，供用户在库中执行。
-2. **配置与枚举**：在项目约定的配置注册处注册配置名；在项目约定的错误码/枚举处定义错误码与文档一致。
-3. **接口**：在项目约定的接口/路由目录下新增接口文件；请求体/查询参数、返回体、错误码与文档「接口设计」一致；在项目约定的路由/网关配置中增加对应 handler 与路径。
-4. **消息队列**（若方案涉及）：在项目约定的 MQ 定义处定义 topic 及消费映射；在项目约定的消费代码目录下实现消费逻辑；在项目约定的部署/订阅配置中为该消费 handler 配置订阅。
-5. **定时任务**（若方案涉及）：在项目约定的任务代码目录下新增 job 文件；在项目约定的调度配置中注册。
-6. **公共逻辑**：若方案中有可复用逻辑，放在项目约定的公共模块目录（如 common、utils、service 等），与现有项目一致。
-
-实现时注意：使用项目已有的依赖、工具方法、错误码封装等，与现有代码风格一致；接口与消息队列中的错误返回与文档「错误码」一致；复杂分支或「重点流程」处加简短注释。
-
-### 步骤 5：实现后——待完成列表与提醒
-
-1. **待完成列表（必须输出）**  
-   对所有「实现前向用户确认过但用户未给到答案」的项，以及「依赖平台或人工操作」的项，在回复末尾整理为 **「待完成列表」**，格式示例：
-
-   ```markdown
-   ## 待完成列表（需用户/运维补齐）
-
-   - [ ] **配置**：配置项确认为 xxx，并在配置中心/环境变量中创建或更新。
-   - [ ] **消息队列**：topic / group / 确认方式已按占位实现，请在消息队列平台核对并修改（若使用）。
-   - [ ] **数据库**：执行 **`配置根/req-docs/xxx建表.sql`**（或见某注释）在目标库建表。
-   - [ ] **API 网关/路由**：为本次新增的接口路径配置访问权限与路由。
-   - [ ] **其他**：确认 xxx 参数/链接已在配置或环境中就绪。
-   ```
-
-   若用户已全部确认且无遗漏，可写「待完成列表：无」。
-
-2. **实现后提醒清单（必须提醒用户执行）**  
-   在回复中**明确列出**以下提醒，并说明「代码已按技术方案实现，以下需在对应平台或环境中由用户完成」：
-
-   - **配置中心/环境变量**（若使用）：请在配置中心或环境变量中创建/更新与代码中读取的配置名、key 一致的配置项。
-   - **消息队列**（若使用）：请在消息队列平台创建/核对 topic、group，确认消费组与确认方式等与代码一致。
-   - **数据库**：请在目标库执行建表 SQL（或按文档表设计建表），确保表名、字段、索引与模型一致。
-   - **API 网关/路由**：请为本次新增的接口路径在网关或路由中配置访问权限与路由，否则调用方无法访问。
-   - **其他**：若涉及风控、外部服务等，请确认参数与链接已在配置或环境中就绪。
-
----
-
-## 四、可选补充（由 AI 视情况执行）
-
-- **目录命名**：若技术方案未指定目录名，可建议与现有项目风格一致的命名方式。
-- **测试建议**：说明如何用 curl、Postman 或项目约定方式调接口、如何触发消息队列消费或定时任务，便于用户自测。
-- **与 f2s-ctx-build 联动**：若用户希望把本次技术方案纳入 Cursor 项目上下文，可提醒其将方案整理为符合《终稿模版》并保存至 **配置根/stock-docs/** 后，按 **f2s-ctx-build** 技能、以 `配置根/stock-docs/xxx.md` 为入参生成 Rules、Skills、文档索引。
-
----
-
-## 五、约束与小结
-
-- **PDF 先转 MD**：当用户提供 **PDF 路径** 时，先按 `配置根/skills/f2s-doc-pdf/SKILL.md` 执行，再以生成的 MD 继续步骤 2～5。
-- **路径**：技术方案等相对**配置根的父目录**书写（如 `.cursor/req-docs/xxx.md`）；文档推荐放在 **`配置根/req-docs/`**，具体以项目约定为准。
-- **遇疑必问**：实现过程中遇到文档未写清、或存在多种合理做法时，**必须先执行步骤 3**，将典型问题列出并向用户提问；用户未回复的，按占位/默认实现并记入待完成列表。**不得跳过步骤 3 直接写代码。**
-- **提醒必做**：实现完成后必须输出「待完成列表」和「实现后提醒清单」，确保用户知道还有哪些步骤需在平台或环境中完成。
-
-完成时用一句话总结：已基于《xxx》技术方案实现接口/模型/消息队列/定时任务等代码，并已列出待完成列表与平台/环境配置提醒，请按清单完成配置与建表等后续操作。

package/templates/rules/stock-docs-vs-req-docs.mdc

@@ -1,14 +0,0 @@
----
-description: 区分 配置根/stock-docs（存量上下文、生成 Rules/Skills）与 配置根/req-docs（需求与技术方案、按代码实现）；禁止混用路径与链出目标
-globs:
-  - "**/stock-docs/**/*.md"
-  - "**/req-docs/**/*.md"
-alwaysApply: false
----
-
-# stock-docs 与 req-docs
-
-- **`配置根/stock-docs/`**：PDF/初稿/终稿/架构说明等**存量源文档**；**f2s-ctx-build**、**f2s-doc-final**、**f2s-doc-arch**（架构初稿）、**f2s-doc-add**（**工作中**将**已落地能力**从多文件解析进上下文：初稿→终稿→Rules/Skills；与 f2s-doc-arch 分工不同）等技能的落盘（除 PDF→初稿等另有说明外）优先在此。Rule/Skill/docs-index 链出文档用 `../stock-docs/`、`../../stock-docs/`、`stock-docs/<文件名>.md`；`sourceDoc` 为 `<配置根>/stock-docs/<文件名>.md`。
-- **`req-docs/`**（**配置根**下，如 `.cursor/req-docs/`）：需求澄清、**后端技术方案**、f2s-doc-pdf 输出的「按方案实现」MD；`implement-tech-design` 的 globs 为 `**/req-docs/**/*.md`。
-
-完整约定与链接表见仓库 **`docs/README-目录与路径约定.md`**（包内说明；用户项目无此目录时以 init 写入的 **skills** 与 **rules** 为准）。