jvibe 1.0.0

package/template/docs/project/README.md

@@ -0,0 +1,83 @@
+# PROJECT-DOCS 说明
+
+> 本目录存放**项目特定**的技术文档，与 `core/` 目录中的固定核心文档不同。
+
+---
+
+## CORE-DOCS vs PROJECT-DOCS
+
+| 维度 | CORE-DOCS（core/） | PROJECT-DOCS（project/） |
+|------|-------------------|------------------------|
+| **结构** | 所有项目中**结构相同** | 根据项目类型**按需创建** |
+| **数量** | **固定 4 个** | **可变**（0~N个） |
+| **文档** | 规范文档、项目文档、功能清单、附加材料 | API文档、数据库文档、部署文档等 |
+| **注册机制** | 固定存在，无需注册 | **必须**在规范文档中注册 |
+
+---
+
+## 如何创建 PROJECT-DOCS？
+
+### 1. 确定需要的文档类型
+
+**后端项目**：
+- [ ] API文档（REST/GraphQL端点）
+- [ ] 数据库Schema文档
+- [ ] 部署文档
+
+**前端项目**：
+- [ ] 组件文档（Storybook等）
+- [ ] 路由文档
+- [ ] 状态管理文档
+
+**全栈项目**：
+- [ ] 以上按需选择
+
+**其他**：
+- [ ] 第三方集成文档
+- [ ] 性能优化文档
+- [ ] 安全审计文档
+
+### 2. 创建文档并注册
+
+1. 在 `docs/project/` 创建文档（例如 `api.md`）
+2. **必须**在 `docs/core/规范文档.md` 的 **"Project文档注册表"** 中添加记录：
+
+```markdown
+## 2.2.1 Project文档注册表
+
+| 文档ID | 文档名称 | 位置 | 用途 | 维护者 | 状态 |
+|--------|----------|------|------|--------|------|
+| P-001  | API文档  | `docs/project/api.md` | REST API端点 | 后端 | active |
+| P-002  | 数据库Schema | `docs/project/database.md` | 表结构和ER图 | 后端 | active |
+```
+
+### 3. 文档结构要求
+
+每个 PROJECT-DOCS 必须在开头说明：
+- **是什么**：文档的用途
+- **怎么用**：如何查阅和使用
+- **更新时机**：何时需要更新此文档
+
+---
+
+## 参考示例
+
+本目录提供了示例文档供参考：
+
+| 示例文件 | 说明 |
+|----------|------|
+| `api.md.example` | API文档示例 |
+| `database.md.example` | 数据库文档示例 |
+
+使用时：
+1. 复制示例文件并重命名（去掉 `.example` 后缀）
+2. 根据项目实际情况填充内容
+3. 在规范文档中注册
+
+---
+
+## 注意事项
+
+⚠️ **所有 PROJECT-DOCS 必须在规范文档中注册**，否则视为无效文档。
+
+⚠️ **不要修改 `core/` 目录中的文档结构**，只修改内容。

package/template/docs/project/api.md.example

@@ -0,0 +1,145 @@
+# API 文档
+
+> **文档ID**: P-001
+> **维护者**: 后端团队
+> **最后更新**: YYYY-MM-DD
+
+---
+
+## 📌 文档说明
+
+**是什么**：记录项目所有 REST API 端点的详细信息。
+
+**怎么用**：
+- 开发前端时：查询可用接口
+- 联调测试时：确认请求/响应格式
+- 编写测试时：参考示例数据
+
+**更新时机**：
+- 新增 API 端点时
+- 修改请求/响应格式时
+- 变更认证方式时
+
+---
+
+## 1. 概述
+
+### 1.1 基础信息
+
+| 项目 | 值 |
+|------|-----|
+| Base URL | `https://api.example.com/v1` |
+| 认证方式 | Bearer Token (JWT) |
+| 响应格式 | JSON |
+| API 版本 | v1 |
+
+### 1.2 通用响应格式
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {}
+}
+```
+
+### 1.3 错误码说明
+
+| HTTP 状态码 | 业务码 | 说明 |
+|-------------|--------|------|
+| 200 | 0 | 成功 |
+| 400 | 1001 | 参数错误 |
+| 401 | 1002 | 未认证 |
+| 403 | 1003 | 无权限 |
+| 404 | 1004 | 资源不存在 |
+| 500 | 1005 | 服务器错误 |
+
+---
+
+## 2. 认证模块 (Auth)
+
+### 2.1 用户注册
+
+**POST** `/auth/register`
+
+**请求体**：
+```json
+{
+  "email": "user@example.com",
+  "password": "SecurePass123!",
+  "displayName": "John Doe"
+}
+```
+
+**响应**：
+```json
+{
+  "code": 200,
+  "message": "注册成功",
+  "data": {
+    "userId": "uuid-xxx",
+    "email": "user@example.com"
+  }
+}
+```
+
+### 2.2 用户登录
+
+**POST** `/auth/login`
+
+**请求体**：
+```json
+{
+  "email": "user@example.com",
+  "password": "SecurePass123!"
+}
+```
+
+**响应**：
+```json
+{
+  "code": 200,
+  "message": "登录成功",
+  "data": {
+    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
+    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
+    "expiresIn": 900
+  }
+}
+```
+
+---
+
+## 3. 用户模块 (User)
+
+### 3.1 获取用户信息
+
+**GET** `/users/:id`
+
+**请求头**：
+```
+Authorization: Bearer <accessToken>
+```
+
+**响应**：
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "id": "uuid-xxx",
+    "email": "user@example.com",
+    "displayName": "John Doe",
+    "avatarUrl": "https://..."
+  }
+}
+```
+
+---
+
+## 📋 附录
+
+### 相关文档
+
+- [规范文档](../core/规范文档.md) - 文档体系入口
+- [附加材料](../core/附加材料.md) - API 设计规范（API-001~003）

