create-yss-spec 1.0.0

package/template/docs/testing/README.md

@@ -0,0 +1,110 @@
+# 测试策略 (Testing Strategy)
+
+> **覆盖全流程：单元 → 集成 → E2E → 性能 → 安全**
+
+---
+
+## 测试金字塔
+
+```
+           ┌──────┐
+           │ E2E  │  ← Playwright (关键流程 100% 覆盖)
+           ├──────┤
+           │ 集成  │  ← pytest + httpx (API 端点)
+           ├──────┤
+           │ 单元  │  ← pytest + vitest (Service/Hook/组件)
+           └──────┘
+```
+
+---
+
+## 各层测试策略
+
+### 单元测试 (Unit)
+
+| 层级 | 工具 | 覆盖率 | Mock 策略 |
+|------|------|--------|----------|
+| 后端 Service | pytest | ≥90% | Mock DB/外部API，不 mock 内部 Service |
+| 后端 Model | pytest | ≥90% | 验证字段定义/约束 |
+| 前端 Hook | vitest | ≥90% | Mock API 调用 |
+| 前端 工具函数 | vitest | ≥90% | 纯函数不 mock |
+
+### 集成测试 (Integration)
+
+| 层级 | 工具 | 覆盖率 | 策略 |
+|------|------|--------|------|
+| API 端点 | pytest + httpx + ASGITransport | ≥80% | 真实路由 + Mock 数据层 |
+| 数据库 (未来) | pytest + test DB | ≥80% | 每测试独立事务，自动回滚 |
+
+### E2E 测试
+
+| 场景 | 工具 | 策略 |
+|------|------|------|
+| 关键业务流程 | Playwright | 100% 覆盖 |
+| 视觉回归 | Playwright + screenshot | 关键页面 |
+| 跨浏览器 | Playwright (Chromium + Firefox) | 关键流程 |
+
+### 性能测试
+
+| 指标 | 工具 | 目标 |
+|------|------|------|
+| API 响应时间 | locust / k6 | P99 ≤ 200ms |
+| 并发用户 | locust | 1000 并发 P99 ≤ 500ms |
+
+### 安全测试
+
+| 检查项 | 工具 | 频率 |
+|--------|------|------|
+| 依赖漏洞 | pip audit / npm audit | 每次 PR |
+| 代码安全 | bandit (Python) | 每次 PR |
+| SAST | semgrep | 每次 PR |
+
+---
+
+## AI 在测试中的角色
+
+### 1. 测试生成 Agent — 分析影响范围，自动生成测试
+
+```python
+delegate_task(
+    goal="分析本次 PR diff，生成被修改代码的针对性测试",
+    context="""
+    分析 git diff，对每个修改的函数：
+    1. 识别未覆盖的代码路径
+    2. 生成单元测试 (边界值/等价类/异常路径)
+    3. 如果修改了 API 端点，生成集成测试
+    
+    输出：可直接运行的测试代码
+    """,
+    toolsets=["terminal", "file"]
+)
+```
+
+### 2. 失败诊断 Agent — 测试失败时辅助定位
+
+```python
+delegate_task(
+    goal="分析测试失败日志，定位根因",
+    context="""
+    失败测试输出：[贴入 pytest/vitest 输出]
+    
+    1. 归类失败 (代码bug / 测试bug / 环境问题)
+    2. 定位最可能的根因文件+行号
+    3. 给出修复建议
+    """,
+    toolsets=["terminal", "file"]
+)
+```
+
+---
+
+## 质量门禁
+
+| 门禁 | 条件 | 阻断级别 |
+|------|------|---------|
+| 单元测试 | 100% pass | 🔴 阻断合入 |
+| 集成测试 | 100% pass | 🔴 阻断合入 |
+| 覆盖率 | ≥80% (新增代码) | 🟡 警告 |
+| Lint | 0 error | 🔴 阻断合入 |
+| 安全扫描 | 0 high/critical | 🔴 阻断合入 |
+| 发布门禁 | 项目定义的质量门禁通过 | 🔴 阻断合入 |

