jsharness 1.0.0

package/.harness/dev-map/backend/api-definition.md

@@ -0,0 +1,131 @@
+# 后端分区 — API 设计规范
+
+## RESTful API 设计原则
+
+### URL 设计
+
+```
+# 基础路径
+/api/v1/{resource}
+
+# 资源命名：名词复数
+GET    /api/v1/users              # 用户列表
+GET    /api/v1/users/:id           # 单个用户
+POST   /api/v1/users              # 创建用户
+PUT    /api/v1/users/:id           # 全量更新
+PATCH  /api/v1/users/:id           # 部分更新
+DELETE /api/v1/users/:id           # 删除用户
+
+# 子资源
+GET    /api/v1/users/:id/orders    # 用户的订单列表
+
+# 动作（非 CRUD 操作用动词）
+POST   /api/v1/users/:id/activate   # 激活用户
+POST   /api/v1/orders/:id/cancel    # 取消订单
+POST   /api/v1/auth/refresh          # 刷新 Token
+
+# 过滤/排序/分页
+GET    /api/v1/users?role=admin&page=1&pageSize=20&sort=createdAt-desc
+```
+
+### 统一响应格式
+
+#### 成功响应
+
+```json
+{
+  "code": 0,
+  "data": { ... },
+  "message": "success",
+  "timestamp": 1700000000000
+}
+```
+
+#### 列表响应（含分页）
+
+```json
+{
+  "code": 0,
+  "data": {
+    "items": [ ... ],
+    "pagination": {
+      "page": 1,
+      "pageSize": 20,
+      "total": 150,
+      "totalPages": 8
+    }
+  },
+  "message": "success",
+  "timestamp": 1700000000000
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 20001,
+  "message": "参数校验失败",
+  "details": [
+    {
+      "field": "email",
+      "message": "邮箱格式无效",
+      "code": "INVALID_EMAIL"
+    }
+  ],
+  "timestamp": 1700000000000
+}
+```
+
+### HTTP 状态码使用
+
+| 场景 | Status Code | 说明 |
+|------|-------------|------|
+| 成功 GET | 200 | 正常返回 |
+| 成功创建 | 201 | Created（返回新资源的 Location header）|
+| 成功删除 | 204 | No Content |
+| 参数错误 | 400 | Bad Request（附详细错误信息）|
+| 未认证 | 401 | Unauthorized（Token 缺失或过期）|
+| 无权限 | 403 | Forbidden（已认证但权限不足）|
+| 资源不存在 | 404 | Not Found |
+| 方法不允许 | 405 | Method Not Allowed |
+| 冲突 | 409 | Conflict（如唯一键冲突）|
+| 未验证 | 422 | Unprocessable Entity（校验失败）|
+| 太多请求 | 429 | Too Many Requests（限流）|
+| 服务器错误 | 500 | Internal Server Error |
+| 未实现 | 501 | Not Implemented |
+
+### 分页标准参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `page` | integer | 1 | 页码（从 1 开始）|
+| `pageSize` | integer | 20 | 每页数量（最大 100）|
+| `sort` | string | `-createdAt` | 排序字段（`-` 表示降序）|
+
+### 过滤参数
+
+```
+GET /api/v1/users?role=admin&status=active&q=keyword&createdAfter=2026-01-01
+
+常用过滤参数：
+- q / keyword     关键词搜索
+- status          状态过滤
+- {fieldName}     字段精确匹配
+- {fieldFrom}/{fieldTo}  范围查询
+- createdAfter/Before   时间范围
+```
+
+## API 版本控制
+
+```
+URL 版本化策略：
+/api/v1/...   → 当前稳定版本
+/api/v2/...   → 未来新版本
+
+兼容性承诺：
+- v1 API 至少维护 2 个大版本周期
+- 新增字段不影响旧版 client
+- 废弃接口在 Response Header 中标注 Deprecated
+- 移除接口至少提前 30 天通知
+```

package/.harness/dev-map/backend/auth-security.md

