@dev-workflow/skill 0.1.0

package/skills/execution/devFlow/domains/backend/references/api-tech.md

@@ -0,0 +1,173 @@
+# api-tech 子命令
+
+`api-tech` 生成后端技术方案文档。它不是仓库调研报告，不是项目入门说明，不是开发排期，也不生成后端代码骨架（不产出
+controller / service / dto / entity 代码文件）。
+
+## 代码事实优先
+
+- 后端仓库可用时，接口、实体、schema 必须基于真实代码；写清具体文件路径与关键片段引用。
+- 后端仓库不可用时，不写具体文件路径，不声称某资源存在，涉及具体接口 / 表的字段一律标记为待确认。
+- 飞书 PRD / 需求与仓库代码冲突时，保留冲突并写入「风险与待确认项」，不擅自二选一。
+
+## 工作流程
+
+1. 收集上下文：PRD / 需求（优先用 `lark-read` 读取飞书文档）、可用的后端仓库代码。
+2. 确认章节：必写章节自动纳入；可选章节逐项让用户勾选。
+3. 用 `domains/backend/templates/api-tech.md` 作为骨架，只生成必写 + 选中可选章节。
+4. 生成正式文档时删除模板中的 HTML 注释（含【必写】/【可选】标记）。
+5. 生成后运行交付前自检。
+
+## 选择式骨架
+
+必写章节（总是生成）：
+
+- 接口设计
+- 数据模型 / 数据库设计
+- 核心流程 / 时序
+- 边界与异常
+- 风险与待确认项
+
+可选章节（由用户勾选，未选不生成、不写“不涉及”占位）：
+
+- 背景与目标
+- 范围与非目标
+- 依赖与非功能性
+- 完成标准
+
+启动时先列出上述清单让用户确认要包含哪些可选章节，再生成。
+
+## 标题与编号硬规则
+
+- 分节一律用原生 Markdown 标题：章 `#`、节 `##`、小节 `###`，最多三级。
+- **不写编号**：飞书「标题自动编号」是文档级 UI 显示开关、Open API 不可设置；也不要手写序号。需要编号时由用户在文档里开启。
+
+## 排版与飞书呈现规范（定稿模板）
+
+排版遵循 [tools/lark/references/lark-doc.md](../../../../../../tools/lark/references/lark-doc.md) 的「排版与飞书呈现规范（定稿模板）」。以下为 `api-tech` 在通用规则之上追加的硬规则。
+
+## 数据结构硬规则
+
+实体 / 表用「字段表格 + TypeScript interface」双给：
+
+- 字段表格列固定：字段、类型、必填、说明（默认 / 约束并入说明，保持 4 列、行矮）。
+- 实体说明（collection、extends 等）写在表格上方的**引用块** `> …`。
+- TypeScript interface：可空字段用 `?`，时间等注明单位（如 `// epoch ms`）。
+
+## 接口呈现硬规则
+
+接口设计章节每个接口条目按以下结构、label 全部加粗：
+
+1. **用途**：用 bullet 列出能力点（多能力时），不写成一长段。
+2. **入参**：4 列表格（参数、类型、必填、说明）**+** TypeScript DTO interface。
+3. **出参**：TypeScript data interface（描述 `data` 结构），不贴 JSON 示例。
+4. **说明**：用 bullet 列要点（副作用、事务、mock 口径等）。
+5. **错误码**：内联文本，如 `` `40001` 参数校验失败 ｜ `40301` 登录态失效 ``；有业务码则补全。
+
+## 章节规则
+
+- 接口设计：先用引用块写统一约定（方法、Content-Type、返回体、鉴权、时间单位），再逐接口按上面的接口呈现硬规则写。
+- 数据模型 / 数据库设计：每个实体 / 表给字段表格 + TS，并说明索引与 migration 影响；仓库可用时基于真实 entity /
+  schema，不可用时标记为待确认。
+- 核心流程 / 时序：业务流程超过 4 步或多服务调用时画 Mermaid（`sequenceDiagram` /
+  `flowchart`），说明事务边界与幂等 / 并发。
+- 边界与异常：覆盖空数据、失败、无权限、重复提交、并发冲突、部分数据缺失、回滚 / 重试 / 降级。
+- 风险与待确认项：必写，收敛 PRD / 接口 / 仓库代码冲突，每条具体到可直接提问。
+
+## Mermaid 风格规则
+
+Mermaid 图必须提高技术评审效率，不做装饰。生成时优先保证语义清晰，其次保证层次和可读性。
+
+### sequenceDiagram 调用链模板
+
+接口调用链、多服务协作、前后端链路默认用 `sequenceDiagram`，并遵守：
+
+- 开头使用 `autonumber`。
+- 用户端用 `actor`，系统和服务用 `participant`。
+- participant 别名使用业务可读名称，例如 `supplier-portal · 前端`、`supplier-server · 门户后端`。
+- 按业务阶段使用 `rect rgb(...)` 分组，每个阶段用 `Note over` 写清阶段名和边界。
+- 阶段颜色使用柔和浅色，推荐：
+  - 蓝色 `rgb(219, 234, 254)`：入口 / 登录 / 初始化。
+  - 黄色 `rgb(254, 243, 199)`：填写 / 暂存 / 草稿。
+  - 绿色 `rgb(220, 252, 231)`：提交 / 成功 / 主链路完成。
+  - 紫色 `rgb(243, 232, 255)`：审核 / 回流 / 异步状态。
+  - 红色 `rgb(254, 226, 226)`：失败 / 驳回 / 异常分支。
+- 每个阶段 4-8 条交互为宜；超过 8 条时拆阶段，不把所有细节堆进一块。
+- 消息文案写业务动作和关键接口名，不写长 JSON。
+- 必须表达信任边界、签名验签、事务边界、状态机、回调 / pull 模式等关键架构约束。
+
+示例结构：
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor U as 用户浏览器
+  participant FE as xxx-portal · 前端
+  participant BE as xxx-server · 后端
+  participant AD as admin-be · 管理后台
+
+  rect rgb(219, 234, 254)
+  Note over U,BE: 阶段 1 · 入口 / 登录（止于门户）
+  U->>FE: 进入页面
+  FE->>BE: check-session
+  BE-->>FE: { profileStatus }
+  end
+
+  rect rgb(220, 252, 231)
+  Note over U,AD: 阶段 2 · 提交（后端签名访问管理后台）
+  U->>FE: 点击提交
+  FE->>BE: submit-profile
+  BE->>AD: AdminClient.submit（x-signature 验签）
+  AD-->>BE: { auditStatus: PENDING }
+  BE-->>FE: SUBMITTED
+  end
+```
+
+### flowchart 业务流程模板
+
+事务分支、幂等、异常处理、状态判断默认用 `flowchart TD`，并遵守：
+
+- 使用 `subgraph` 表达层次：入口、校验、核心处理、外部依赖、结果。
+- 节点文本保持短句，复杂规则放正文，不塞进节点。
+- 使用 `classDef` 区分类型：入口/成功/风险/外部依赖。
+- 分支条件写在连线上，避免多个菱形连续堆叠。
+
+示例结构：
+
+```mermaid
+flowchart TD
+  classDef entry fill:#dbeafe,stroke:#60a5fa,color:#1e3a8a
+  classDef success fill:#dcfce7,stroke:#22c55e,color:#14532d
+  classDef warn fill:#fef3c7,stroke:#f59e0b,color:#78350f
+  classDef risk fill:#fee2e2,stroke:#ef4444,color:#7f1d1d
+
+  A[接收提交请求]:::entry --> B{幂等键存在?}
+  B -->|是| C[返回已有处理结果]:::warn
+  B -->|否| D[参数与权限校验]
+  D --> E{校验通过?}
+  E -->|否| F[返回业务错误码]:::risk
+  E -->|是| G[开启事务并写入主表]
+  G --> H[提交事务]:::success
+```
+
+### 图放在哪些章节
+
+- `核心流程 / 时序`：至少保留一张 Mermaid 图。主链路优先 `sequenceDiagram`；存在复杂分支时补充 `flowchart TD`。
+- `数据模型 / 数据库设计`：只有实体关系复杂时补充 `erDiagram`，不要替代表格 + TypeScript。
+- `边界与异常`：异常路径多于 3 类时可补充异常流程 `flowchart TD`。
+- `依赖与非功能性`：存在 MQ、缓存、第三方服务、回调 / pull 策略时可补充依赖链路图。
+
+## 飞书上下文规则
+
+如果用户提供飞书 PRD / 设计 / 接口链接，必须先用 `lark-read`
+读取并结构化，再写方案；不得只凭链接标题或转述猜测。读取失败时停止依赖该文档的生成并说明原因。飞书内容与仓库代码冲突时写入风险与待确认项。
+
+## 交付前自检
+
+落地为 Markdown 文件后运行：
+
+```bash
+node .agent/skills/devFlow/domains/backend/scripts/check_api_tech_doc.mjs --file <markdown-file> --optional "<本次选中的可选章节，逗号分隔>"
+```
+
+自检覆盖：必写章节齐全、选中可选章节存在、数据模型含表格 + TS、接口设计含表格与 TS 代码块、核心流程含
+Mermaid、风险与待确认项非空、标题为 `#`/`##`/`###` 且无手写序号。脚本输出 JSON，最终回复只摘必要状态。

