Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(admin): Add user management and upgrade to module permission system

Browse Source 
Features - User Management (Phase 4.1):
- Database: Add user_modules table for fine-grained module permissions
- Database: Add 4 user permissions (view/create/edit/delete) to role_permissions
- Backend: UserService (780 lines) - CRUD with tenant isolation
- Backend: UserController + UserRoutes (648 lines) - 13 API endpoints
- Backend: Batch import users from Excel
- Frontend: UserListPage (412 lines) - list/filter/search/pagination
- Frontend: UserFormPage (341 lines) - create/edit with module config
- Frontend: UserDetailPage (393 lines) - details/tenant/module management
- Frontend: 3 modal components (592 lines) - import/assign/configure
- API: GET/POST/PUT/DELETE /api/admin/users/* endpoints

Architecture Upgrade - Module Permission System:
- Backend: Add getUserModules() method in auth.service
- Backend: Login API returns modules array in user object
- Frontend: AuthContext adds hasModule() method
- Frontend: Navigation filters modules based on user.modules
- Frontend: RouteGuard checks requiredModule instead of requiredVersion
- Frontend: Remove deprecated version-based permission system
- UX: Only show accessible modules in navigation (clean UI)
- UX: Smart redirect after login (avoid 403 for regular users)

Fixes:
- Fix UTF-8 encoding corruption in ~100 docs files
- Fix pageSize type conversion in userService (String to Number)
- Fix authUser undefined error in TopNavigation
- Fix login redirect logic with role-based access check
- Update Git commit guidelines v1.2 with UTF-8 safety rules

Database Changes:
- CREATE TABLE user_modules (user_id, tenant_id, module_code, is_enabled)
- ADD UNIQUE CONSTRAINT (user_id, tenant_id, module_code)
- INSERT 4 permissions + role assignments
- UPDATE PUBLIC tenant with 8 module subscriptions

Technical:
- Backend: 5 new files (~2400 lines)
- Frontend: 10 new files (~2500 lines)
- Docs: 1 development record + 2 status updates + 1 guideline update
- Total: ~4900 lines of code

Status: User management 100% complete, module permission system operational
This commit is contained in:
HaHafeng
2026-01-16 13:42:10 +08:00
parent 98d862dbd4
commit 66255368b7
560 changed files with 70424 additions and 52353 deletions
Download Patch File Download Diff File Expand all files Collapse all files

168
docs/_templates/API设计-模板.md vendored
View File

@@ -1,8 +1,8 @@
# [模块名称] - API设计
> **<EFBFBD>箇<EFBFBD>頝臬<EFBFBD>嚗?* `/api/v1/璅∪<EFBFBD><EFBFBD>崾
> **蝡舐<EFBFBD><EFBFBD>圈<EFBFBD>嚗?* X銝?
> **霈方<EFBFBD>閬<EFBFBD><EFBFBD>嚗?* JWT Token
> **基础路径：** `/api/v1/模块名`
> **端点数量：** X个
> **认证要求：** JWT Token
> **最后更新：** YYYY-MM-DD
---
@@ -11,11 +11,11 @@
| 端点 | 方法 | 说明 | 认证 |
|------|------|------|------|
| `/api/v1/xxx/resources` | GET | <EFBFBD>瑕<EFBFBD>韏<EFBFBD><EFBFBD><EFBFBD>𡑒” | <EFBFBD>?|
| `/api/v1/xxx/resources/:id` | GET | <EFBFBD>瑕<EFBFBD>韏<EFBFBD><EFBFBD>霂行<EFBFBD> | <EFBFBD>?|
| `/api/v1/xxx/resources` | POST | <EFBFBD>𥕦遣韏<EFBFBD><EFBFBD> | <EFBFBD>?|
| `/api/v1/xxx/resources/:id` | PUT | <EFBFBD>湔鰵韏<EFBFBD><EFBFBD> | <EFBFBD>?|
| `/api/v1/xxx/resources/:id` | DELETE | <EFBFBD>𣳇膄韏<EFBFBD><EFBFBD> | <EFBFBD>?|
| `/api/v1/xxx/resources` | GET | 获取资源列表 | ✅ |
| `/api/v1/xxx/resources/:id` | GET | 获取资源详情 | ✅ |
| `/api/v1/xxx/resources` | POST | 创建资源 | ✅ |
| `/api/v1/xxx/resources/:id` | PUT | 更新资源 | ✅ |
| `/api/v1/xxx/resources/:id` | DELETE | 删除资源 | ✅ |
---
@@ -23,31 +23,31 @@
### 1. 获取资源列表
**蝡舐<EFBFBD>嚗?* `GET /api/v1/xxx/resources`
**端点：** `GET /api/v1/xxx/resources`
**<EFBFBD>券<EFBFBD>䈑<EFBFBD>** <20>瑕<EFBFBD>敶枏<E695B6><E69E8F>冽<EFBFBD><E586BD><EFBFBD><EFBFBD>皞𣂼<E79A9E>銵剁<E98AB5><E58981><EFBFBD>△嚗?
**用途：** 获取当前用户的资源列表（分页）
**霂瑟<EFBFBD><EFBFBD><EFBFBD>㺭嚗?*
**请求参数：**
**Query<EFBFBD><EFBFBD>㺭嚗?*
**Query参数：**
```typescript
{
page?: number; // 憿萇<EFBFBD>嚗屸<EFBFBD>霈?
pageSize?: number; // 瘥誯△<EFBFBD>圈<EFBFBD>嚗屸<EFBFBD>霈?0嚗峕<E59A97>憭?00
status?: string; // 蝑偦<EFBFBD>㚁<EFBFBD><EFBFBD>嗆<EFBFBD><EFBFBD><EFBFBD>active/inactive嚗?
keyword?: string; // <EFBFBD>𦦵揣<EFBFBD>喲睸霂?
sortBy?: string; // <EFBFBD>鍦<EFBFBD>摮埈挾嚗ẾreatedAt/updatedAt嚗?
page?: number; // 页码，默认1
pageSize?: number; // 每页数量，默认10，最大100
status?: string; // 筛选：状态（active/inactive）
keyword?: string; // 搜索关键词
sortBy?: string; // 排序字段（createdAt/updatedAt）
sortOrder?: 'asc' | 'desc'; // 排序方向，默认desc
}
```
**霂瑟<EFBFBD>蝷箔<EFBFBD>嚗?*
**请求示例：**
```bash
GET /api/v1/xxx/resources?page=1&pageSize=10&status=active
Authorization: Bearer <token>
```
**<EFBFBD>𣂼<EFBFBD><EFBFBD>滚<EFBFBD>嚗?* `200 OK`
**成功响应：** `200 OK`
```json
{
"success": true,
@@ -74,7 +74,7 @@ Authorization: Bearer <token>
}
```
**<EFBFBD>躰秤<EFBFBD>滚<EFBFBD>嚗?*
**错误响应：**
```json
// 401 Unauthorized
{
@@ -92,7 +92,7 @@ Authorization: Bearer <token>
"code": "INVALID_PARAMS",
"message": "参数错误",
"details": [
{ "field": "pageSize", "message": "<EFBFBD><EFBFBD>憭找<EFBFBD><EFBFBD>質<EFBFBD>餈?00" }
{ "field": "pageSize", "message": "最大不能超过100" }
]
}
}
@@ -102,20 +102,20 @@ Authorization: Bearer <token>
### 2. 获取资源详情
**蝡舐<EFBFBD>嚗?* `GET /api/v1/xxx/resources/:id`
**端点：** `GET /api/v1/xxx/resources/:id`
**<EFBFBD>券<EFBFBD>䈑<EFBFBD>** <20>瑕<EFBFBD><E79195><EFBFBD><EFBFBD>韏<EFBFBD><E99F8F><EFBFBD><EFBFBD>祕蝏<E7A595>縑<EFBFBD>?
**用途：** 获取指定资源的详细信息
**頝臬<EFBFBD><EFBFBD><EFBFBD>㺭嚗?*
**路径参数：**
- `id` (必填): 资源ID
**霂瑟<EFBFBD>蝷箔<EFBFBD>嚗?*
**请求示例：**
```bash
GET /api/v1/xxx/resources/123
Authorization: Bearer <token>
```
**<EFBFBD>𣂼<EFBFBD><EFBFBD>滚<EFBFBD>嚗?* `200 OK`
**成功响应：** `200 OK`
```json
{
"success": true,
@@ -127,24 +127,24 @@ Authorization: Bearer <token>
"status": "active",
"createdAt": "2025-11-06T10:00:00.000Z",
"updatedAt": "2025-11-06T10:00:00.000Z",
// 憸嘥<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>娍㺭<EFBFBD>?
// 额外的关联数据
"user": {
"id": 456,
"name": "<EFBFBD>冽<EFBFBD><EFBFBD>?
"name": "用户名"
}
},
"message": "获取成功"
}
```
**<EFBFBD>躰秤<EFBFBD>滚<EFBFBD>嚗?*
**错误响应：**
```json
// 404 Not Found
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "韏<EFBFBD><EFBFBD>銝滚<EFBFBD><EFBFBD>?
"message": "资源不存在"
}
}
@@ -153,7 +153,7 @@ Authorization: Bearer <token>
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "<EFBFBD>䭾<EFBFBD>霈輸䔮甇方<EFBFBD>皞?
"message": "无权访问此资源"
}
}
```
@@ -162,44 +162,44 @@ Authorization: Bearer <token>
### 3. 创建资源
**蝡舐<EFBFBD>嚗?* `POST /api/v1/xxx/resources`
**端点：** `POST /api/v1/xxx/resources`
**<EFBFBD>券<EFBFBD>䈑<EFBFBD>** <20>𥕦遣<F0A595A6>啗<EFBFBD>皞?
**用途：** 创建新资源
**请求体：**
```json
{
"fieldName": "韏<EFBFBD><EFBFBD><EFBFBD>滨妍", // 敹<EFBFBD>‵嚗屸鵭摨?-200
"description": "<EFBFBD>讛膩", // <EFBFBD>舫<EFBFBD>㚁<EFBFBD><EFBFBD><EFBFBD>憭?000摮?
"fieldName": "资源名称", // 必填，长度2-200
"description": "描述", // 可选，最大5000字
"status": "active" // 可选，默认active
}
```
**撉諹<EFBFBD>閫<EFBFBD><EFBFBD>嚗?*
- `fieldName`: 敹<EFBFBD>‵嚗?-200摮㛖泵嚗䔶<E59A97><E494B6>賢<EFBFBD><E8B3A2>怎鸌畾𠰴<E795BE>蝚?
- `description`: <EFBFBD>舫<EFBFBD>㚁<EFBFBD><EFBFBD><EFBFBD>憭?000摮㛖泵
**验证规则：**
- `fieldName`: 必填，2-200字符，不能包含特殊字符
- `description`: 可选，最大5000字符
- `status`: 可选，有效值：active, inactive
**霂瑟<EFBFBD>蝷箔<EFBFBD>嚗?*
**请求示例：**
```bash
POST /api/v1/xxx/resources
Authorization: Bearer <token>
Content-Type: application/json
{
"fieldName": "<EFBFBD>啗<EFBFBD>皞?,
"fieldName": "新资源",
"description": "这是一个新资源"
}
```
**<EFBFBD>𣂼<EFBFBD><EFBFBD>滚<EFBFBD>嚗?* `201 Created`
**成功响应：** `201 Created`
```json
{
"success": true,
"data": {
"id": 124,
"userId": 456,
"fieldName": "<EFBFBD>啗<EFBFBD>皞?,
"fieldName": "新资源",
"description": "这是一个新资源",
"status": "active",
"createdAt": "2025-11-06T10:00:00.000Z",
@@ -209,7 +209,7 @@ Content-Type: application/json
}
```
**<EFBFBD>躰秤<EFBFBD>滚<EFBFBD>嚗?*
**错误响应：**
```json
// 422 Unprocessable Entity
{
@@ -219,7 +219,7 @@ Content-Type: application/json
"message": "参数验证失败",
"details": [
{ "field": "fieldName", "message": "字段名称不能为空" },
{ "field": "fieldName", "message": "摮埈挾<EFBFBD>滨妍<EFBFBD>踹漲敹<EFBFBD>◆<EFBFBD>?-200銋钅𡢿" }
{ "field": "fieldName", "message": "字段名称长度必须在2-200之间" }
]
}
}
@@ -238,11 +238,11 @@ Content-Type: application/json
### 4. 更新资源
**蝡舐<EFBFBD>嚗?* `PUT /api/v1/xxx/resources/:id`
**端点：** `PUT /api/v1/xxx/resources/:id`
**用途：** 更新指定资源（完整更新）
**頝臬<EFBFBD><EFBFBD><EFBFBD>㺭嚗?*
**路径参数：**
- `id` (必填): 资源ID
**请求体：**
@@ -254,7 +254,7 @@ Content-Type: application/json
}
```
**霂瑟<EFBFBD>蝷箔<EFBFBD>嚗?*
**请求示例：**
```bash
PUT /api/v1/xxx/resources/123
Authorization: Bearer <token>
@@ -266,7 +266,7 @@ Content-Type: application/json
}
```
**<EFBFBD>𣂼<EFBFBD><EFBFBD>滚<EFBFBD>嚗?* `200 OK`
**成功响应：** `200 OK`
```json
{
"success": true,
@@ -280,14 +280,14 @@ Content-Type: application/json
}
```
**<EFBFBD>躰秤<EFBFBD>滚<EFBFBD>嚗?*
**错误响应：**
```json
// 404 Not Found
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "韏<EFBFBD><EFBFBD>銝滚<EFBFBD><EFBFBD>?
"message": "资源不存在"
}
}
@@ -296,7 +296,7 @@ Content-Type: application/json
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "<EFBFBD>䭾<EFBFBD>靽格㺿甇方<EFBFBD>皞?
"message": "无权修改此资源"
}
}
```
@@ -305,20 +305,20 @@ Content-Type: application/json
### 5. 删除资源
**蝡舐<EFBFBD>嚗?* `DELETE /api/v1/xxx/resources/:id`
**端点：** `DELETE /api/v1/xxx/resources/:id`
**<EFBFBD>券<EFBFBD>䈑<EFBFBD>** <20>𣳇膄<F0A3B387><E88684><EFBFBD>韏<EFBFBD><E99F8F>嚗<EFBFBD>蔓<EFBFBD>𣳇膄嚗?
**用途：** 删除指定资源（软删除）
**頝臬<EFBFBD><EFBFBD><EFBFBD>㺭嚗?*
**路径参数：**
- `id` (必填): 资源ID
**霂瑟<EFBFBD>蝷箔<EFBFBD>嚗?*
**请求示例：**
```bash
DELETE /api/v1/xxx/resources/123
Authorization: Bearer <token>
```
**<EFBFBD>𣂼<EFBFBD><EFBFBD>滚<EFBFBD>嚗?* `200 OK`
**成功响应：** `200 OK`
```json
{
"success": true,
@@ -327,14 +327,14 @@ Authorization: Bearer <token>
}
```
**<EFBFBD>躰秤<EFBFBD>滚<EFBFBD>嚗?*
**错误响应：**
```json
// 404 Not Found
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "韏<EFBFBD><EFBFBD>銝滚<EFBFBD><EFBFBD>?
"message": "资源不存在"
}
}
@@ -343,7 +343,7 @@ Authorization: Bearer <token>
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "<EFBFBD>䭾<EFBFBD><EFBFBD>𣳇膄甇方<EFBFBD>皞?
"message": "无权删除此资源"
}
}
@@ -352,37 +352,37 @@ Authorization: Bearer <token>
"success": false,
"error": {
"code": "CANNOT_DELETE",
"message": "霂亥<EFBFBD>皞鞉<EFBFBD><EFBFBD>唾<EFBFBD><EFBFBD>唳旿嚗峕<EFBFBD>瘜訫<EFBFBD><EFBFBD>?
"message": "该资源有关联数据，无法删除"
}
}
```
---
## <EFBFBD><EFBFBD> 霈方<E99C88>銝擧<E98A9D><E693A7>?
## 🔐 认证与权限
### 认证方式
<EFBFBD><EFBFBD><EFBFBD>𡅅PI<EFBFBD>賡<EFBFBD>閬<EFBFBD>WT Token霈方<EFBFBD>嚗?
所有API都需要JWT Token认证：
```
Authorization: Bearer <token>
```
### <EFBFBD><EFBFBD><EFBFBD>璉<EFBFBD><EFBFBD>?
- <EFBFBD>冽<EFBFBD><EFBFBD>芾<EFBFBD>霈輸䔮<EFBFBD>芸楛<EFBFBD><EFBFBD><EFBFBD>皞?
- ADMIN閫坿𠧧<EFBFBD>臭誑霈輸䔮<EFBFBD><EFBFBD><EFBFBD>㕑<EFBFBD>皞?
### 权限检查
- 用户只能访问自己的资源
- ADMIN角色可以访问所有资源
---
## <EFBFBD><EFBFBD> <20>躰秤<E8BAB0><E7A7A4><EFBFBD><EFBFBD>?
## 📊 错误码汇总
| <EFBFBD>躰秤<EFBFBD>?| HTTP<EFBFBD>嗆<EFBFBD>?| 霂湔<E99C82> |
| 错误码 | HTTP状态 | 说明 |
|--------|---------|------|
| UNAUTHORIZED | 401 | <EFBFBD>芣<EFBFBD><EFBFBD>?|
| FORBIDDEN | 403 | <EFBFBD>䭾<EFBFBD><EFBFBD>?|
| NOT_FOUND | 404 | 韏<EFBFBD><EFBFBD>銝滚<EFBFBD><EFBFBD>?|
| UNAUTHORIZED | 401 | 未授权 |
| FORBIDDEN | 403 | 无权限 |
| NOT_FOUND | 404 | 资源不存在 |
| VALIDATION_ERROR | 422 | 参数验证失败 |
| ALREADY_EXISTS | 409 | 韏<EFBFBD><EFBFBD>撌脣<EFBFBD><EFBFBD>?|
| INTERNAL_ERROR | 500 | <EFBFBD>滚𦛚<EFBFBD>券<EFBFBD>霂?|
| ALREADY_EXISTS | 409 | 资源已存在 |
| INTERNAL_ERROR | 500 | 服务器错误 |
---
@@ -406,7 +406,7 @@ const response = await fetch('/api/v1/xxx/resources', {
'Content-Type': 'application/json',
},
body: JSON.stringify({
fieldName: '<EFBFBD>啗<EFBFBD>皞?,
fieldName: '新资源',
description: '描述',
}),
});
@@ -422,38 +422,38 @@ curl -X GET "http://localhost:3001/api/v1/xxx/resources?page=1&pageSize=10" \
curl -X POST "http://localhost:3001/api/v1/xxx/resources" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"fieldName":"<EFBFBD>啗<EFBFBD>皞?,"description":"<EFBFBD>讛膩"}'
-d '{"fieldName":"新资源","description":"描述"}'
```
---
## ⚠️ 注意事项
**<EFBFBD>扯<EFBFBD>隡睃<EFBFBD>嚗?*
- <EFBFBD>𡑒”<EFBFBD>亙藁敹<EFBFBD>◆<EFBFBD>舀<EFBFBD><EFBFBD><EFBFBD>△嚗屸<EFBFBD>霈小ageSize=10嚗峕<EFBFBD>憭?00
**性能优化：**
- 列表接口必须支持分页，默认pageSize=10，最大100
- 避免返回过多关联数据，按需加载
- 大量数据导出使用异步任务
**安全性：**
- 所有接口必须验证JWT Token
- 必须检查资源归属（用户只能操作自己的资源）
- <EFBFBD>𤩺<EFBFBD>摮埈挾銝滩<EFBFBD>餈𥪜<EFBFBD>嚗<EFBFBD><EFBFBD>撖<EFBFBD><EFBFBD>嚗?
- 敏感字段不要返回（如密码）
**<EFBFBD>穃<EFBFBD><EFBFBD>澆捆嚗?*
- API<EFBFBD>䀹凒雿輻鍂<EFBFBD><EFBFBD>𧋦<EFBFBD>瘀<EFBFBD>/api/v2嚗?
**向后兼容：**
- API变更使用版本号（/api/v2）
- 不要删除已有字段，只能标记为deprecated
- <EFBFBD>啣<EFBFBD>摮埈挾敹<EFBFBD>◆<EFBFBD>厰<EFBFBD>霈文<EFBFBD>?
- 新增字段必须有默认值
---
## 🔗 相关文档
**閫<EFBFBD><EFBFBD>嚗?*
- [API霈曇恣閫<EFBFBD><EFBFBD>](../../04-撘<EFBFBD><EFBFBD>𤏸<EFBFBD><EFBFBD>?02-API霈曇恣閫<E681A3><E996AB>.md)
- [API頝舐眏<EFBFBD>餉<EFBFBD>](../../04-撘<EFBFBD><EFBFBD>𤏸<EFBFBD><EFBFBD>?04-API頝舐眏<E88890>餉<EFBFBD>.md)
**规范：**
- [API设计规范](../../04-开发规范/02-API设计规范.md)
- [API路由总览](../../04-开发规范/04-API路由总览.md)
**数据库：**
- [<EFBFBD>祆芋<EFBFBD>埈㺭<EFBFBD>桀<EFBFBD>霈曇恣](./01-<EFBFBD>唳旿摨栞挽霈?md)
- [本模块数据库设计](./01-数据库设计.md)
---

36
docs/_templates/README.md vendored
View File

@@ -1,7 +1,7 @@
# 文档模板
> **鐩<EFBFBD>綍璇存槑锛?* 鏈<>洰褰曞寘鍚<E5AF98>悇绫绘枃妗ｇ殑鏍囧噯妯℃澘
> **浣跨敤鏂规硶锛?* 鍒涘缓鏂版枃妗ｆ椂锛屽<E9949B>鍒跺<E98D92>搴旀ā鏉匡紝濉<E7B49D>厖鍐呭<E98D90>
> **目录说明：** 本目录包含各类文档的标准模板
> **使用方法：** 创建新文档时，复制对应模板，填充内容
---
@@ -9,28 +9,28 @@
| 模板 | 说明 | 适用场景 |
|------|------|---------|
| **[AI瀵规帴] 蹇<>€熶笂涓嬫枃-妯℃澘.md** | 蹇<>€熶笂涓嬫枃鏂囨。妯℃澘 | 鍒涘缓鏂版ā鍧?鑳藉姏鏃?|
| **[AI对接] 快速上下文-模板.md** | 快速上下文文档模板 | 创建新模块/能力时 |
| **模块README-模板.md** | 模块README模板 | 创建新业务模块时 |
---
## 🎯 使用说明
### 1. 鍒涘缓鏂颁笟鍔℃ā鍧?
### 1. 创建新业务模块
**姝ラ<EFBFBD>锛?*
**步骤：**
1. 复制 `模块README-模板.md` 到新模块目录
2. 重命名为 `README.md`
3. 濉<EFBFBD>厖鎵€鏈?`[鍗犱綅绗<E7B685>` 鍐呭<E98D90>
3. 填充所有 `[占位符]` 内容
4. 删除不需要的章节
### 2. 创建快速上下文文档
**姝ラ<EFBFBD>锛?*
1. 澶嶅埗 `[AI瀵规帴] 蹇<>€熶笂涓嬫枃-妯℃澘.md` 鍒板<E98D92>搴旂洰褰?
**步骤：**
1. 复制 `[AI对接] 快速上下文-模板.md` 到对应目录
2. 重命名为 `[AI对接] [模块代号]快速上下文.md`
3. 濉<EFBFBD>厖鎵€鏈夊唴瀹?
4. 纭<EFBFBD>繚Token娑堣€楀湪鐩<EFBFBD>爣鑼冨洿鍐?
3. 填充所有内容
4. 确保Token消耗在目标范围内
---
@@ -40,18 +40,18 @@
**L0级别（总体）：**
- Token消耗：~800
- 闃呰<EFBFBD>鏃堕棿锛?鍒嗛挓
- 鍐呭<EFBFBD>锛氶」鐩<EFBFBD>叏璨屻€佸揩閫熻烦杞?
- 阅读时间：2分钟
- 内容：项目全貌、快速跳转
**L1绾у埆锛堝眰绾э級锛?*
**L1级别（层级）：**
- Token消耗：~1500
- 闃呰<EFBFBD>鏃堕棿锛?鍒嗛挓
- 鍐呭<EFBFBD>锛氬眰绾ф<EFBFBD>瑙堛€佹ā鍧楁竻鍗?
- 阅读时间：3分钟
- 内容：层级概览、模块清单
**L2绾у埆锛堟ā鍧楋級锛?*
**L2级别（模块）：**
- Token消耗：~2000
- 闃呰<EFBFBD>鏃堕棿锛?鍒嗛挓
- 鍐呭<EFBFBD>锛氭ā鍧楄<EFBFBD>鎯呫€佸紑鍙戞寚鍗?
- 阅读时间：5分钟
- 内容：模块详情、开发指南
---

98
docs/_templates/数据库设计-模板.md vendored
View File

@@ -1,25 +1,25 @@
# [璅∪<EFBFBD><EFBFBD>滨妍] - <20>唳旿摨栞挽霈?
# [模块名称] - 数据库设计
> **Schema嚗?* `xxx_schema`
> **銵冽㺭<EFBFBD>𧶏<EFBFBD>** X銝?
> **靘肽<EFBFBD>嚗?* platform_schema.users嚗<EFBFBD><EFBFBD><EFBFBD>㚁<EFBFBD>
> **Schema：** `xxx_schema`
> **表数量：** X个
> **依赖：** platform_schema.users（如有）
> **最后更新：** YYYY-MM-DD
---
## 📋 Schema说明
**Schema<EFBFBD>𥕦遣嚗?*
**Schema创建：**
```sql
CREATE SCHEMA IF NOT EXISTS xxx_schema;
```
**<EFBFBD>諹提<EFBFBD><EFBFBD>凒嚗?*
**职责范围：**
- 功能1相关数据
- 功能2相关数据
- ...
**靘肽<EFBFBD><EFBFBD>喟頂嚗?*
**依赖关系：**
- 依赖 `platform_schema.users`（用户信息）
- 依赖 `platform_schema.xxx`（如有）
@@ -28,30 +28,30 @@ CREATE SCHEMA IF NOT EXISTS xxx_schema;
## 📊 ER图（可选）
```
<EFBFBD>𢞖<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
<EFBFBD>? users (憭㚚<EFBFBD>) <EFBFBD>?
<EFBFBD>婙<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>砂<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
<EFBFBD>?1:N
<EFBFBD>?
<EFBFBD>𢞖<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
<EFBFBD>? 銝餉” <EFBFBD>?
<EFBFBD>婙<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>砂<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
<EFBFBD>?1:N
<EFBFBD>?
<EFBFBD>𢞖<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
<EFBFBD>? 摮鞱” <EFBFBD>?
<EFBFBD>婙<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
┌─────────────────┐
│ users (外部) │
└────────┬────────┘
│ 1:N
▼
┌─────────────────┐
│ 主表 │
└────────┬────────┘
│ 1:N
▼
┌─────────────────┐
│ 子表 │
└─────────────────┘
```
---
## <EFBFBD><EFBFBD> 銵函<E98AB5><E587BD><EFBFBD>挽霈?
## 📋 表结构设计
### 1. xxx_table_name嚗<EFBFBD>”<EFBFBD>讛膩嚗?
### 1. xxx_table_name（表描述）
**<EFBFBD>券<EFBFBD>䈑<EFBFBD>** 蝞<>閬<EFBFBD>秩<EFBFBD>舘”<E88898><E2809D>鍂<EFBFBD>?
**用途：** 简要说明表的用途
**摮埈挾霂湔<EFBFBD>嚗?*
**字段说明：**
```sql
CREATE TABLE xxx_schema.xxx_table_name (
@@ -66,7 +66,7 @@ CREATE TABLE xxx_schema.xxx_table_name (
description TEXT,
status VARCHAR(20) DEFAULT 'active',
-- <EFBFBD>園𡢿<EFBFBD>喉<EFBFBD>敹<EFBFBD>◆嚗?
-- 时间戳（必须）
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
@@ -76,9 +76,9 @@ CREATE TABLE xxx_schema.xxx_table_name (
);
```
**摮埈挾霂西圾嚗?*
**字段详解：**
| 摮埈挾<EFBFBD>?| 蝐餃<E89D90> | 蝥行<E89DA5> | 霂湔<E99C82> |
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | SERIAL | PK | 主键 |
| user_id | INTEGER | FK, NOT NULL | 用户ID |
@@ -88,8 +88,8 @@ CREATE TABLE xxx_schema.xxx_table_name (
| created_at | TIMESTAMP | NOT NULL | 创建时间 |
| updated_at | TIMESTAMP | NOT NULL | 更新时间 |
**銝𡁜𦛚閫<EFBFBD><EFBFBD>嚗?*
- 瘥譍葵<EFBFBD>冽<EFBFBD><EFBFBD><EFBFBD>憭𡁜<EFBFBD>撱旗銝芾扇敶?
**业务规则：**
- 每个用户最多创建X个记录
- status字段的有效值：active, inactive, deleted
- 软删除：不物理删除，只修改status为deleted
@@ -97,7 +97,7 @@ CREATE TABLE xxx_schema.xxx_table_name (
### 2. xxx_table_name_2（第二个表）
嚗<EFBFBD><EFBFBD>憭滢<EFBFBD><EFBFBD>Ｙ<EFBFBD>蝏𤘪<EFBFBD>嚗?
（重复上面的结构）
---
@@ -105,7 +105,7 @@ CREATE TABLE xxx_schema.xxx_table_name (
### 单列索引
```sql
-- <EFBFBD>冽<EFBFBD>ID蝝Ｗ<EFBFBD>嚗<EFBFBD><EFBFBD><EFBFBD>桀<EFBFBD>憿餃<EFBFBD>蝝Ｗ<EFBFBD>嚗?
-- 用户ID索引（外键必须加索引）
CREATE INDEX idx_xxx_user_id ON xxx_schema.xxx_table_name(user_id);
-- 状态索引（常用筛选字段）
@@ -117,7 +117,7 @@ CREATE INDEX idx_xxx_created_at ON xxx_schema.xxx_table_name(created_at DESC);
### 复合索引
```sql
-- <EFBFBD>冽<EFBFBD>+<2B>嗆<EFBFBD><E59786><EFBFBD><EFBFBD><EFBFBD>䰻霂?
-- 用户+状态组合查询
CREATE INDEX idx_xxx_user_status ON xxx_schema.xxx_table_name(user_id, status);
```
@@ -127,13 +127,13 @@ CREATE INDEX idx_xxx_user_status ON xxx_schema.xxx_table_name(user_id, status);
### 依赖关系
```sql
-- 靘肽<EFBFBD><EFBFBD>冽<EFBFBD>銵?
-- 依赖用户表
ALTER TABLE xxx_schema.xxx_table_name
ADD CONSTRAINT fk_xxx_users
FOREIGN KEY (user_id) REFERENCES platform_schema.users(id)
ON DELETE CASCADE; -- <EFBFBD>冽<EFBFBD><EFBFBD>𣳇膄<EFBFBD>嗥漣<EFBFBD>𥪜<EFBFBD><EFBFBD>?
ON DELETE CASCADE; -- 用户删除时级联删除
-- 璅∪<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
-- 模块内关联
ALTER TABLE xxx_schema.child_table
ADD CONSTRAINT fk_child_parent
FOREIGN KEY (parent_id) REFERENCES xxx_schema.parent_table(id)
@@ -141,14 +141,14 @@ ALTER TABLE xxx_schema.child_table
```
### 外键策略
- <EFBFBD>?**ON DELETE CASCADE**嚗𡁶鍂<F0A181B6>瑕<EFBFBD><E79195>斗𧒄嚗諹䌊<E8ABB9>典<EFBFBD><E585B8>斗<EFBFBD><E69697>匧<EFBFBD><E58CA7>娍㺭<E5A88D>?
- <EFBFBD>𩤃<EFBFBD> **頝沒chema憭㚚睸**嚗𡁜蘨<F0A1819C>賢<EFBFBD><E8B3A2>?platform_schema嚗䔶<E59A97><E494B6>賢<EFBFBD><E8B3A2>典<EFBFBD>隞碶<E99A9E><E7A2B6>⊥芋<E28AA5>?
- ✅ **ON DELETE CASCADE**：用户删除时，自动删除所有关联数据
- ⚠️ **跨Schema外键**：只能引用 platform_schema，不能引用其他业务模块
---
## 📈 数据迁移（可选）
### <EFBFBD>嘥<EFBFBD><EFBFBD>𡝗㺭<EFBFBD>?
### 初始化数据
```sql
-- 如果需要初始化数据
INSERT INTO xxx_schema.xxx_table_name (field_name, status) VALUES
@@ -164,40 +164,40 @@ INSERT INTO xxx_schema.xxx_table_name (field_name, status) VALUES
---
## <EFBFBD><EFBFBD> <20>唳旿<E594B3>誯<EFBFBD>隡?
## 📊 数据量预估
| 銵典<EFBFBD> | 憸<>摯霈啣<E99C88><E595A3>?| 憓鮋鵭<E9AE8B>笔漲 |
| 表名 | 预估记录数 | 增长速度 |
|------|-----------|---------|
| xxx_table_name | 10銝?撟?| 銝剔<E98A9D> |
| xxx_table_name_2 | 100銝?撟?| 擃?|
| xxx_table_name | 10万/年 | 中等 |
| xxx_table_name_2 | 100万/年 | 高 |
---
## ⚠️ 注意事项
**<EFBFBD>扯<EFBFBD>隡睃<EFBFBD>嚗?*
**性能优化：**
- 大表必须添加分页查询
- 热点字段必须添加索引
- 定期清理软删除的数据
**安全性：**
- <EFBFBD>𤩺<EFBFBD>摮埈挾<EFBFBD><EFBFBD>閬<EFBFBD><EFBFBD>撖<EFBFBD><EFBFBD><EFBFBD>?
- 敏感字段需要加密存储
- 所有外键必须有 ON DELETE 策略
- 避免N+1查询问题
**维护性：**
- 表结构变更需要写迁移脚本
- <EFBFBD>滩<EFBFBD><EFBFBD>䀹凒<EFBFBD><EFBFBD>閬<EFBFBD><EFBFBD>隞賣㺭<EFBFBD>?
- 重要变更需要备份数据
---
## 🔗 相关文档
**閫<EFBFBD><EFBFBD>嚗?*
- [<EFBFBD>唳旿摨栞挽霈∟<EFBFBD><EFBFBD><EFBFBD>(../../04-撘<><E69298>𤏸<EFBFBD><F0A48FB8>?01-<2D>唳旿摨栞挽霈∟<E99C88><E2889F>?md)
- [<EFBFBD>唳旿摨枏<EFBFBD>撅<EFBFBD>閫<EFBFBD>㦛](../../04-撘<EFBFBD><EFBFBD>𤏸<EFBFBD><EFBFBD>?03-<2D>唳旿摨枏<E691A8>撅<EFBFBD>閫<EFBFBD>㦛.md)
**规范：**
- [数据库设计规范](../../04-开发规范/01-数据库设计规范.md)
- [数据库全局视图](../../04-开发规范/03-数据库全局视图.md)
**API霈曇恣嚗?*
**API设计：**
- [本模块API设计](./02-API设计.md)
---

40
docs/_templates/模块README-模板.md vendored
View File

@@ -1,9 +1,9 @@
# [模块代号] - [模块名称]
> **妯″潡浠ｅ彿锛?* [浠ｅ彿] ([鑻辨枃鍏ㄧО])
> **模块代号：** [代号] ([英文全称])
> **开发状态：** [✅已完成 / ⏳开发中 / ⏳规划中]
> **鍟嗕笟浠峰€硷細** 猸愨瓙猸愨瓙猸?[璇勭骇]
> **鐙<EFBFBD>珛鎬э細** 猸愨瓙猸愨瓙猸?[璇勭骇]
> **商业价值：** ⭐⭐⭐⭐⭐ [评级]
> **独立性：** ⭐⭐⭐⭐⭐ [评级]
> **优先级：** [P0/P1/P2]
---
@@ -18,12 +18,12 @@
## 🎯 核心功能
### [宸插畬鎴愬姛鑳?/ 璁″垝鍔熻兘]
1. [鉁?鈴砞 **鍔熻兘1** - 绠€瑕佹弿杩?
2. [鉁?鈴砞 **鍔熻兘2** - 绠€瑕佹弿杩?
3. [鉁?鈴砞 **鍔熻兘3** - 绠€瑕佹弿杩?
### [已完成功能 / 计划功能]
1. [✅/⏳] **功能1** - 简要描述
2. [✅/⏳] **功能2** - 简要描述
3. [✅/⏳] **功能3** - 简要描述
**[鏈<EFBFBD>懆/涓嬩竴姝<E7ABB4>閲嶇偣锛?* [褰撳墠閲嶇偣]
**[本周/下一步]重点：** [当前重点]
---
@@ -33,17 +33,17 @@
[模块代号]-[模块名称]/
├── [AI对接] [代号]快速上下文.md # [状态]
├── 00-项目概述/
鈹? 鈹溾攢鈹€ 01-浜у搧闇€姹傛枃妗?PRD).md # [鐘舵€乚
鈹? 鈹斺攢鈹€ README.md
│ ├── 01-产品需求文档(PRD).md # [状态]
│ └── README.md
├── 01-设计文档/
鈹? 鈹溾攢鈹€ 01-鎶€鏈<E282AC>灦鏋勮<E98F8B>璁?md # [鐘舵€乚
鈹? 鈹溾攢鈹€ 02-鏁版嵁搴撹<E690B4>璁?md # [鐘舵€乚
鈹? 鈹溾攢鈹€ 03-API璁捐<EFBFBD>.md # [鐘舵€乚
鈹? 鈹斺攢鈹€ README.md
│ ├── 01-技术架构设计.md # [状态]
│ ├── 02-数据库设计.md # [状态]
│ ├── 03-API设计.md # [状态]
│ └── README.md
├── 02-业务规则/
鈹溾攢鈹€ 03-寮€鍙戣<E98D99>鍒?
├── 03-开发计划/
├── 04-测试文档/
鈹斺攢鈹€ README.md # 鉁?褰撳墠鏂囨。
└── README.md # ✅ 当前文档
```
---
@@ -57,13 +57,13 @@
## 🎯 商业模式
**鐩<EFBFBD>爣瀹㈡埛锛?* [鐩<>爣瀹㈡埛缇<E59F9B>
**鍞<EFBFBD>崠鏂瑰紡锛?* [鐙<>珛浜у搧 / 缁勫悎鍞<E6828E>崠 / 骞冲彴鍔熻兘]
**瀹氫环绛栫暐锛?* [瀹氫环鏂瑰紡]
**目标客户：** [目标客户群]
**售卖方式：** [独立产品 / 组合售卖 / 平台功能]
**定价策略：** [定价方式]
---
## 鈿狅笍 [鎶€鏈<E282AC>毦鐐?/ 鏍稿績鐗硅壊]
## ⚠️ [技术难点 / 核心特色]
[如果有特别的技术难点或核心特色，在这里说明]