feat(aia): Complete AIA V2.0 with universal streaming capabilities

Major Changes:
- Add StreamingService with OpenAI Compatible format
- Upgrade Chat component V2 with Ant Design X integration
- Implement AIA module with 12 intelligent agents
- Update API routes to unified /api/v1 prefix
- Update system documentation

Backend (~1300 lines):
- common/streaming: OpenAI Compatible adapter
- modules/aia: 12 agents, conversation service, streaming integration
- Update route versions (RVW, PKB to v1)

Frontend (~3500 lines):
- modules/aia: AgentHub + ChatWorkspace (100% prototype restoration)
- shared/Chat: AIStreamChat, ThinkingBlock, useAIStream Hook
- Update API endpoints to v1

Documentation:
- AIA module status guide
- Universal capabilities catalog
- System overview updates
- All module documentation sync

Tested: Stream response verified, authentication working
Status: AIA V2.0 core completed (85%)
This commit is contained in:
2026-01-14 19:15:01 +08:00
parent 3d35e9c58b
commit 1b53ab9d52
386 changed files with 52096 additions and 65238 deletions

View File

@@ -1,8 +1,8 @@
# [璅<E79285><E288AA>滨妍] - API霈曇恣
> **基础路径:** `/api/v1/模块名`
> **端点数量:** X
> **认证要求:** JWT Token
> **<EFBFBD><EFBFBD>頝臬<EFBFBD>嚗?* `/api/v1/<EFBFBD><EFBFBD>
> **蝡舐<EFBFBD><EFBFBD><EFBFBD>嚗?* X銝?
> **霈方<EFBFBD><EFBFBD><EFBFBD>嚗?* JWT Token
> **<2A><><EFBFBD>擧凒<E693A7><EFBFBD>** YYYY-MM-DD
---
@@ -11,11 +11,11 @@
| 蝡舐<E89DA1> | <20><EFBFBD> | 霂湔<E99C82> | 霈方<E99C88> |
|------|------|------|------|
| `/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 | 删除资源 | |
| `/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>?|
---
@@ -23,31 +23,31 @@
### 1. <20><EFBFBD><EFBFBD><E99F8F><EFBFBD>𡑒”
**端点:** `GET /api/v1/xxx/resources`
**蝡舐<EFBFBD>嚗?* `GET /api/v1/xxx/resources`
**用途:** 获取当前用户的资源列表(分页)
**<EFBFBD><EFBFBD><EFBFBD>** <20><EFBFBD>敶枏<E695B6><E69E8F><EFBFBD><E586BD><EFBFBD><EFBFBD>皞𣂼<E79A9E>銵剁<E98AB5><E58981><EFBFBD>△嚗?
**请求参数:**
**霂瑟<EFBFBD><EFBFBD><EFBFBD>㺭嚗?*
**Query参数:**
**Query<EFBFBD><EFBFBD>㺭嚗?*
```typescript
{
page?: number; // 页码默认1
pageSize?: number; // 每页数量默认10最大100
status?: string; // 筛选:状态(active/inactive
keyword?: string; // 搜索关键词
sortBy?: string; // 排序字段createdAt/updatedAt
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嚗?
sortOrder?: 'asc' | 'desc'; // <20><EFBFBD><E98DA6><EFBFBD>嚗屸<E59A97>霈千esc
}
```
**请求示例:**
**霂瑟<EFBFBD>蝷箔<EFBFBD>嚗?*
```bash
GET /api/v1/xxx/resources?page=1&pageSize=10&status=active
Authorization: Bearer <token>
```
**成功响应:** `200 OK`
**<EFBFBD>𣂼<EFBFBD><EFBFBD><EFBFBD>嚗?* `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": "<22><><EFBFBD>躰秤",
"details": [
{ "field": "pageSize", "message": "最大不能超过100" }
{ "field": "pageSize", "message": "<EFBFBD><EFBFBD>憭找<EFBFBD><EFBFBD><EFBFBD>餈?00" }
]
}
}
@@ -102,20 +102,20 @@ Authorization: Bearer <token>
### 2. <20><EFBFBD><EFBFBD><E99F8F>霂行<E99C82>
**端点:** `GET /api/v1/xxx/resources/:id`
**蝡舐<EFBFBD>嚗?* `GET /api/v1/xxx/resources/:id`
**用途:** 获取指定资源的详细信息
**<EFBFBD><EFBFBD><EFBFBD>** <20><EFBFBD><E79195><EFBFBD><EFBFBD><EFBFBD><E99F8F><EFBFBD><EFBFBD>祕蝏<E7A595><EFBFBD>?
**路径参数:**
**頝臬<EFBFBD><EFBFBD><EFBFBD>㺭嚗?*
- `id` (敹<>): 韏<><E99F8F>ID
**请求示例:**
**霂瑟<EFBFBD>蝷箔<EFBFBD>嚗?*
```bash
GET /api/v1/xxx/resources/123
Authorization: Bearer <token>
```
**成功响应:** `200 OK`
**<EFBFBD>𣂼<EFBFBD><EFBFBD><EFBFBD>嚗?* `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": "用户名"
"name": "<EFBFBD><EFBFBD><EFBFBD>?
}
},
"message": "<EFBFBD><EFBFBD><EFBFBD>𣂼<EFBFBD>"
}
```
**错误响应:**
**<EFBFBD>躰秤<EFBFBD><EFBFBD>嚗?*
```json
// 404 Not Found
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "资源不存在"
"message": "<EFBFBD><EFBFBD>銝滚<EFBFBD><EFBFBD>?
}
}
@@ -153,7 +153,7 @@ Authorization: Bearer <token>
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "无权访问此资源"
"message": "<EFBFBD><EFBFBD><EFBFBD>?
}
}
```
@@ -162,44 +162,44 @@ Authorization: Bearer <token>
### 3. <20>𥕦遣韏<E981A3><E99F8F>
**端点:** `POST /api/v1/xxx/resources`
**蝡舐<EFBFBD>嚗?* `POST /api/v1/xxx/resources`
**用途:** 创建新资源
**<EFBFBD><EFBFBD><EFBFBD>** <20>𥕦遣<F0A595A6><EFBFBD>皞?
**霂瑟<E99C82>雿橒<E99BBF>**
```json
{
"fieldName": "资源名称", // 必填长度2-200
"description": "描述", // 可选最大5000
"fieldName": "<EFBFBD><EFBFBD><EFBFBD>滨妍", // <EFBFBD>嚗屸鵭摨?-200
"description": "<EFBFBD>讛膩", // <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>憭?000摮?
"status": "active" // <20><EFBFBD><EFBFBD>暺䁅恕active
}
```
**验证规则:**
- `fieldName`: 必填2-200字符不能包含特殊字符
- `description`: 可选最大5000字符
**撉諹<EFBFBD><EFBFBD><EFBFBD>嚗?*
- `fieldName`: <EFBFBD>嚗?-200摮㛖泵嚗䔶<E59A97><E494B6><EFBFBD><E8B3A2>怎鸌畾𠰴<E795BE>蝚?
- `description`: <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>憭?000摮㛖泵
- `status`: <20><EFBFBD><EFBFBD><E39A81><EFBFBD><E39787><EFBFBD>active, inactive
**请求示例:**
**霂瑟<EFBFBD>蝷箔<EFBFBD>嚗?*
```bash
POST /api/v1/xxx/resources
Authorization: Bearer <token>
Content-Type: application/json
{
"fieldName": "新资源",
"fieldName": "<EFBFBD><EFBFBD>皞?,
"description": "餈蹱糓銝<EFBFBD>銝芣鰵韏<EFBFBD><EFBFBD>"
}
```
**成功响应:** `201 Created`
**<EFBFBD>𣂼<EFBFBD><EFBFBD><EFBFBD>嚗?* `201 Created`
```json
{
"success": true,
"data": {
"id": 124,
"userId": 456,
"fieldName": "新资源",
"fieldName": "<EFBFBD><EFBFBD>皞?,
"description": "<EFBFBD><EFBFBD><EFBFBD>",
"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": "<22><>㺭撉諹<E69289>憭梯揖",
"details": [
{ "field": "fieldName", "message": "摮埈挾<E59F88>滨妍銝滩<E98A9D>銝箇征" },
{ "field": "fieldName", "message": "字段名称长度必须在2-200之间" }
{ "field": "fieldName", "message": "摮埈挾<EFBFBD>滨妍<EFBFBD>踹漲敹<EFBFBD><EFBFBD>?-200銋钅𡢿" }
]
}
}
@@ -238,11 +238,11 @@ Content-Type: application/json
### 4. <20>湔鰵韏<E9B0B5><E99F8F>
**端点:** `PUT /api/v1/xxx/resources/:id`
**蝡舐<EFBFBD>嚗?* `PUT /api/v1/xxx/resources/:id`
**<EFBFBD><EFBFBD><EFBFBD>** <20>湔鰵<E6B994><E9B0B5><EFBFBD><EFBFBD><E99F8F><EFBFBD><E59A97><EFBFBD>湔凒<E6B994><EFBFBD>
**路径参数:**
**頝臬<EFBFBD><EFBFBD><EFBFBD>㺭嚗?*
- `id` (敹<>): 韏<><E99F8F>ID
**霂瑟<E99C82>雿橒<E99BBF>**
@@ -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
}
```
**成功响应:** `200 OK`
**<EFBFBD>𣂼<EFBFBD><EFBFBD><EFBFBD>嚗?* `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": "资源不存在"
"message": "<EFBFBD><EFBFBD>銝滚<EFBFBD><EFBFBD>?
}
}
@@ -296,7 +296,7 @@ Content-Type: application/json
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "无权修改此资源"
"message": "<EFBFBD><EFBFBD>㺿<EFBFBD>?
}
}
```
@@ -305,20 +305,20 @@ Content-Type: application/json
### 5. <20>𣳇膄韏<E88684><E99F8F>
**端点:** `DELETE /api/v1/xxx/resources/:id`
**蝡舐<EFBFBD>嚗?* `DELETE /api/v1/xxx/resources/:id`
**用途:** 删除指定资源(软删除)
**<EFBFBD><EFBFBD><EFBFBD>** <20>𣳇膄<F0A3B387><E88684><EFBFBD><EFBFBD><E99F8F><EFBFBD><EFBFBD>𣳇膄嚗?
**路径参数:**
**頝臬<EFBFBD><EFBFBD><EFBFBD>㺭嚗?*
- `id` (敹<>): 韏<><E99F8F>ID
**请求示例:**
**霂瑟<EFBFBD>蝷箔<EFBFBD>嚗?*
```bash
DELETE /api/v1/xxx/resources/123
Authorization: Bearer <token>
```
**成功响应:** `200 OK`
**<EFBFBD>𣂼<EFBFBD><EFBFBD><EFBFBD>嚗?* `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": "资源不存在"
"message": "<EFBFBD><EFBFBD>銝滚<EFBFBD><EFBFBD>?
}
}
@@ -343,7 +343,7 @@ Authorization: Bearer <token>
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "无权删除此资源"
"message": "<EFBFBD><EFBFBD><EFBFBD>𣳇<EFBFBD>?
}
}
@@ -352,37 +352,37 @@ Authorization: Bearer <token>
"success": false,
"error": {
"code": "CANNOT_DELETE",
"message": "该资源有关联数据,无法删除"
"message": "<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
}
}
```
---
## 🔐 认证与权限
## <EFBFBD><EFBFBD> 霈方<E99C88>銝擧<E98A9D><E693A7>?
### 霈方<E99C88><E696B9><EFBFBD>
所有API都需要JWT Token认证:
<EFBFBD><EFBFBD><EFBFBD>𡅅PI<EFBFBD><EFBFBD><EFBFBD>WT Token霈方<EFBFBD>嚗?
```
Authorization: Bearer <token>
```
### 权限检查
- 用户只能访问自己的资源
- ADMIN角色可以访问所有资源
### <EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
- <EFBFBD><EFBFBD><EFBFBD><EFBFBD>霈輸䔮<EFBFBD>芸楛<EFBFBD><EFBFBD><EFBFBD>皞?
- ADMIN閫坿𠧧<EFBFBD>臭誑霈輸䔮<EFBFBD><EFBFBD><EFBFBD><EFBFBD>皞?
---
## 📊 错误码汇总
## <EFBFBD><EFBFBD> <20>躰秤<E8BAB0><E7A7A4><EFBFBD><EFBFBD>?
| 错误码 | HTTP状态 | 说明 |
| <EFBFBD>躰秤<EFBFBD>?| HTTP<EFBFBD><EFBFBD>?| 霂湔<E99C82> |
|--------|---------|------|
| UNAUTHORIZED | 401 | 未授权 |
| FORBIDDEN | 403 | 无权限 |
| NOT_FOUND | 404 | 资源不存在 |
| UNAUTHORIZED | 401 | <EFBFBD><EFBFBD><EFBFBD>?|
| FORBIDDEN | 403 | <EFBFBD><EFBFBD><EFBFBD>?|
| NOT_FOUND | 404 | <EFBFBD><EFBFBD>銝滚<EFBFBD><EFBFBD>?|
| VALIDATION_ERROR | 422 | <20><>㺭撉諹<E69289>憭梯揖 |
| ALREADY_EXISTS | 409 | 资源已存在 |
| INTERNAL_ERROR | 500 | 服务器错误 |
| ALREADY_EXISTS | 409 | <EFBFBD><EFBFBD>撌脣<EFBFBD><EFBFBD>?|
| INTERNAL_ERROR | 500 | <EFBFBD>滚𦛚<EFBFBD><EFBFBD>霂?|
---
@@ -406,7 +406,7 @@ const response = await fetch('/api/v1/xxx/resources', {
'Content-Type': 'application/json',
},
body: JSON.stringify({
fieldName: '新资源',
fieldName: '<EFBFBD><EFBFBD>皞?,
description: '<EFBFBD>',
}),
});
@@ -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":"新资源","description":"描述"}'
-d '{"fieldName":"<EFBFBD><EFBFBD>皞?,"description":"<EFBFBD>讛膩"}'
```
---
## <20>𩤃<EFBFBD> 瘜冽<E7989C>鈭钅★
**性能优化:**
- 列表接口必须支持分页默认pageSize=10最大100
**<EFBFBD><EFBFBD>隡睃<EFBFBD>嚗?*
- <EFBFBD>𡑒”<EFBFBD>亙藁敹<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>△嚗屸<EFBFBD>霈小ageSize=10嚗峕<EFBFBD>憭?00
- <20><EFBFBD>餈𥪜<E9A488><EFBFBD><E9A488><EFBFBD><EFBFBD><E594BE>唳旿嚗峕<E59A97><E5B395><EFBFBD><EFBFBD>㰘蝸
- 憭折<E686AD><E68A98>唳旿撖澆枂雿輻鍂撘<E98D82>郊隞餃𦛚
**摰匧<E691B0><E58CA7><EFBFBD>**
- <20><><EFBFBD>㗇𦻖<E39787><F0A6BB96><EFBFBD>憿駁<E686BF><EFBFBD>WT Token
-<>◆璉<E29786><E79289><EFBFBD>皞𣂼<E79A9E>撅痹<E69285><E797B9><EFBFBD><E586BD><EFBFBD><E88ABE><EFBFBD><E6BBA2>芸楛<E88AB8><E6A59B><EFBFBD>皞琜<E79A9E>
- 敏感字段不要返回(如密码)
- <EFBFBD>𤩺<EFBFBD>摮埈挾銝滩<EFBFBD>餈𥪜<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>嚗?
**向后兼容:**
- API变更使用版本号(/api/v2
**<EFBFBD><EFBFBD><EFBFBD>澆捆嚗?*
- API<EFBFBD>䀹凒雿輻鍂<EFBFBD><EFBFBD>𧋦<EFBFBD><EFBFBD>/api/v2嚗?
- 銝滩<E98A9D><E6BBA9>𣳇膄撌脫<E6928C>摮埈挾嚗<E68CBE><EFBFBD><EFBFBD>霈唬蛹deprecated
- 新增字段必须有默认值
- <EFBFBD><EFBFBD>摮埈挾敹<EFBFBD><EFBFBD><EFBFBD>霈文<EFBFBD>?
---
## <20><> <20><EFBFBD><E8A9A8><EFBFBD>
**规范:**
- [API设计规范](../../04-开发规范/02-API设计规范.md)
- [API路由总览](../../04-开发规范/04-API路由总览.md)
**<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)
**<EFBFBD>唳旿摨橒<EFBFBD>**
- [本模块数据库设计](./01-数据库设计.md)
- [<EFBFBD>祆芋<EFBFBD>埈㺭<EFBFBD><EFBFBD>霈曇恣](./01-<EFBFBD>唳旿摨栞挽霈?md)
---

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` 鍒版柊妯″潡鐩<E6BDA1>
2. 閲嶅懡鍚嶄负 `README.md`
3. 填充所有 `[占位符]` 内容
3. <EFBFBD>厖鎵€鏈?`[鍗犱綅绗<E7B685>` 鍐呭<E98D90>
4. 鍒犻櫎涓嶉渶瑕佺殑绔犺妭
### 2. 鍒涘缓蹇<E7BC93>€熶笂涓嬫枃鏂囨。
**步骤:**
1. 复制 `[AI对接] 快速上下文-模板.md` 到对应目录
**姝ラ<EFBFBD>锛?*
1. 澶嶅埗 `[AI瀵规帴] 蹇<>€熶笂涓嬫枃-妯℃澘.md` 鍒板<E98D92>搴旂洰褰?
2. 閲嶅懡鍚嶄负 `[AI瀵规帴] [妯″潡浠e彿]蹇<>€熶笂涓嬫枃.md`
3. 填充所有内容
4. 确保Token消耗在目标范围内
3. <EFBFBD>厖鎵€鏈夊唴瀹?
4. <EFBFBD>Token娑堣€楀湪鐩<EFBFBD>爣鑼冨洿鍐?
---
@@ -40,18 +40,18 @@
**L0绾у埆锛堟€讳綋锛夛細**
- Token娑堣€楋細~800
- 阅读时间2分钟
- 内容:项目全貌、快速跳转
- 闃呰<EFBFBD>鏃堕棿锛?鍒嗛挓
- 鍐呭<EFBFBD>锛氶」鐩<EFBFBD>叏璨屻€佸揩閫熻烦杞?
**L1级别(层级):**
**L1绾у埆锛堝眰绾э級锛?*
- Token娑堣€楋細~1500
- 阅读时间3分钟
- 内容:层级概览、模块清单
- 闃呰<EFBFBD>鏃堕棿锛?鍒嗛挓
- 鍐呭<EFBFBD>锛氬眰绾ф<EFBFBD>瑙堛€佹ā鍧楁竻鍗?
**L2级别(模块):**
**L2绾у埆锛堟ā鍧楋級锛?*
- Token娑堣€楋細~2000
- 阅读时间5分钟
- 内容:模块详情、开发指南
- 闃呰<EFBFBD>鏃堕棿锛?鍒嗛挓
- 鍐呭<EFBFBD>锛氭ā鍧楄<EFBFBD>鎯呫€佸紑鍙戞寚鍗?
---