@@ -0,0 +1,131 @@
+# 后端分区 — 认证与安全机制
+
+## 认证方案：JWT 双 Token 机制
+
+### Token 结构
+
+```
+┌─────────────────────────────────────────────────┐
+│                  Access Token                     │
+│  类型: JWT (HS256)                               │
+│  有效期: 15 分钟                                  │
+│  Payload: { sub, role, iat, exp, jti }           │
+│  存储: 内存 (前端) / Cookie HttpOnly (可选)      │
+└─────────────────────────────────────────────────┘
+                         +
+                         │ (access_token 过期时使用)
+                         ▼
+┌─────────────────────────────────────────────────┐
+│                 Refresh Token                    │
+│  类型: Opaque Random String (64 bytes)          │
+│  有效期: 7 天                                   │
+│  存储: DB sessions 表 + HttpOnly Secure Cookie  │
+│  用途: 获取新的 Access Token                    │
+│  轮转: 每次使用后生成新的 Refresh Token          │
+└─────────────────────────────────────────────────┘
+```
+
+### 认证流程
+
+```
+1. 登录
+   POST /api/v1/auth/login
+   → { access_token, refresh_token (HttpOnly cookie), expires_in }
+   
+2. 正常请求
+   GET /api/v1/profile
+   Header: Authorization: Bearer <access_token>
+   
+3. Access Token 过期
+   GET /api/v1/profile → 401 Unauthorized
+   
+4. 自动刷新
+   POST /api/v1/auth/refresh
+   Body: { refresh_token } 或从 Cookie 读取
+   → { new_access_token, new_refresh_token }
+   
+5. 重新发起请求
+   GET /api/v1/profile
+   Header: Authorization: Bearer <new_access_token>
+   → 200 OK
+```
+
+## 授权机制：RBAC（基于角色的访问控制）
+
+### 角色定义
+
+| 角色 | 权限范围 | 典型用户 |
+|------|----------|----------|
+| `super_admin` | 全部权限 | 系统管理员 |
+| `admin` | 管理后台全部 | 业务管理员 |
+| `editor` | 内容增删改 | 内容运营 |
+| `viewer` | 只读访问 | 只读用户 |
+| `user` | 自身数据的读写 | 普通注册用户 |
+
+### 权限守卫实现
+
+```typescript
+@UseGuards(JwtAuthGuard)
+@Roles(Role.ADMIN, Role.EDITOR)
+@Controller('admin/posts')
+export class AdminPostController {
+  // 只有 admin 和 editor 才能访问
+  @Post()
+  createPost() {}
+}
+
+@Roles(Role.ADMIN)  // 只有 admin
+@Delete(':id')
+deletePost() {}
+```
+
+### 权限矩阵
+
+| 资源/操作 | super_admin | admin | editor | viewer | user |
+|-----------|:-----------:|:-----:|:------:|:------:|:----:|
+| 用户管理 CRUD | ✅ | ✅ | ❌ | ❌ | 自身 |
+| 内容发布 | ✅ | ✅ | ✅ | ❌ | ❌ |
+| 内容编辑 | ✅ | ✅ | 自身 | ❌ | ❌ |
+| 内容删除 | ✅ | ✅ | ❌ | ❌ | ❌ |
+| 数据查看 | ✅ | ✅ | ✅ | ✅ | 自身 |
+| 系统配置 | ✅ | ❌ | ❌ | ❌ | ❌ |
+
+## 安全中间件链
+
+```
+请求进入
+  │
+  ├── Helmet (安全头设置)
+  │   ├── X-Frame-Options: DENY
+  │   ├── X-Content-Type-Options: nosniff
+  │   └── X-XSS-Protection: 1; mode=block
+  │
+  ├── Rate Limiter (速率限制)
+  │   ├── 全局: 100 req/min
+  │   ├── 登录: 5 req/min (同一 IP)
+  │   └── API: 60 req/min (同一用户)
+  │
+  ├── CORS (跨域控制)
+  │   ├── Allow-Origin: [白名单]
+  │   ├── Allow-Methods: GET,POST,PUT,DELETE
+  │   └── Credentials: true
+  │
+  ├── JwtAuthGuard (JWT 认证)
+  │   ├── 白名单路径跳过: /health, /public/*
+  │   └── 提取 payload → 注入 request.user
+  │
+  └── RolesGuard (角色鉴权)
+      ├── 检查用户角色是否匹配 @Roles()
+      └── 不匹配 → 403 Forbidden
+```
+
+## 安全 Checklist
+
+- [ ] 所有敏感接口都有认证保护
+- [ ] Password 使用 bcrypt (cost ≥ 12) 哈希存储
+- [ ] Refresh Token 支持吊销（logout 时失效）
+- [ ] 登录限制：连续 5 次失败锁定 15 分钟
+- [ ] CSRF Token 保护写操作（如果使用 Cookie）
+- [ ] SQL 注入防护：全部参数化查询
+- [ ] XSS 防护：输出转义、CSP 策略
+- [ ] 日志脱敏：不记录 password/token 等敏感字段