package/template/docs/project/database.md.example

@@ -0,0 +1,172 @@
+# 数据库 Schema 文档
+
+> **文档ID**: P-002
+> **维护者**: 后端团队
+> **最后更新**: YYYY-MM-DD
+
+---
+
+## 📌 文档说明
+
+**是什么**：记录项目数据库表结构、索引策略和 ER 图。
+
+**怎么用**：
+- 编写查询时：了解表结构和关联关系
+- 设计新功能时：评估数据模型影响
+- 性能优化时：查看索引设计
+
+**更新时机**：
+- 新增数据表时
+- 修改表结构时
+- 添加/修改索引时
+
+---
+
+## 1. 概述
+
+### 1.1 数据库信息
+
+| 项目 | 值 |
+|------|-----|
+| 数据库类型 | PostgreSQL |
+| 版本 | 15.5 |
+| ORM | Prisma |
+| 字符集 | UTF-8 |
+
+### 1.2 ER 图
+
+```mermaid
+erDiagram
+    users ||--o{ auth_tokens : has
+    users ||--|| user_profiles : has
+    users ||--o{ room_members : joins
+    chat_rooms ||--o{ room_members : contains
+    chat_rooms ||--o{ messages : contains
+    users ||--o{ messages : sends
+
+    users {
+        uuid id PK
+        string email UK
+        string password_hash
+        timestamp created_at
+    }
+
+    user_profiles {
+        uuid id PK
+        uuid user_id FK
+        string display_name
+        string avatar_url
+    }
+
+    chat_rooms {
+        uuid id PK
+        string name
+        string type
+        timestamp created_at
+    }
+
+    messages {
+        uuid id PK
+        uuid room_id FK
+        uuid sender_id FK
+        text content
+        timestamp sent_at
+    }
+```
+
+---
+
+## 2. 表结构详情
+
+### 2.1 users（用户表）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK | 主键 |
+| email | VARCHAR(255) | UNIQUE, NOT NULL | 邮箱 |
+| password_hash | VARCHAR(255) | NOT NULL | 密码哈希 |
+| created_at | TIMESTAMP | DEFAULT NOW() | 创建时间 |
+| updated_at | TIMESTAMP | DEFAULT NOW() | 更新时间 |
+
+**索引**：
+- `users_email_idx` (email) - 唯一索引
+
+### 2.2 user_profiles（用户资料表）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK | 主键 |
+| user_id | UUID | FK, UNIQUE | 关联用户 |
+| display_name | VARCHAR(100) | | 显示名称 |
+| avatar_url | VARCHAR(500) | | 头像URL |
+| bio | TEXT | | 个人简介 |
+
+**索引**：
+- `user_profiles_user_id_idx` (user_id) - 唯一索引
+
+### 2.3 chat_rooms（聊天室表）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK | 主键 |
+| name | VARCHAR(100) | NOT NULL | 聊天室名称 |
+| type | VARCHAR(20) | NOT NULL | 类型（private/group） |
+| created_at | TIMESTAMP | DEFAULT NOW() | 创建时间 |
+
+**索引**：
+- `chat_rooms_name_idx` (name)
+
+### 2.4 messages（消息表）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK | 主键 |
+| room_id | UUID | FK, NOT NULL | 聊天室ID |
+| sender_id | UUID | FK, NOT NULL | 发送者ID |
+| content | TEXT | NOT NULL | 消息内容 |
+| sent_at | TIMESTAMP | DEFAULT NOW() | 发送时间 |
+
+**索引**：
+- `messages_room_id_idx` (room_id)
+- `messages_sender_id_idx` (sender_id)
+- `messages_sent_at_idx` (sent_at)
+
+---
+
+## 3. 索引策略
+
+### 3.1 索引设计原则
+
+参考 [附加材料 DB-002](../core/附加材料.md)：
+- 外键字段必须建索引
+- 查询条件常用字段建索引
+- 避免过度索引
+
+### 3.2 当前索引列表
+
+| 表 | 索引名 | 字段 | 类型 |
+|-----|--------|------|------|
+| users | users_email_idx | email | UNIQUE |
+| user_profiles | user_profiles_user_id_idx | user_id | UNIQUE |
+| chat_rooms | chat_rooms_name_idx | name | BTREE |
+| messages | messages_room_id_idx | room_id | BTREE |
+| messages | messages_sender_id_idx | sender_id | BTREE |
+| messages | messages_sent_at_idx | sent_at | BTREE |
+
+---
+
+## 4. 迁移历史
+
+| 版本 | 日期 | 说明 |
+|------|------|------|
+| 001 | YYYY-MM-DD | 初始化数据库结构 |
+| 002 | YYYY-MM-DD | 添加 messages 表 |
+
+---
+
+## 📋 附录
+
+### 相关文档
+
+- [规范文档](../core/规范文档.md) - 文档体系入口
+- [附加材料](../core/附加材料.md) - 数据库设计规范（DB-001~003）