package/template/docs/user-guide/README.md

@@ -0,0 +1,31 @@
+# 使用手册
+
+本文档面向使用本模板初始化项目的开发者、产品/架构协作者和 AI Agent 操作者。
+
+## 当前范围
+
+本模板提供文档骨架、契约模板、项目级 Agent skills 和协作约定。
+
+## 推荐流程
+
+1. 在 `docs/discovery/` 记录机会探索、市场、竞品和用户洞察。
+2. 在 `docs/requirements/` 维护 PRD、用户故事和验收标准。
+3. 在 `docs/design/` 维护页面、原型、用户流和交互状态。
+4. 在 `docs/api/` 维护 OpenAPI 3.1 契约。
+5. 在 `docs/architecture/` 和 `docs/adr/` 记录业务架构、功能架构、系统总体架构、数据架构和架构决策。
+6. 在 `docs/testing/` 维护测试策略和质量要求。
+7. 使用项目自己的 CI、harness 或人工流程推进开发、审查、发布和复盘。
+
+## 继续阅读
+
+- [create-yss-spec 使用手册](./create-yss-spec-cli-guide.md)
+- [产品全生命周期使用手册](./product-lifecycle-workflow.md)
+- [全生命周期最佳实践](./lifecycle-best-practices.md)
+- [产品研发全生命周期最佳实践](./product-rd-lifecycle-best-practices.md)
+- [grill-with-docs 使用手册](./grill-with-docs-guide.md)
+- [grill-with-docs 最佳实践](./grill-with-docs-best-practices.md)
+- [Excalidraw Diagram Generator 使用手册](./excalidraw-diagram-generator-guide.md)
+- [PDCA × Scrum](../process/PDCA-SCRUM.md)
+- [Matt Pocock Engineering Skills](../process/MATT-POCOCK-ENGINEERING-SKILLS.md)
+- [架构设计](../architecture/README.md)
+- [测试策略](../testing/README.md)

package/template/docs/user-guide/create-yss-spec-cli-guide.md