package/skills/execution/devFlow/domains/backend/scripts/check_api_tech_doc.mjs

@@ -0,0 +1,170 @@
+import { readFileSync } from 'node:fs'
+
+const REQUIRED_SECTIONS = [
+  '接口设计',
+  '数据模型 / 数据库设计',
+  '核心流程 / 时序',
+  '边界与异常',
+  '风险与待确认项'
+]
+
+const OPTIONAL_SECTIONS = ['背景与目标', '范围与非目标', '依赖与非功能性', '完成标准']
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function hasSection(markdown, title) {
+  return new RegExp(`^#{1,3}\\s+${escapeRegExp(title)}\\s*$`, 'm').test(markdown)
+}
+
+function getSection(markdown, title) {
+  const pattern = new RegExp(`^(#{1,3})\\s+${escapeRegExp(title)}\\s*$`, 'm')
+  const match = pattern.exec(markdown)
+  if (!match) return ''
+
+  const level = match[1].length
+  const start = match.index + match[0].length
+  const rest = markdown.slice(start)
+  const lines = rest.split('\n')
+  const collected = []
+
+  // 收集到下一个同级或更高级标题为止，保留章节内的 ## / ### 子节内容。
+  for (const line of lines) {
+    const heading = /^(#{1,6})\s+/.exec(line)
+    if (heading && heading[1].length <= level) break
+    collected.push(line)
+  }
+
+  return collected.join('\n')
+}
+
+function hasTable(section) {
+  return /\|.+\|\s*\n\|[\s:|-]+\|/.test(section)
+}
+
+function hasTsBlock(section) {
+  return /```(typescript|ts)[\s\S]*?```/.test(section)
+}
+
+function hasMermaid(section) {
+  return /```mermaid[\s\S]*?```/.test(section)
+}
+
+export function checkApiTechDoc(markdown, options = {}) {
+  const optional = options.optional || []
+  const issues = []
+
+  for (const title of REQUIRED_SECTIONS) {
+    if (!hasSection(markdown, title)) {
+      issues.push(`缺少必写章节：${title}`)
+    }
+  }
+
+  for (const title of optional) {
+    if (!OPTIONAL_SECTIONS.includes(title)) {
+      issues.push(`未知可选章节名：${title}`)
+      continue
+    }
+    if (!hasSection(markdown, title)) {
+      issues.push(`已选可选章节缺失：${title}`)
+    }
+  }
+
+  const apiSection = getSection(markdown, '接口设计')
+  if (apiSection) {
+    if (!hasTable(apiSection)) {
+      issues.push('接口设计缺少入参表格')
+    }
+    if (!hasTsBlock(apiSection)) {
+      issues.push('接口设计缺少 TypeScript 代码块（入参 DTO / 出参 data 结构）')
+    }
+  }
+
+  const modelSection = getSection(markdown, '数据模型 / 数据库设计')
+  if (modelSection) {
+    if (!hasTable(modelSection)) {
+      issues.push('数据模型缺少字段表格')
+    }
+    if (!hasTsBlock(modelSection)) {
+      issues.push('数据模型缺少 TypeScript 代码块')
+    }
+  }
+
+  const flowSection = getSection(markdown, '核心流程 / 时序')
+  if (flowSection && !hasMermaid(flowSection)) {
+    issues.push('核心流程 / 时序缺少 Mermaid 图')
+  }
+
+  const riskSection = getSection(markdown, '风险与待确认项')
+  if (riskSection && riskSection.trim().length < 10) {
+    issues.push('风险与待确认项为空')
+  }
+
+  const lines = markdown.split('\n')
+  let inFence = false
+  for (const line of lines) {
+    if (/^```/.test(line)) {
+      inFence = !inFence
+      continue
+    }
+    if (inFence) continue
+
+    const heading = /^(#{1,6})\s+(.+?)\s*$/.exec(line)
+    if (!heading) continue
+
+    if (heading[1].length > 3) {
+      issues.push(`标题层级超过三级（飞书仅支持 H1-H3）：${line.trim()}`)
+    }
+    if (/^\s*\d+\s*[.、)]/.test(heading[2])) {
+      issues.push(`标题不得手写序号：${heading[2]}`)
+    }
+  }
+
+  return { ok: issues.length === 0, issues }
+}
+
+function parseFlags(argv) {
+  const args = {}
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index]
+    if (!item.startsWith('--')) continue
+    const key = item.slice(2)
+    const next = argv[index + 1]
+    if (!next || next.startsWith('--')) {
+      args[key] = true
+      continue
+    }
+    args[key] = next
+    index += 1
+  }
+  return args
+}
+
+function main() {
+  const args = parseFlags(process.argv.slice(2))
+  if (!args.file || args.file === true) {
+    console.error('Usage: node check_api_tech_doc.mjs --file <markdown> [--optional "背景与目标,完成标准"]')
+    process.exit(2)
+  }
+
+  const optional =
+    typeof args.optional === 'string'
+      ? args.optional.split(',').map((value) => value.trim()).filter(Boolean)
+      : []
+
+  const markdown = readFileSync(args.file, 'utf8')
+  const result = checkApiTechDoc(markdown, { optional })
+
+  if (result.ok) {
+    console.log(JSON.stringify(result, null, 2))
+    process.exit(0)
+  }
+
+  console.error(JSON.stringify(result, null, 2))
+  process.exit(1)
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main()
+}

package/skills/execution/devFlow/domains/backend/scripts/check_api_tech_doc.test.mjs

@@ -0,0 +1,89 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { checkApiTechDoc } from './check_api_tech_doc.mjs'
+
+const API_DTO = '```typescript\ninterface ListDto { page: number }\n```'
+const API_RESP = '```typescript\ninterface ListData { total: number }\n```'
+const MODEL_TS = '```typescript\ninterface Entity { id: string }\n```'
+
+const GOOD = `# 接口设计
+
+> 统一约定：POST，返回体 { code, data }。
+
+### 列表查询 · POST /api/x
+
+**入参**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| page | number | 否 | 页码 |
+
+${API_DTO}
+
+**出参**
+
+${API_RESP}
+
+**错误码**：\`40001\` 参数校验失败
+
+# 数据模型 / 数据库设计
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| id | string | 是 | 主键 |
+
+${MODEL_TS}
+
+# 核心流程 / 时序
+
+\`\`\`mermaid
+sequenceDiagram
+  A->>B: x
+\`\`\`
+
+# 边界与异常
+
+- 空数据返回空列表。
+
+# 风险与待确认项
+
+- 待确认 X 字段来源。
+`
+
+test('合规文档通过', () => {
+  const r = checkApiTechDoc(GOOD)
+  assert.equal(r.ok, true, JSON.stringify(r.issues))
+})
+
+test('缺必写章节报错', () => {
+  const md = GOOD.replace('# 边界与异常', '# 其他')
+  const r = checkApiTechDoc(md)
+  assert.equal(r.ok, false)
+  assert.ok(r.issues.some((i) => i.includes('边界与异常')))
+})
+
+test('标题手写序号报错', () => {
+  const md = GOOD.replace('# 接口设计', '# 2. 接口设计')
+  const r = checkApiTechDoc(md)
+  assert.ok(r.issues.some((i) => i.includes('手写序号')))
+})
+
+test('数据模型缺 TS 报错', () => {
+  const md = GOOD.replace(MODEL_TS, '')
+  const r = checkApiTechDoc(md)
+  assert.ok(r.issues.some((i) => i.includes('数据模型') && i.includes('TypeScript')))
+})
+
+test('接口缺 TS 报错', () => {
+  const md = GOOD.replace(API_DTO, '').replace(API_RESP, '')
+  const r = checkApiTechDoc(md)
+  assert.ok(r.issues.some((i) => i.includes('接口设计') && i.includes('TypeScript')))
+})
+
+test('已选可选章节缺失报错，未选的不报', () => {
+  const missing = checkApiTechDoc(GOOD, { optional: ['完成标准'] })
+  assert.ok(missing.issues.some((i) => i.includes('完成标准')))
+  const none = checkApiTechDoc(GOOD)
+  assert.equal(none.ok, true, JSON.stringify(none.issues))
+})

package/skills/execution/devFlow/domains/backend/templates/api-tech.md

@@ -0,0 +1,164 @@
+<!-- devFlow domains/backend api-tech 模板（定稿格式）。章节用 HTML 注释标【必写】/【可选】，生成正式文档时删除所有 HTML 注释。 -->
+<!-- 飞书排版语法：> 引用块；> [!WARNING]/[!TIP]/[!NOTE] 高亮块；--- 分隔线；**x** 粗体；表格自动灰底表头+自适应列宽。标题不写编号。 -->
+
+# 背景与目标
+<!-- 【可选】 -->
+
+说明本次后端要解决的问题与服务级目标。不写项目背景与技术栈罗列。
+
+# 范围与非目标
+<!-- 【可选】 -->
+
+- 涉及的服务 / 模块。
+- 明确不做的部分（非目标）。
+
+# 接口设计
+<!-- 【必写】 -->
+
+> 统一约定：`POST`，`Content-Type: application/json`，返回体 `{ code, data }`，时间字段统一 epoch ms。鉴权：Admin 登录态。
+
+## <模块名>
+
+### <接口名> · POST /api/<module>/<action>
+
+**用途**：用 bullet 列出能力点：
+
+- 能力点 1
+- 能力点 2
+
+**入参**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| page | number | 是 | 页码（≥ 1） |
+| pageSize | number | 是 | 每页条数（1–100） |
+
+```typescript
+interface ExampleDto {
+  page: number
+  pageSize: number
+}
+```
+
+> [!WARNING] 标注本期为 mock / 跨模块依赖的字段，需在此提示。
+
+**出参**（data 结构）
+
+```typescript
+interface ExampleData {
+  total: number
+  list: ExampleItem[]
+}
+```
+
+**说明**
+
+- 副作用 / 事务 / mock 口径等要点，逐条 bullet。
+
+**错误码**：`40001` 参数校验失败 ｜ `40301` 登录态失效
+
+---
+
+# 数据模型 / 数据库设计
+<!-- 【必写】 -->
+
+## <实体 / 表名>
+
+> 集合 <name>（用途）。extends Base: sys_status；timestamps。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| _id | ObjectId | 是 | 主键 |
+| name | string | 是 | 名称，查重唯一 |
+| createdAt | number | 是 | 创建时间，epoch ms |
+
+```typescript
+interface Entity {
+  _id: string
+  name: string
+  createdAt: number // epoch ms
+}
+```
+
+索引与 migration 影响：说明新增/变更的索引、唯一约束、迁移注意点。
+
+# 核心流程 / 时序
+<!-- 【必写】 -->
+
+说明关键业务流程、调用链、事务边界与幂等 / 并发。状态流转用 Mermaid（源码）。生成正式文档时按实际场景保留必要图，不要机械保留所有示例。
+
+**主链路时序图**
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor U as 用户浏览器
+  participant FE as xxx-portal · 前端
+  participant BE as xxx-server · 后端
+  participant AD as admin-be · 管理后台
+
+  rect rgb(219, 234, 254)
+  Note over U,BE: 阶段 1 · 入口 / 初始化（说明边界）
+  U->>FE: 进入页面 / 触发操作
+  FE->>BE: check-session / load-profile
+  BE-->>FE: { profileStatus }
+  end
+
+  rect rgb(254, 243, 199)
+  Note over U,BE: 阶段 2 · 暂存 / 校验（说明数据落点）
+  U->>FE: 填写信息
+  FE->>BE: save-draft / validate
+  BE->>BE: 参数校验 / 幂等检查
+  BE-->>FE: { saved: true }
+  end
+
+  rect rgb(220, 252, 231)
+  Note over U,AD: 阶段 3 · 提交 / 生效（说明事务与外部依赖）
+  U->>FE: 点击提交
+  FE->>BE: submit
+  BE->>AD: AdminClient.submit（x-signature 验签）
+  AD->>AD: 查重 / 状态机 / 审计
+  AD-->>BE: { status }
+  BE-->>FE: { code, data }
+  end
+```
+
+**关键分支流程图**（存在事务、幂等、异常分支时保留）
+
+```mermaid
+flowchart TD
+  classDef entry fill:#dbeafe,stroke:#60a5fa,color:#1e3a8a
+  classDef success fill:#dcfce7,stroke:#22c55e,color:#14532d
+  classDef warn fill:#fef3c7,stroke:#f59e0b,color:#78350f
+  classDef risk fill:#fee2e2,stroke:#ef4444,color:#7f1d1d
+
+  A[接收提交请求]:::entry --> B{幂等键存在?}
+  B -->|是| C[返回已有处理结果]:::warn
+  B -->|否| D[参数与权限校验]
+  D --> E{校验通过?}
+  E -->|否| F[返回业务错误码]:::risk
+  E -->|是| G[开启事务并写入主表]
+  G --> H[提交事务]:::success
+```
+
+# 依赖与非功能性
+<!-- 【可选】 -->
+
+- 中间件 / 第三方 / MQ / 缓存。
+- 限流、性能、安全与权限。
+
+# 边界与异常
+<!-- 【必写】 -->
+
+- 空数据、请求失败、无权限、重复提交、并发冲突、部分数据缺失的处理与返回。
+- 回滚、重试、降级策略。
+
+# 完成标准
+<!-- 【可选】 -->
+
+说明后端做到什么程度算完成。保持简短，不写测试用例与排期。
+
+# 风险与待确认项
+<!-- 【必写】 -->
+
+- 收敛 PRD / 接口 / 仓库代码冲突，每条具体到可直接问产品、前端或负责人。