项目初始化

2026-05-21 20:32:32 +08:00 · 2026-05-21 20:32:32 +08:00 · aca7dc999e
commit aca7dc999e
25 changed files with 782 additions and 0 deletions
--- a/.gitignore
+++ 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/
--- a/CHANGELOG.md
+++ 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/
--- a/CLAUDE.md
+++ 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.
--- a/CONTRIBUTING.md
+++ 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>(<scope>): <subject>
+
+类型（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/` 记录
--- a/21
+++ b/21
@ -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.
--- a/README.md
+++ 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 <repo-url>
+cd <project-name>
+
+# [安装 / 构建 / 运行步骤，根据项目补充]
+```
+
+## 文档导航
+
+| 你想做的事 | 去哪看 |
+|------------|--------|
+| 了解项目背景和架构 | `docs/design/architecture/` |
+| 查看需求与变更 | `docs/requirements/` |
+| 查看功能设计 | `docs/features/` |
+| 查看任务进度 | `docs/implementation/tasks/` |
+| 参与开发 | `CONTRIBUTING.md` |
+| 查看版本历史 | `CHANGELOG.md` |
+
+## 维护者
+
+- [@维护者](https://github.com/xxx)
+
+## 许可证
+
+[LICENSE](./LICENSE)
--- a/1
+++ b/1
@ -0,0 +1 @@
+0.1.0
--- a/docs/design/architecture/index.md
+++ 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/)
--- a/docs/design/index.md
+++ 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 工具解析。
--- a/docs/design/technical/index.md
+++ b/docs/design/technical/index.md
@ -0,0 +1,51 @@
+# docs/design/technical — 技术方案
+
+本目录存放各模块的详细技术设计方案。
+
+## 文件命名
+
+```
+<模块名>-技术方案.md
+```
+
+## 技术方案模板
+
+```markdown
+# [模块名] 技术方案
+
+- **版本**：v[版本号]
+- **作者**：[姓名]
+- **日期**：YYYY-MM-DD
+- **状态**：草稿 / 评审中 / 已定稿
+
+## 1. 概述
+
+> 本方案解决什么问题？适用范围是什么？
+
+## 2. 设计目标
+
+- 功能目标
+- 非功能目标（性能、安全、可扩展性等）
+
+## 3. 方案描述
+
+### 3.1 整体流程
+
+<!-- 推荐使用 Mermaid 绘制流程图 -->
+
+### 3.2 接口设计
+
+### 3.3 数据模型
+
+### 3.4 关键逻辑
+
+## 4. 风险与应对
+
+| 风险 | 影响 | 应对措施 |
+|------|------|----------|
+| ... | ... | ... |
+
+## 5. 参考
+
+- [相关文档链接]
+```
--- a/docs/features/index.md
+++ 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`
+```
--- a/docs/implementation/index.md
+++ b/docs/implementation/index.md
@ -0,0 +1,17 @@
+# docs/implementation — 实施与跟踪
+
+本目录用于管理开发实施计划和任务进度。
+
+## 目录结构
+
+```
+implementation/
+├── index.md         # 本文件
+└── tasks/           # 任务拆分与进度跟踪
+```
+
+## 使用方式
+
+1. 将功能需求拆分为可执行的任务
+2. 每个迭代/功能一个任务文件，记录在 `tasks/` 下
+3. 任务文件中用 Checkbox 标记进度
--- a/docs/implementation/tasks/index.md
+++ 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 | ... |
+```
--- a/docs/index.md
+++ b/docs/index.md
@ -0,0 +1,18 @@
+# docs — 开发文档
+
+本目录存放项目的全部开发文档，涵盖需求、设计、功能规格和实施跟踪。
+
+## 目录说明
+
+| 子目录 | 用途 | 受众 |
+|--------|------|------|
+| `requirements/` | 需求与变更管理 | 产品、开发、测试 |
+| `design/` | 架构设计与技术方案 | 开发、架构师 |
+| `features/` | 功能规格说明 | 开发、测试、产品 |
+| `implementation/` | 实施计划与任务跟踪 | 开发、项目管理 |
+
+## 使用原则
+
+1. 文档**与代码同步更新**，不是一次性交付物
+2. 优先用 Markdown，便于版本控制和 AI 工具阅读
+3. 每个文档文件保持聚焦，一个文件讲清一件事
--- a/docs/requirements/changes/index.md
+++ b/docs/requirements/changes/index.md
@ -0,0 +1,11 @@
+# docs/requirements/changes — 需求变更记录
+
+每条需求变更一个文件，便于追溯和评审。
+
+## 变更记录文件命名
+
+```
+YYYY-MM-DD-<简短描述>.md
+```
+
+示例：`2025-01-15-登录支持短信验证码.md`
--- a/docs/requirements/index.md
+++ 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` 文件，便于版本控制和追溯。
--- a/scripts/index.md
+++ b/scripts/index.md
@ -0,0 +1,9 @@
+# scripts — 工具脚本
+
+本目录存放项目的辅助脚本：构建、部署、数据迁移、环境初始化等。
+
+## 原则
+
+- 每个脚本做好注释，说明用途和运行方式
+- 脚本应尽量幂等（多次运行结果一致）
+- 避免将敏感信息（密码、密钥）硬编码在脚本中
--- a/skills/index.md
+++ b/skills/index.md
@ -0,0 +1,17 @@
+# skills — AI 辅助技能
+
+本目录用于存放项目专属的 AI 辅助技能 / 提示词，帮助 AI 编码助手更好地理解项目上下文。
+
+## 用途
+
+- 项目特定的编码规范和约定
+- 代码审查清单
+- 自动化提示词（如：生成测试、生成文档等）
+
+## 使用方式
+
+将自定义的提示词文件放入本目录，并按需要引用。
+
+---
+
+> 当前为空，可根据团队需要添加。
--- a/src/index.md
+++ b/src/index.md
@ -0,0 +1,27 @@
+# src — 源代码
+
+本目录存放项目的全部源代码。
+
+## 组织原则
+
+- 按模块/功能划分子目录，避免扁平结构过于庞大
+- 公共组件、工具函数独立成目录或模块
+- 保持目录层级不超过 3-4 层
+
+## 推荐结构
+
+```
+src/
+├── core/          # 核心业务逻辑
+├── utils/         # 通用工具函数
+├── models/        # 数据模型 / 实体
+├── services/      # 服务层（如有）
+├── api/           # API 接口层（如有）
+└── main.*         # 入口文件
+```
+
+## 注意事项
+
+- 该结构为建议，请根据项目实际技术栈和框架调整
+- 保持模块间低耦合、高内聚
+- 公共代码优先放在 `utils/` 或独立模块中
--- a/test/e2e/index.md
+++ b/test/e2e/index.md
@ -0,0 +1,14 @@
+# test/e2e — 端到端测试
+
+模拟真实用户行为，从系统入口到出口的完整链路测试。
+
+## 原则
+
+- **用户视角** — 模拟用户操作流程
+- **环境一致** — 尽量在类生产环境中运行
+- **场景驱动** — 聚焦核心用户场景，避免测试琐碎细节
+
+## 示例
+
+- 用户注册 → 登录 → 操作 → 退出 完整流程
+- 订单创建 → 支付 → 状态变更 完整链路
--- a/test/index.md
+++ b/test/index.md
@ -0,0 +1,18 @@
+# test — 测试代码
+
+本目录存放项目的全部测试代码。测试代码的组织结构应**镜像** `src/` 的结构，便于定位。
+
+## 目录说明
+
+| 子目录 | 用途 | 特点 |
+|--------|------|------|
+| `unit/` | 单元测试 | 测试最小单元（函数、方法），不依赖外部系统 |
+| `integration/` | 集成测试 | 测试模块间交互，或与外部系统（数据库、API）的集成 |
+| `e2e/` | 端到端测试 | 模拟用户行为，从入口到出口的完整链路 |
+
+## 测试原则
+
+1. **先写测试，再写代码**（推荐 TDD）
+2. 每个 bug 修复都应伴随对应的回归测试
+3. 测试用例命名应清晰描述测试场景：`<被测方法>_<场景>_<预期结果>`
+4. 保持测试独立：单个测试不应依赖其他测试的运行顺序
--- a/test/integration/index.md
+++ b/test/integration/index.md
@ -0,0 +1,15 @@
+# test/integration — 集成测试
+
+测试多个模块之间的协作，或与外部系统（数据库、消息队列、API）的集成。
+
+## 原则
+
+- **真实交互** — 连接真实的（或测试专用）外部系统
+- **关键路径** — 优先覆盖核心业务流程
+- **可重复** — 每次运行结果一致（注意数据准备和清理）
+
+## 示例
+
+- 数据库读写操作的正确性
+- API 请求/响应完整链路
+- 消息队列的生产/消费
--- a/test/unit/index.md
+++ b/test/unit/index.md
@ -0,0 +1,17 @@
+# test/unit — 单元测试
+
+测试最小单元：单个函数、方法、类。不依赖网络、数据库、文件系统等外部资源。
+
+## 原则
+
+- **快速** — 毫秒级完成，可频繁运行
+- **隔离** — 不依赖外部系统，使用 Mock / Stub 替代
+- **全覆盖** — 正常路径、异常路径、边界条件
+
+## 命名示例
+
+```
+UserService.test.ts
+loginHandler_test.go
+test_calculator.py
+```
--- a/verify/checklist/index.md
+++ b/verify/checklist/index.md
@ -0,0 +1,36 @@
+# verify/checklist — 检查清单
+
+本目录存放各环节的检查清单。
+
+## 清单模板
+
+以**上线检查清单**为例：
+
+```markdown
+# 上线检查清单
+
+## 代码质量
+- [ ] 代码审查已完成
+- [ ] 所有测试通过
+- [ ] 无已知 P0/P1 Bug
+- [ ] 代码已合并到主分支
+
+## 性能与安全
+- [ ] 性能测试通过
+- [ ] 安全扫描通过
+- [ ] 敏感信息已清理
+
+## 运维准备
+- [ ] 数据库变更脚本就绪
+- [ ] 回滚方案已准备
+- [ ] 监控和告警已配置
+
+## 文档
+- [ ] CHANGELOG 已更新
+- [ ] 版本号已更新
+- [ ] API 文档已更新（如有）
+```
+
+---
+
+> 根据项目实际情况增删条目。
--- a/verify/index.md
+++ b/verify/index.md
@ -0,0 +1,22 @@
+# verify — 验证与质量保障
+
+本目录存放与质量验证相关的文档和检查清单。
+
+## 目录结构
+
+```
+verify/
+├── README.md        # 本文件
+└── checklist/       # 检查清单
+```
+
+## 用途
+
+- 上线前检查清单
+- 发布验收清单
+- 代码审查清单
+- 安全审计清单
+
+---
+
+> 与 `test/` 的区别：`test/` 是**自动化代码测试**，`verify/` 是**人工检查清单和验证流程**。