From aca7dc999e70f2c6f0c3dd310bf3d0b5730be009 Mon Sep 17 00:00:00 2001 From: tian <11429339@qq.com> Date: Thu, 21 May 2026 20:32:32 +0800 Subject: [PATCH] =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E5=88=9D=E5=A7=8B=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 49 ++++++++++++++++++++++++ CHANGELOG.md | 34 +++++++++++++++++ CLAUDE.md | 61 ++++++++++++++++++++++++++++++ CONTRIBUTING.md | 51 +++++++++++++++++++++++++ LICENSE | 21 ++++++++++ README.md | 60 +++++++++++++++++++++++++++++ VERSION | 1 + docs/design/architecture/index.md | 47 +++++++++++++++++++++++ docs/design/index.md | 26 +++++++++++++ docs/design/technical/index.md | 51 +++++++++++++++++++++++++ docs/features/index.md | 56 +++++++++++++++++++++++++++ docs/implementation/index.md | 17 +++++++++ docs/implementation/tasks/index.md | 51 +++++++++++++++++++++++++ docs/index.md | 18 +++++++++ docs/requirements/changes/index.md | 11 ++++++ docs/requirements/index.md | 53 ++++++++++++++++++++++++++ scripts/index.md | 9 +++++ skills/index.md | 17 +++++++++ src/index.md | 27 +++++++++++++ test/e2e/index.md | 14 +++++++ test/index.md | 18 +++++++++ test/integration/index.md | 15 ++++++++ test/unit/index.md | 17 +++++++++ verify/checklist/index.md | 36 ++++++++++++++++++ verify/index.md | 22 +++++++++++ 25 files changed, 782 insertions(+) create mode 100644 .gitignore create mode 100644 CHANGELOG.md create mode 100644 CLAUDE.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 VERSION create mode 100644 docs/design/architecture/index.md create mode 100644 docs/design/index.md create mode 100644 docs/design/technical/index.md create mode 100644 docs/features/index.md create mode 100644 docs/implementation/index.md create mode 100644 docs/implementation/tasks/index.md create mode 100644 docs/index.md create mode 100644 docs/requirements/changes/index.md create mode 100644 docs/requirements/index.md create mode 100644 scripts/index.md create mode 100644 skills/index.md create mode 100644 src/index.md create mode 100644 test/e2e/index.md create mode 100644 test/index.md create mode 100644 test/integration/index.md create mode 100644 test/unit/index.md create mode 100644 verify/checklist/index.md create mode 100644 verify/index.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..16b989b --- /dev/null +++ b/.gitignore @@ -0,0 +1,49 @@ +# === 操作系统生成文件 === +.DS_Store +Thumbs.db + +# === IDE & 编辑器 === +.vscode/ +.idea/ +*.swp +*.swo + +# === 构建产物 === +dist/ +build/ +target/ +out/ +*.class +*.jar +*.war + +# === 依赖 === +node_modules/ +vendor/ +__pycache__/ +*.pyc +.venv/ +venv/ +.env + +# === 日志 === +*.log +logs/ + +# === 临时文件 === +*.tmp +*.temp +tmp/ + +# === 测试 === +coverage/ +.nyc_output/ +*.coverage + +# === 环境变量（敏感信息） === +.env.local +.env.production + +# === 缓存 === +.cache/ +.pytest_cache/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..cebd874 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,34 @@ +# Changelog + +本文件记录项目对外发布的变更历史（用户视角）。 +格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)， +版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 + +格式说明： +- `Added` — 新增功能 +- `Changed` — 现有功能的变更 +- `Deprecated` — 即将移除的功能 +- `Removed` — 已移除的功能 +- `Fixed` — 问题修复 +- `Security` — 安全修复 + +--- + +## [Unreleased] + +### Added +- （待发布的新功能） + +### Changed +- （待发布的变更） + +--- + +## [0.1.0] - YYYY-MM-DD + +### Added +- 项目初始化。 + +--- + +> 更多格式说明见：https://keepachangelog.com/zh-CN/1.1.0/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..1b679d0 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,61 @@ +# CLAUDE.md + +## 1. Think Before Coding + +**Don't assume. Don't hide confusion. Surface tradeoffs.** + +Before implementing: +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them - don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +## 2. Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +## 3. Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it - don't delete it. + +When your changes create orphans: +- Remove imports/variables/functions that YOUR changes made unused. +- Don't remove pre-existing dead code unless asked. + +The test: Every changed line should trace directly to the user's request. + +## 4. Goal-Driven Execution + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: +- "Add validation" → "Write tests for invalid inputs, then make them pass" +- "Fix the bug" → "Write a test that reproduces it, then make it pass" +- "Refactor X" → "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan: +``` +1. [Step] → verify: [check] +2. [Step] → verify: [check] +3. [Step] → verify: [check] +``` + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. + +--- + +**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3901f9e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,51 @@ +# 贡献指南 + +感谢你对本项目的关注！请遵循以下规范参与开发。 + +## 开发流程 + +1. **认领任务** — 从 `docs/implementation/tasks/` 中选取或创建任务 +2. **创建分支** — 分支命名：`feature/<描述>` / `fix/<描述>` / `docs/<描述>` +3. **编写代码** — 遵循项目代码规范，添加必要的测试 +4. **自测** — 确保测试通过，功能正常 +5. **提交代码** — Commit message 遵循 [约定式提交](https://www.conventionalcommits.org/zh-hans/) +6. **发起 Merge Request / Pull Request** — 描述变更内容，关联对应的需求/问题 +7. **代码审查** — 至少一人 Review 通过后合并 + +## Commit Message 规范 + +``` +(): + +类型（type）： + feat — 新功能 + fix — 修复 + docs — 文档 + style — 格式（不影响功能） + refactor — 重构 + test — 测试 + chore — 构建/工具 + +示例： + feat(auth): add login by SMS + fix(api): correct user list pagination +``` + +## 代码规范 + +- 保持代码风格与项目一致 +- 公共接口必须有注释 +- 新增功能必须编写测试 +- 修改现有功能需同步更新相关文档 + +## 测试要求 + +- 单元测试覆盖率目标：> [XX]% +- 提交前确保所有测试通过 +- 涉及接口变更需补充集成测试 + +## 文档要求 + +- 功能设计文档放在 `docs/features/` +- 架构变更需在 `docs/design/architecture/` 添加 ADR（架构决策记录） +- 需求变更在 `docs/requirements/changes/` 记录 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4d23f2f --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) [2026] [北京泰奥理科技] + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..164a1d4 --- /dev/null +++ b/README.md @@ -0,0 +1,60 @@ +# [项目名称] + +> 一句话描述项目：是什么，解决什么问题，面向谁。 + +## 目录结构 + +``` +├── README.md # 项目概述与快速开始（本文件） +├── CHANGELOG.md # 对外发布变更记录（用户视角） +├── VERSION # 语义化版本号 +├── LICENSE # 许可证 +├── CONTRIBUTING.md # 贡献规范 +├── .gitignore # Git 忽略规则 +├── CLAUDE.md # AI 编码助手上下文 +│ +├── src/ # 源代码 +├── test/ # 测试代码 +│ ├── unit/ # 单元测试 +│ ├── integration/ # 集成测试 +│ └── e2e/ # 端到端测试 +│ +├── docs/ # 开发文档 +│ ├── requirements/ # 需求与变更管理 +│ ├── design/ # 设计方案（架构 + 技术方案） +│ ├── features/ # 功能规格说明 +│ └── implementation/ # 实施计划与任务跟踪 +│ +├── skills/ # AI 辅助技能 +├── scripts/ # 构建、部署、工具脚本 +└── verify/ # 验证、检查清单、上线验收 +``` + +## 快速开始 + +```bash +# 克隆项目 +git clone +cd + +# [安装 / 构建 / 运行步骤，根据项目补充] +``` + +## 文档导航 + +| 你想做的事 | 去哪看 | +|------------|--------| +| 了解项目背景和架构 | `docs/design/architecture/` | +| 查看需求与变更 | `docs/requirements/` | +| 查看功能设计 | `docs/features/` | +| 查看任务进度 | `docs/implementation/tasks/` | +| 参与开发 | `CONTRIBUTING.md` | +| 查看版本历史 | `CHANGELOG.md` | + +## 维护者 + +- [@维护者](https://github.com/xxx) + +## 许可证 + +[LICENSE](./LICENSE) diff --git a/VERSION b/VERSION new file mode 100644 index 0000000..6e8bf73 --- /dev/null +++ b/VERSION @@ -0,0 +1 @@ +0.1.0 diff --git a/docs/design/architecture/index.md b/docs/design/architecture/index.md new file mode 100644 index 0000000..5cd83be --- /dev/null +++ b/docs/design/architecture/index.md @@ -0,0 +1,47 @@ +# docs/design/architecture — 架构设计 + +存放系统架构文档和架构决策记录（ADR）。 + +## 架构决策记录（ADR） + +当需要做出影响系统结构的重大技术决策时，请创建一条 ADR。 + +### 文件命名 + +``` +ADR-<序号>-<标题>.md +``` + +### ADR 模板 + +```markdown +# ADR-001: [决策标题] + +- **状态**：提议 / 已接受 / 已废弃 / 已替代 +- **日期**：YYYY-MM-DD +- **决策者**：[姓名] +- **替代**：[如替代了之前的 ADR] + +## 背景 + +> 为什么需要做这个决策？面临什么问题？ + +## 决策 + +> 我们决定做什么？ + +## 备选方案 + +| 方案 | 优点 | 缺点 | +|------|------|------| +| 方案 A | ... | ... | +| 方案 B | ... | ... | + +## 后果 + +> 决策后带来的影响（好的和需要关注的）。 +``` + +--- + +> 关于 ADR 的更多说明，见 [adr.github.io](https://adr.github.io/) diff --git a/docs/design/index.md b/docs/design/index.md new file mode 100644 index 0000000..0e21946 --- /dev/null +++ b/docs/design/index.md @@ -0,0 +1,26 @@ +# docs/design — 设计方案 + +本目录存放架构设计和技术方案文档。 + +## 目录结构 + +``` +design/ +├── architecture/ # 架构设计 & 架构决策记录（ADR） +└── technical/ # 技术方案 / 详细设计 +``` + +## architecture/ — 架构设计 + +- **总体架构文档**：系统架构图、模块划分、技术选型、核心交互流程 +- **ADR（Architecture Decision Record）**：记录重大架构决策及其背景 + +## technical/ — 技术方案 + +- 各模块的详细技术设计 +- 接口设计、数据模型设计 +- 关键技术难点的攻关方案 + +--- + +> **提示**：架构图和流程图推荐使用 Mermaid（Markdown 原生支持）或 PlantUML，方便版本控制和 AI 工具解析。 diff --git a/docs/design/technical/index.md b/docs/design/technical/index.md new file mode 100644 index 0000000..33b1c70 --- /dev/null +++ b/docs/design/technical/index.md @@ -0,0 +1,51 @@ +# docs/design/technical — 技术方案 + +本目录存放各模块的详细技术设计方案。 + +## 文件命名 + +``` +<模块名>-技术方案.md +``` + +## 技术方案模板 + +```markdown +# [模块名] 技术方案 + +- **版本**：v[版本号] +- **作者**：[姓名] +- **日期**：YYYY-MM-DD +- **状态**：草稿 / 评审中 / 已定稿 + +## 1. 概述 + +> 本方案解决什么问题？适用范围是什么？ + +## 2. 设计目标 + +- 功能目标 +- 非功能目标（性能、安全、可扩展性等） + +## 3. 方案描述 + +### 3.1 整体流程 + + + +### 3.2 接口设计 + +### 3.3 数据模型 + +### 3.4 关键逻辑 + +## 4. 风险与应对 + +| 风险 | 影响 | 应对措施 | +|------|------|----------| +| ... | ... | ... | + +## 5. 参考 + +- [相关文档链接] +``` diff --git a/docs/features/index.md b/docs/features/index.md new file mode 100644 index 0000000..beb59da --- /dev/null +++ b/docs/features/index.md @@ -0,0 +1,56 @@ +# docs/features — 功能规格说明 + +每个功能模块对应一个功能规格说明文档，用于描述该功能的完整定义。 + +## 文件命名 + +``` +<功能名称>.md +``` + +## 功能规格模板 + +```markdown +# [功能名称] + +- **版本**：v[版本号] +- **状态**：规划中 / 开发中 / 已完成 +- **负责人**：[姓名] +- **关联需求**：[需求编号或链接] + +## 1. 功能概述 + +> 一句话描述 + 详细说明（用户视角，这个功能能做什么、解决什么问题）。 + +## 2. 用户场景 + +- 作为 [角色]，我希望 [做什么]，以便 [达到什么目的] + +## 3. 功能详情 + +### 3.1 前置条件 + +### 3.2 主流程 + +### 3.3 异常处理 + +- 异常情况 1：[描述] → [预期行为] +- 异常情况 2：[描述] → [预期行为] + +## 4. 验收标准 + +- [ ] 标准 1 +- [ ] 标准 2 +- [ ] 标准 3 + +## 5. 约束与限制 + +- 性能要求 +- 兼容性要求 +- 其他限制 + +## 6. 关联 + +- 设计方案：`docs/design/technical/<相关方案>.md` +- 任务拆分：`docs/implementation/tasks/<相关任务>.md` +``` diff --git a/docs/implementation/index.md b/docs/implementation/index.md new file mode 100644 index 0000000..02ce7d9 --- /dev/null +++ b/docs/implementation/index.md @@ -0,0 +1,17 @@ +# docs/implementation — 实施与跟踪 + +本目录用于管理开发实施计划和任务进度。 + +## 目录结构 + +``` +implementation/ +├── index.md # 本文件 +└── tasks/ # 任务拆分与进度跟踪 +``` + +## 使用方式 + +1. 将功能需求拆分为可执行的任务 +2. 每个迭代/功能一个任务文件，记录在 `tasks/` 下 +3. 任务文件中用 Checkbox 标记进度 diff --git a/docs/implementation/tasks/index.md b/docs/implementation/tasks/index.md new file mode 100644 index 0000000..12fac3d --- /dev/null +++ b/docs/implementation/tasks/index.md @@ -0,0 +1,51 @@ +# docs/implementation/tasks — 任务跟踪 + +每个功能或迭代对应一个任务文件。 + +## 文件命名 + +``` +<迭代/功能名称>-任务.md +``` + +## 任务文件模板 + +```markdown +# [迭代/功能名称] 任务跟踪 + +- **开始日期**：YYYY-MM-DD +- **目标日期**：YYYY-MM-DD +- **负责人**：[姓名] + +## 任务列表 + +### 阶段 1：[阶段名称]（目标：YYYY-MM-DD） + +- [ ] 任务 1 — @负责人 +- [ ] 任务 2 — @负责人 + - [ ] 子任务 2.1 + - [ ] 子任务 2.2 + +### 阶段 2：[阶段名称]（目标：YYYY-MM-DD） + +- [ ] 任务 3 — @负责人 +- [ ] 任务 4 — @负责人 + +## 进度 + +- ✅ 已完成：X / Y +- 🚧 进行中：X +- ⬜ 待开始：X + +## 风险与阻塞 + +| 问题 | 影响 | 责任人 | 状态 | +|------|------|--------|------| +| ... | ... | ... | 解决中 / 已解决 | + +## 变更记录 + +| 日期 | 变更内容 | +|------|----------| +| YYYY-MM-DD | ... | +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..f1ccbac --- /dev/null +++ b/docs/index.md @@ -0,0 +1,18 @@ +# docs — 开发文档 + +本目录存放项目的全部开发文档，涵盖需求、设计、功能规格和实施跟踪。 + +## 目录说明 + +| 子目录 | 用途 | 受众 | +|--------|------|------| +| `requirements/` | 需求与变更管理 | 产品、开发、测试 | +| `design/` | 架构设计与技术方案 | 开发、架构师 | +| `features/` | 功能规格说明 | 开发、测试、产品 | +| `implementation/` | 实施计划与任务跟踪 | 开发、项目管理 | + +## 使用原则 + +1. 文档**与代码同步更新**，不是一次性交付物 +2. 优先用 Markdown，便于版本控制和 AI 工具阅读 +3. 每个文档文件保持聚焦，一个文件讲清一件事 diff --git a/docs/requirements/changes/index.md b/docs/requirements/changes/index.md new file mode 100644 index 0000000..72e20e2 --- /dev/null +++ b/docs/requirements/changes/index.md @@ -0,0 +1,11 @@ +# docs/requirements/changes — 需求变更记录 + +每条需求变更一个文件，便于追溯和评审。 + +## 变更记录文件命名 + +``` +YYYY-MM-DD-<简短描述>.md +``` + +示例：`2025-01-15-登录支持短信验证码.md` diff --git a/docs/requirements/index.md b/docs/requirements/index.md new file mode 100644 index 0000000..b32595b --- /dev/null +++ b/docs/requirements/index.md @@ -0,0 +1,53 @@ +# docs/requirements — 需求与变更管理 + +本目录用于管理项目需求及其变更记录。 + +## 目录结构 + +``` +requirements/ +├── index.md # 本文件 +└── changes/ # 需求变更记录（每条变更一个文件） +``` + +## 需求变更记录 + +当需求发生变更时，请在 `changes/` 下创建一条记录。 + +### 文件命名规范 + +``` +YYYY-MM-DD-<简短描述>.md +``` + +### 变更记录模板 + +```markdown +# [变更标题] + +- **日期**：YYYY-MM-DD +- **提出人**：[姓名] +- **关联需求**：[原始需求编号或链接] +- **优先级**：高 / 中 / 低 + +## 变更描述 + +> 说明变更内容、变更原因。 + +## 影响范围 + +- [ ] 接口变更 +- [ ] 数据库变更 +- [ ] UI 变更 +- [ ] 文档变更 + +## 审批 + +- [ ] 产品确认 +- [ ] 技术评估 +- [ ] 测试评估 +``` + +--- + +> 每条变更记录对应一个 `.md` 文件，便于版本控制和追溯。 diff --git a/scripts/index.md b/scripts/index.md new file mode 100644 index 0000000..79a82c2 --- /dev/null +++ b/scripts/index.md @@ -0,0 +1,9 @@ +# scripts — 工具脚本 + +本目录存放项目的辅助脚本：构建、部署、数据迁移、环境初始化等。 + +## 原则 + +- 每个脚本做好注释，说明用途和运行方式 +- 脚本应尽量幂等（多次运行结果一致） +- 避免将敏感信息（密码、密钥）硬编码在脚本中 diff --git a/skills/index.md b/skills/index.md new file mode 100644 index 0000000..ebdef53 --- /dev/null +++ b/skills/index.md @@ -0,0 +1,17 @@ +# skills — AI 辅助技能 + +本目录用于存放项目专属的 AI 辅助技能 / 提示词，帮助 AI 编码助手更好地理解项目上下文。 + +## 用途 + +- 项目特定的编码规范和约定 +- 代码审查清单 +- 自动化提示词（如：生成测试、生成文档等） + +## 使用方式 + +将自定义的提示词文件放入本目录，并按需要引用。 + +--- + +> 当前为空，可根据团队需要添加。 diff --git a/src/index.md b/src/index.md new file mode 100644 index 0000000..042dcde --- /dev/null +++ b/src/index.md @@ -0,0 +1,27 @@ +# src — 源代码 + +本目录存放项目的全部源代码。 + +## 组织原则 + +- 按模块/功能划分子目录，避免扁平结构过于庞大 +- 公共组件、工具函数独立成目录或模块 +- 保持目录层级不超过 3-4 层 + +## 推荐结构 + +``` +src/ +├── core/ # 核心业务逻辑 +├── utils/ # 通用工具函数 +├── models/ # 数据模型 / 实体 +├── services/ # 服务层（如有） +├── api/ # API 接口层（如有） +└── main.* # 入口文件 +``` + +## 注意事项 + +- 该结构为建议，请根据项目实际技术栈和框架调整 +- 保持模块间低耦合、高内聚 +- 公共代码优先放在 `utils/` 或独立模块中 diff --git a/test/e2e/index.md b/test/e2e/index.md new file mode 100644 index 0000000..64582fe --- /dev/null +++ b/test/e2e/index.md @@ -0,0 +1,14 @@ +# test/e2e — 端到端测试 + +模拟真实用户行为，从系统入口到出口的完整链路测试。 + +## 原则 + +- **用户视角** — 模拟用户操作流程 +- **环境一致** — 尽量在类生产环境中运行 +- **场景驱动** — 聚焦核心用户场景，避免测试琐碎细节 + +## 示例 + +- 用户注册 → 登录 → 操作 → 退出 完整流程 +- 订单创建 → 支付 → 状态变更 完整链路 diff --git a/test/index.md b/test/index.md new file mode 100644 index 0000000..364bcdb --- /dev/null +++ b/test/index.md @@ -0,0 +1,18 @@ +# test — 测试代码 + +本目录存放项目的全部测试代码。测试代码的组织结构应**镜像** `src/` 的结构，便于定位。 + +## 目录说明 + +| 子目录 | 用途 | 特点 | +|--------|------|------| +| `unit/` | 单元测试 | 测试最小单元（函数、方法），不依赖外部系统 | +| `integration/` | 集成测试 | 测试模块间交互，或与外部系统（数据库、API）的集成 | +| `e2e/` | 端到端测试 | 模拟用户行为，从入口到出口的完整链路 | + +## 测试原则 + +1. **先写测试，再写代码**（推荐 TDD） +2. 每个 bug 修复都应伴随对应的回归测试 +3. 测试用例命名应清晰描述测试场景：`<被测方法>_<场景>_<预期结果>` +4. 保持测试独立：单个测试不应依赖其他测试的运行顺序 diff --git a/test/integration/index.md b/test/integration/index.md new file mode 100644 index 0000000..4d0f60b --- /dev/null +++ b/test/integration/index.md @@ -0,0 +1,15 @@ +# test/integration — 集成测试 + +测试多个模块之间的协作，或与外部系统（数据库、消息队列、API）的集成。 + +## 原则 + +- **真实交互** — 连接真实的（或测试专用）外部系统 +- **关键路径** — 优先覆盖核心业务流程 +- **可重复** — 每次运行结果一致（注意数据准备和清理） + +## 示例 + +- 数据库读写操作的正确性 +- API 请求/响应完整链路 +- 消息队列的生产/消费 diff --git a/test/unit/index.md b/test/unit/index.md new file mode 100644 index 0000000..0eb3857 --- /dev/null +++ b/test/unit/index.md @@ -0,0 +1,17 @@ +# test/unit — 单元测试 + +测试最小单元：单个函数、方法、类。不依赖网络、数据库、文件系统等外部资源。 + +## 原则 + +- **快速** — 毫秒级完成，可频繁运行 +- **隔离** — 不依赖外部系统，使用 Mock / Stub 替代 +- **全覆盖** — 正常路径、异常路径、边界条件 + +## 命名示例 + +``` +UserService.test.ts +loginHandler_test.go +test_calculator.py +``` diff --git a/verify/checklist/index.md b/verify/checklist/index.md new file mode 100644 index 0000000..7813faa --- /dev/null +++ b/verify/checklist/index.md @@ -0,0 +1,36 @@ +# verify/checklist — 检查清单 + +本目录存放各环节的检查清单。 + +## 清单模板 + +以**上线检查清单**为例： + +```markdown +# 上线检查清单 + +## 代码质量 +- [ ] 代码审查已完成 +- [ ] 所有测试通过 +- [ ] 无已知 P0/P1 Bug +- [ ] 代码已合并到主分支 + +## 性能与安全 +- [ ] 性能测试通过 +- [ ] 安全扫描通过 +- [ ] 敏感信息已清理 + +## 运维准备 +- [ ] 数据库变更脚本就绪 +- [ ] 回滚方案已准备 +- [ ] 监控和告警已配置 + +## 文档 +- [ ] CHANGELOG 已更新 +- [ ] 版本号已更新 +- [ ] API 文档已更新（如有） +``` + +--- + +> 根据项目实际情况增删条目。 diff --git a/verify/index.md b/verify/index.md new file mode 100644 index 0000000..90d984d --- /dev/null +++ b/verify/index.md @@ -0,0 +1,22 @@ +# verify — 验证与质量保障 + +本目录存放与质量验证相关的文档和检查清单。 + +## 目录结构 + +``` +verify/ +├── README.md # 本文件 +└── checklist/ # 检查清单 +``` + +## 用途 + +- 上线前检查清单 +- 发布验收清单 +- 代码审查清单 +- 安全审计清单 + +--- + +> 与 `test/` 的区别：`test/` 是**自动化代码测试**，`verify/` 是**人工检查清单和验证流程**。