@@ -0,0 +1,194 @@
+# create-yss-spec 使用手册
+
+本文档面向需要初始化 `yss-spec-project-template` 模板实例仓库的内部开发者、Tech Lead、项目初始化负责人。
+
+## 适用场景
+
+当你需要基于当前模板源仓库快速生成一个新的研发管理仓库时，使用 `create-yss-spec`。
+
+它适合做的事：
+
+- 初始化新的 PRD / 架构 / OpenAPI / Issue 管理仓库
+- 统一生成项目级文档骨架、Agent 协作约定和模板目录结构
+- 通过参数渲染项目名称、业务领域、团队规模等元信息
+
+它不负责做的事：
+
+- 生成前端 / 后端运行时代码工程
+- 自动安装依赖
+- 自动创建远端 Git 仓库、CI 或 Issue Board
+- 把已有项目升级到最新模板版本
+
+## 快速开始
+
+推荐入口：
+
+```bash
+npm create yss-spec@latest
+```
+
+兼容入口：
+
+```bash
+npx create-yss-spec@latest
+```
+
+运行后会按顺序询问：
+
+1. `项目名称`
+2. `业务领域`
+3. `团队规模（可留空）`
+4. `目标目录`
+
+初始化完成后，CLI 会输出结果目录和下一步建议。
+
+## 最常见用法
+
+### 交互式初始化
+
+```bash
+npm create yss-spec@latest
+```
+
+适合第一次使用或希望手动确认输入内容的场景。
+
+### 指定参数直接生成
+
+```bash
+npx create-yss-spec@latest \
+  --project-name "Acme Spec Repo" \
+  --business-domain "Investment Research" \
+  --team-size "12" \
+  --target-dir "./acme-spec-repo" \
+  --issue-tracker github \
+  --git-init
+```
+
+适合脚本化、重复初始化或在 CI / shell 脚本中调用的场景。
+
+### 只预览，不真正写入
+
+```bash
+npx create-yss-spec@latest \
+  --project-name "Preview Repo" \
+  --business-domain "Data Platform" \
+  --target-dir "./preview-repo" \
+  --dry-run
+```
+
+`--dry-run` 只展示计划，不会创建目录，也不会删除已有文件。
+
+## 参数说明
+
+| 参数 | 含义 | 默认行为 |
+|---|---|---|
+| `--project-name` | 项目名称 | 不传则进入交互输入 |
+| `--business-domain` | 业务领域 | 不传则进入交互输入 |
+| `--team-size` | 团队规模 | 不传则进入交互输入，可留空 |
+| `--target-dir` | 输出目录 | 不传则进入交互输入 |
+| `--issue-tracker github\|gitlab` | 默认 issue tracker 偏好 | 默认 `github` |
+| `--dry-run` | 只预览复制 / 渲染计划，不写入文件 | 默认关闭 |
+| `--force` | 目标目录非空时允许清空后重新生成 | 默认关闭 |
+| `--git-init` | 初始化完成后执行 `git init` | 默认关闭 |
+| `--include-example-docs` | 显式保留示例文档 | 默认开启 |
+| `--no-example-docs` | 不生成示例文档 | 默认关闭 |
+
+## 输出内容说明
+
+CLI 会根据模板清单把源仓库内容分成三类处理：
+
+- `render`：需要写入项目变量的文件，例如 `AGENTS.md`、`README.md`
+- `copy`：原样复制的模板资产
+- `exclude`：不会进入实例仓库的维护性文件、本地配置和本需求自身的实现资产
+
+生成结果通常包含：
+
+- `AGENTS.md`
+- `CONTEXT.md`
+- `docs/requirements/`
+- `docs/architecture/`
+- `docs/api/`
+- `docs/design/`
+- `docs/testing/`
+- 项目级 Agent skills 与流程文档
+
+如果启用了 `--git-init`，目标目录下还会生成 `.git/`。
+
+## 默认安全策略
+
+为了避免误覆盖，CLI 采用默认安全策略：
+
+- 目标目录非空时，默认直接失败
+- 只有显式传入 `--force` 时，才允许清空目标目录后重新生成
+- 目标目录不能位于模板源仓库内部
+- `--dry-run` 没有副作用
+
+## 示例结果
+
+一次典型执行完成后，你会看到类似输出：
+
+```text
+初始化完成
+输出目录：/path/to/your-project
+下一步建议：
+1. cd /path/to/your-project
+2. 如需版本管理，可执行 git init
+3. 检查 AGENTS.md、README 和 docs 目录是否符合预期
+```
+
+如果已经传了 `--git-init`，第二步会提示执行 `git status` 检查初始化结果。
+
+## 常见问题
+
+### 1. 提示“目标目录非空，当前主路径不支持覆盖已有内容”
+
+说明目标目录里已经有文件。
+
+处理方式：
+
+- 改用新的空目录
+- 或确认可以清空后，显式传入 `--force`
+
+### 2. 提示“目标目录不能位于模板源仓库内部”
+
+说明你把输出目录设到了当前模板仓库内部。这样会污染模板源仓库，CLI 会直接拒绝。
+
+处理方式：
+
+- 把 `--target-dir` 改成模板仓库外部目录
+
+### 3. 我想在 shell 管道或脚本里调用
+
+可以，CLI 已支持非 TTY 输入。建议优先显式传参；如果要走标准输入，请按交互顺序提供：
+
+```bash
+printf 'Acme Spec Repo\nInvestment Research\n12\n/tmp/acme-spec-repo\n' \
+  | node packages/create-yss-spec/bin/create-yss-spec.js
+```
+
+### 4. 为什么没有自动安装依赖或创建远端仓库
+
+这是设计上的非目标范围。当前 CLI 只负责初始化研发管理模板实例仓库，组织级权限操作和后续 bootstrap 仍由人工控制。
+
+## 维护与验证
+
+如果你在维护这个 CLI，本地验证命令是：
+
+```bash
+npm test
+```
+
+发布前可检查打包内容：
+
+```bash
+cd packages/create-yss-spec
+npm pack --dry-run
+```
+
+## 继续阅读
+
+- [模板使用说明](./README.md)
+- [产品全生命周期使用手册](./product-lifecycle-workflow.md)
+- [产品研发全生命周期最佳实践](./product-rd-lifecycle-best-practices.md)
+- [实现路由记录](../implementation/yss-spec-cli-init-routing.md)
+- [产品需求文档：yss-spec 模板初始化 CLI](../requirements/yss-spec-cli-init-prd.md)