View File

@@ -1,25 +1,25 @@
# [模块名称] - 数据库设计
# [<EFBFBD><EFBFBD>滨妍] - <20>唳旿摨栞挽霈?
> **Schema** `xxx_schema`
> **表数量:** X
> **依赖:** platform_schema.users(如有)
> **Schema嚗?* `xxx_schema`
> **銵冽㺭<EFBFBD>𧶏<EFBFBD>** X銝?
> **靘肽<EFBFBD>嚗?* platform_schema.users<EFBFBD><EFBFBD><EFBFBD><EFBFBD>
> **<2A><><EFBFBD>擧凒<E693A7><EFBFBD>** YYYY-MM-DD
---
## <20><> Schema霂湔<E99C82>
**Schema创建:**
**Schema<EFBFBD>𥕦遣嚗?*
```sql
CREATE SCHEMA IF NOT EXISTS xxx_schema;
```
**职责范围:**
**<EFBFBD>諹提<EFBFBD><EFBFBD>凒嚗?*
- <20><EFBFBD>1<EFBFBD><EFBFBD><E8A9A8>唳旿
- <20><EFBFBD>2<EFBFBD><EFBFBD><E8A9A8>唳旿
- ...
**依赖关系:**
**靘肽<EFBFBD><EFBFBD>喟頂嚗?*
- 靘肽<E99D98> `platform_schema.users`<EFBFBD><EFBFBD>瑚縑<EFBFBD><EFBFBD>
- 靘肽<E99D98> `platform_schema.xxx`<EFBFBD><EFBFBD><EFBFBD><EFBFBD>
@@ -28,30 +28,30 @@ CREATE SCHEMA IF NOT EXISTS xxx_schema;
## <20><> ER<45><EFBFBD><E6A998><EFBFBD><EFBFBD>
```
┌─────────────────┐
users (外部)
└────────┬────────┘
1:N
┌─────────────────┐
│ 主表
└────────┬────────┘
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>? 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>?
```
---
## 📋 表结构设计
## <EFBFBD><EFBFBD> 銵函<E98AB5><E587BD><EFBFBD>挽霈?
### 1. xxx_table_name(表描述)
### 1. xxx_table_name<EFBFBD><EFBFBD>讛膩嚗?
**用途:** 简要说明表的用途
**<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 | <20><EFBFBD>ID |
@@ -88,8 +88,8 @@ CREATE TABLE xxx_schema.xxx_table_name (
| created_at | TIMESTAMP | NOT NULL | <20>𥕦遣<F0A595A6>園𡢿 |
| updated_at | TIMESTAMP | NOT NULL | <20>湔鰵<E6B994>園𡢿 |
**业务规则:**
- 每个用户最多创建X个记录
**銝𡁜𦛚閫<EFBFBD><EFBFBD>嚗?*
- 瘥譍葵<EFBFBD><EFBFBD><EFBFBD><EFBFBD>憭𡁜<EFBFBD>撱旗銝芾扇敶?
- status摮埈挾<E59F88><E68CBE><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>active, inactive, deleted
- 頧臬<E9A0A7><E887AC><EFBFBD>銝滨<E98A9D><E6BBA8><EFBFBD><EFBFBD><EFBFBD><EFBFBD><E6ADB9>芯耨<E88AAF>零tatus銝榛eleted
@@ -97,7 +97,7 @@ CREATE TABLE xxx_schema.xxx_table_name (
### 2. xxx_table_name_2嚗<32>洵鈭䔶葵銵剁<E98AB5>
(重复上面的结构)
<EFBFBD><EFBFBD>憭滢<EFBFBD><EFBFBD><EFBFBD>蝏𤘪<EFBFBD>嚗?
---
@@ -105,7 +105,7 @@ CREATE TABLE xxx_schema.xxx_table_name (
### <20><EFBFBD><E89D9D>
```sql
-- 用户ID索引外键必须加索引
-- <EFBFBD><EFBFBD>ID蝝<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>憿餃<EFBFBD><EFBFBD>嚗?
CREATE INDEX idx_xxx_user_id ON xxx_schema.xxx_table_name(user_id);
-- <20><EFBFBD><E59786>揣撘𤏪<E69298>撣貊鍂蝑偦<E89D91><EFBFBD>畾蛛<E795BE>
@@ -117,7 +117,7 @@ CREATE INDEX idx_xxx_created_at ON xxx_schema.xxx_table_name(created_at DESC);
### 憭滚<E686AD><E89D9D>
```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);
### 靘肽<E99D98><E882BD>喟頂
```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; -- 用户删除时级联删除
ON DELETE CASCADE; -- <EFBFBD><EFBFBD><EFBFBD>𣳇膄<EFBFBD>嗥漣<EFBFBD>𥪜<EFBFBD><EFBFBD>?
-- 模块内关联
-- <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
```
### 憭㚚睸蝑𣇉裦
- **ON DELETE CASCADE**:用户删除时,自动删除所有关联数据
- ⚠️ **跨Schema外键**:只能引用 platform_schema不能引用其他业务模块
- <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>?
---
## <20><> <20>唳旿餈<E697BF>宏嚗<E5AE8F><EFBFBD><EFBFBD>
### 初始化数据
### <EFBFBD><EFBFBD><EFBFBD>𡝗㺭<EFBFBD>?
```sql
-- 憒<><E68692><EFBFBD><EFBFBD><EFBFBD><E996AC>憪见<E686AA><E8A781>唳旿
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万/年 | 中等 |
| xxx_table_name_2 | 100万/年 | 高 |
| xxx_table_name | 10銝?撟?| 銝剔<E98A9D> |
| xxx_table_name_2 | 100銝?撟?| 擃?|
---
## <20>𩤃<EFBFBD> 瘜冽<E7989C>鈭钅★
**性能优化:**
**<EFBFBD><EFBFBD>隡睃<EFBFBD>嚗?*
- 憭扯”敹<E2809D>◆瘛餃<E7989B><E9A483><EFBFBD><EFBFBD>亥砭
- <20><EFBFBD>摮埈挾敹<E68CBE>◆瘛餃<E7989B><E89D9D>
- 摰𡁏<E691B0><EFBFBD><E79A9C>頧臬<E9A0A7><E887AC><EFBFBD><E696A4>唳旿
**摰匧<E691B0><E58CA7><EFBFBD>**
- 敏感字段需要加密存储
- <EFBFBD>𤩺<EFBFBD>摮埈挾<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>?
- <20><><EFBFBD><EFBFBD><E58CA7><EFBFBD>憿餅<E686BF> ON DELETE 蝑𣇉裦
- <20><EFBFBD>N+1<>亥砭<E4BAA5><EFBFBD>
**蝏湔擪<E6B994><EFBFBD>**
- 銵函<E98AB5><E587BD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><E996AC><EFBFBD><EFBFBD>𡁏𧋦
- 重要变更需要备份数据
- <EFBFBD><EFBFBD><EFBFBD>䀹凒<EFBFBD><EFBFBD><EFBFBD><EFBFBD>隞賣㺭<EFBFBD>?
---
## <20><> <20><EFBFBD><E8A9A8><EFBFBD>
**规范:**
- [数据库设计规范](../../04-开发规范/01-数据库设计规范.md)
- [数据库全局视图](../../04-开发规范/03-数据库全局视图.md)
**<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)
**API设计:**
**API霈曇恣嚗?*
- [<EFBFBD>祆芋<EFBFBD>嫎PI霈曇恣](./02-API霈曇恣.md)
---

View File

@@ -1,9 +1,9 @@
# [妯″潡浠e彿] - [妯″潡鍚嶇О]
> **模块代号:** [代号] ([英文全称])
> **妯″潡浠e彿锛?* [浠e彿] ([鑻辨枃鍏ㄧО])
> **寮€鍙戠姸鎬侊細** [鉁呭凡瀹屾垚 / 鈴冲紑鍙戜腑 / 鈴宠<E988B4>鍒掍腑]
> **商业价值:** ⭐⭐⭐⭐⭐ [评级]
> **独立性:** ⭐⭐⭐⭐⭐ [评级]
> **鍟嗕笟浠峰€硷細** 猸愨瓙猸愨瓙猸?[璇勭骇]
> **<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 @@
[妯″潡浠e彿]-[妯″潡鍚嶇О]/
鈹溾攢鈹€ [AI瀵规帴] [浠e彿]蹇<>€熶笂涓嬫枃.md # [鐘舵€乚
鈹溾攢鈹€ 00-椤圭洰姒傝堪/
│ ├── 01-产品需求文档(PRD).md # [状态]
│ └── README.md
鈹? 鈹溾攢鈹€ 01-浜у搧闇€姹傛枃妗?PRD).md # [鐘舵€乚
鈹? 鈹斺攢鈹€ README.md
鈹溾攢鈹€ 01-璁捐<E79281>鏂囨。/
│ ├── 01-技术架构设计.md # [状态]
│ ├── 02-数据库设计.md # [状态]
│ ├── 03-API设计.md # [状态]
│ └── README.md
鈹? 鈹溾攢鈹€ 01-鎶€鏈<E282AC>灦鏋勮<E98F8B>璁?md # [鐘舵€乚
鈹? 鈹溾攢鈹€ 02-鏁版嵁搴撹<E690B4>璁?md # [鐘舵€乚
鈹? 鈹溾攢鈹€ 03-API璁捐<EFBFBD>.md # [鐘舵€乚
鈹? 鈹斺攢鈹€ README.md
鈹溾攢鈹€ 02-涓氬姟瑙勫垯/
├── 03-开发计划/
鈹溾攢鈹€ 03-寮€鍙戣<E98D99>鍒?
鈹溾攢鈹€ 04-娴嬭瘯鏂囨。/
└── README.md # ✅ 当前文档
鈹斺攢鈹€ README.md # 鉁?褰撳墠鏂囨。
```
---
@@ -57,13 +57,13 @@
## 馃幆 鍟嗕笟妯″紡
**目标客户:** [目标客户群]
**售卖方式:** [独立产品 / 组合售卖 / 平台功能]
**定价策略:** [定价方式]
**<EFBFBD>爣瀹㈡埛锛?* [鐩<>爣瀹㈡埛缇<E59F9B>
**<EFBFBD>崠鏂瑰紡锛?* [鐙<>珛浜у搧 / 缁勫悎鍞<E6828E>崠 / 骞冲彴鍔熻兘]
**瀹氫环绛栫暐锛?* [瀹氫环鏂瑰紡]
---
## ⚠️ [技术难点 / 核心特色]
## 鈿狅笍 [鎶€鏈<E282AC>毦鐐?/ 鏍稿績鐗硅壊]
[濡傛灉鏈夌壒鍒<E5A392>殑鎶€鏈<E282AC>毦鐐规垨鏍稿績鐗硅壊锛屽湪杩欓噷璇存槑]