package/template/docs/user-guide/excalidraw-diagram-generator-guide.md

@@ -0,0 +1,143 @@
+# Excalidraw Diagram Generator 使用手册
+
+`excalidraw-diagram-generator` 是可视化说明与审查辅助 skill，用来把流程、架构、状态、依赖、数据流和切片关系生成 `.excalidraw` 文件。
+
+它不替代 `yss-product-lifecycle`、PRD、OpenAPI、ADR、Issue 或测试。它的价值是让复杂关系可以被快速看见、讨论和审查。
+
+## 1. 在流程中的定位
+
+推荐使用位置：
+
+```text
+机会探索 / Discovery
+  -> 用户旅程图、机会地图、竞品流程泳道图
+
+PRD / 需求澄清
+  -> 业务流程图、角色职责泳道图、页面地图
+
+OpenAPI Draft / 工程基线 / 架构设计
+  -> 系统架构图、数据流图、序列图、ER 图、DDD 边界图
+
+系统 / 数据架构设计
+  -> 状态流、调用链、领域边界、切片依赖图
+
+设计审查 / 垂直切片前
+  -> 用图暴露边界不清、契约缺口和切片依赖
+
+复盘沉淀
+  -> 最终流程图、架构演进图、知识沉淀图
+```
+
+最有价值的阶段是 Architecture / 系统 / 数据架构设计 和 Design Review。此时图可以帮助审查 DDD 边界、状态流、接口契约、异常路径和垂直切片是否一致。
+
+## 1.1 四类架构图产物
+
+四类架构图随生命周期逐步产出，不要求一次性全部画完。
+
+| 架构产物 | 产出阶段 | 图的价值 | 常用图类型 | 保存位置 |
+|---|---|---|---|---|
+| 业务架构图 | 机会探索 / Discovery / 产品定义 | 让用户、价值流、角色协作和产品边界可视化 | 用户旅程、价值流、泳道图、能力地图、生态关系图 | `docs/discovery/diagrams/` 或 `docs/architecture/diagrams/` |
+| 功能架构图 | PRD baseline / 产品设计 / PRD 校准 | 让功能域、模块、优先级和依赖关系可审查 | 功能模块图、依赖图、页面地图、关系图 | `docs/design/diagrams/` 或 `docs/architecture/diagrams/` |
+| 系统总体架构图 | 工程基线 / 系统 / 数据架构设计 | 让服务边界、部署、集成、权限链路和 NFR 方案可审查 | C4/容器图、部署图、序列图、DFD、DDD 边界图 | `docs/architecture/diagrams/` |
+| 数据架构图 | 详细设计 / 持久化开发前 | 让元模型、版本、血缘、查询和存储策略在写 Repository 前被看见 | ER 图、Class/元模型图、血缘图、DFD、查询路径图 | `docs/architecture/diagrams/` |
+
+对于数据模型、元数据管理、模型版本或血缘分析类产品，数据架构图尤其有价值。它不能替代 `docs/architecture/<feature>-data-architecture.md`，但可以帮助提前发现元模型抽象不稳、版本边界不清、血缘关系无法高效查询等高成本问题。
+
+## 2. 适用与不适用
+
+适用：
+
+- 多角色、多系统、多模块协作。
+- 涉及前后端、OpenAPI、DDD、状态机。
+- 有复杂页面流、审批流、发布流、导入导出流。
+- 设计审查时理解不一致。
+- 垂直切片之间有依赖，需要解释交付顺序。
+
+不适用：
+
+- 单点文案、小样式、小 bug。
+- 已有清晰 PRD / OpenAPI / ADR，且没有理解歧义。
+- 只是为了让文档看起来更完整。
+
+## 3. 与 Agents 的协作
+
+| Agent | 使用方式 |
+|---|---|
+| Ideation / Discovery Agent | 生成机会地图、用户旅程、竞品流程泳道图 |
+| Product / Grill Agent | 把需求澄清结果画成业务流程、角色职责图 |
+| API Contract Agent | 画接口调用序列、数据流、错误流 |
+| Architecture Agent | 画系统架构、DDD 分层、模块依赖、ER / Class / DFD |
+| Design Review Agent | 对图做审查，找职责不清、循环依赖、契约缺口 |
+| Code Agent | 消费图辅助理解，不用图替代 PRD、OpenAPI 或 ADR |
+| Review Agent | 检查实现是否偏离图中的边界和流程 |
+| Knowledge / Retro Agent | 把稳定流程或架构图沉淀到 docs |
+
+## 4. 产物位置
+
+推荐目录：
+
+```text
+docs/discovery/diagrams/
+docs/design/diagrams/
+docs/architecture/diagrams/
+```
+
+示例：
+
+```text
+docs/discovery/diagrams/model-management-opportunity-map.excalidraw
+docs/design/diagrams/model-management-user-flow.excalidraw
+docs/architecture/diagrams/model-publishing-sequence.excalidraw
+docs/architecture/diagrams/model-ddd-boundary.excalidraw
+```
+
+在对应 Markdown 文档中引用：
+
+```markdown
+相关图：`docs/architecture/diagrams/model-publishing-sequence.excalidraw`
+```
+
+## 5. 实践方式
+
+推荐三步法：
+
+1. 先有文字事实。
+   来源应该是 Discovery、PRD、OpenAPI Draft、Architecture、系统 / 数据架构设计 或 Issue。
+2. 再生成图。
+   根据用途选择 Flowchart、Swimlane、Relationship、Class、ER、Sequence、DFD、Architecture 或 Mind Map。
+3. 最后回写审查结论。
+   图里暴露的问题要回写到 PRD、OpenAPI、ADR、系统 / 数据架构设计 或 Issue。
+
+常用提示词：
+
+```text
+使用 excalidraw-diagram-generator，基于 docs/requirements/<feature>-prd.md
+和 docs/api/specs/<feature>.yaml，生成 <feature> 的接口调用序列图。
+保存到 docs/architecture/diagrams/<feature>-sequence.excalidraw。
+```
+
+```text
+使用 excalidraw-diagram-generator，基于当前 系统 / 数据架构设计，
+生成 DDD 边界和模块依赖图，突出 Domain、Application、Infrastructure、Adapter 的依赖方向。
+保存到 docs/architecture/diagrams/<feature>-ddd-boundary.excalidraw。
+```
+
+```text
+使用 excalidraw-diagram-generator，基于 docs/architecture/<feature>-data-architecture.md，
+生成元模型 ER 图和血缘关系图，突出 Model、Entity、Attribute、Relationship、Version、LineageEdge 的关系。
+保存到 docs/architecture/diagrams/<feature>-data-model.excalidraw。
+```
+
+```text
+使用 excalidraw-diagram-generator，把这些垂直切片画成依赖关系图。
+要求标出每个 slice 的用户动作、API、后端行为、前端入口和验证点。
+```
+
+## 6. 审查清单
+
+- 图是否引用了明确的上游资产。
+- 图是否帮助回答一个具体问题，而不是装饰文档。
+- 节点数量是否可读，复杂图是否拆成高层图和子图。
+- DDD、API、状态流、权限和错误路径是否表达清楚。
+- 图中发现的问题是否回写到文本资产。
+- `.excalidraw` 文件是否放在合适目录，并被相关文档引用。