refactor: 重构项目结构并优化代码
- 删除无用的文件和错误日志 - 创建统一的 imports 模块集中管理依赖 - 重构组件使用新的 imports 方式 - 修复文档路径大小写问题 - 优化类型定义和接口导出 - 更新依赖版本 - 改进错误处理和API配置 - 统一组件导出方式
This commit is contained in:
@@ -28,6 +28,6 @@
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
- [规则中心](../RULES/_index.md)
|
||||
- [任务中心](../TASKS/_index.md)
|
||||
- [服务地图](../SERVICES/_index.md)
|
||||
- [规则中心](../rules/_index.md)
|
||||
- [任务中心](../tasks/_index.md)
|
||||
- [服务地图](../services/_index.md)
|
||||
|
||||
@@ -27,22 +27,22 @@
|
||||
|
||||
| 业务域 | 文档 | 包含闭环 |
|
||||
|--------|------|---------|
|
||||
| 🛍️ 商品域 | [01_Product.md](./Business_ClosedLoops/01_Product.md) | 数据采集、商品刊登、素材管理、商品主数据、SKU变体、多平台商品管理 |
|
||||
| 📦 订单域 | [02_Order.md](./Business_ClosedLoops/02_Order.md) | 订单履约、售后逆向、订单集中管理、订单拆分合并、异常订单处理、一站式订单履约 |
|
||||
| 📢 营销域 | [03_Marketing.md](./Business_ClosedLoops/03_Marketing.md) | 广告计划与营销、A/B测试与策略优化、全渠道营销整合 |
|
||||
| 💰 财务域 | [04_Finance.md](./Business_ClosedLoops/04_Finance.md) | 资金对账、回款与财务、利润核算、支付与结算 |
|
||||
| 📦 库存域 | [05_Inventory.md](./Business_ClosedLoops/05_Inventory.md) | 库存与仓储管理、海外仓/本土仓 |
|
||||
| 🚚 供应链域 | [06_SupplyChain.md](./Business_ClosedLoops/06_SupplyChain.md) | 供应链与供应商管理、物流策略与渠道选择 |
|
||||
| 🏢 TOB贸易域 | [07_TOBTrade.md](./Business_ClosedLoops/07_TOBTrade.md) | TOB贸易管理 |
|
||||
| 👥 商户域 | [08_Merchant.md](./Business_ClosedLoops/08_Merchant.md) | 多商户入驻、商户店铺、多商户订单、多商户库存、多商户结算、商户权限、商户数据 |
|
||||
| ⚙️ 平台基础域 | [09_Platform.md](./Business_ClosedLoops/09_Platform.md) | 治理与审批、功能模块化、功能开通、用户/客户资产、客户服务、货币管理、运营代理（Agent）、全渠道客户沟通、快速建站与品牌化运营 |
|
||||
| 🤖 AI与自动化域 | [10_AI_Automation.md](./Business_ClosedLoops/10_AI_Automation.md) | AI驱动智能决策、自动选品+上架、AI店铺托管、AI动态定价、跨平台套利、策略市场 |
|
||||
| 🛡️ 治理与合规域 | [11_Governance.md](./Business_ClosedLoops/11_Governance.md) | 合规与证书、合规与风控、异常处理、恶意买家黑名单、高退货率SKU |
|
||||
| 📈 增长与商业化域 | [12_Growth.md](./Business_ClosedLoops/12_Growth.md) | 商业化与增长、增长飞轮、多商户收益排行榜、首页商业化 |
|
||||
| 🔧 技术基础设施域 | [13_Technical.md](./Business_ClosedLoops/13_Technical.md) | 技术基础设施、报表与分析、API文档、系统监控、技术债务、用户教育 |
|
||||
| 🌍 跨境电商域 | [14_CrossBorder.md](./Business_ClosedLoops/14_CrossBorder.md) | 跨境电商、多语言业务 |
|
||||
| 🔒 安全与风控域 | [15_Security.md](./Business_ClosedLoops/15_Security.md) | 安全与风控、用户管理与权限、多租户隔离、多租户层级、账号/店铺健康、店铺隔离 |
|
||||
| 📋 其他独立闭环 | [16_Others.md](./Business_ClosedLoops/16_Others.md) | 定价与利润决策、核心服务优先级、多店铺管理、商家选择发货、客户/商家押金 |
|
||||
| 🛍️ 商品域 | [01_Product.md](../loops/01_Product.md) | 数据采集、商品刊登、素材管理、商品主数据、SKU变体、多平台商品管理 |
|
||||
| 📦 订单域 | [02_Order.md](../loops/02_Order.md) | 订单履约、售后逆向、订单集中管理、订单拆分合并、异常订单处理、一站式订单履约 |
|
||||
| 📢 营销域 | [03_Marketing.md](../loops/03_Marketing.md) | 广告计划与营销、A/B测试与策略优化、全渠道营销整合 |
|
||||
| 💰 财务域 | [04_Finance.md](../loops/04_Finance.md) | 资金对账、回款与财务、利润核算、支付与结算 |
|
||||
| 📦 库存域 | [05_Inventory.md](../loops/05_Inventory.md) | 库存与仓储管理、海外仓/本土仓 |
|
||||
| 🚚 供应链域 | [06_SupplyChain.md](../loops/06_SupplyChain.md) | 供应链与供应商管理、物流策略与渠道选择 |
|
||||
| 🏢 TOB贸易域 | [07_TOBTrade.md](../loops/07_TOBTrade.md) | TOB贸易管理 |
|
||||
| 👥 商户域 | [08_Merchant.md](../loops/08_Merchant.md) | 多商户入驻、商户店铺、多商户订单、多商户库存、多商户结算、商户权限、商户数据 |
|
||||
| ⚙️ 平台基础域 | [09_Platform.md](../loops/09_Platform.md) | 治理与审批、功能模块化、功能开通、用户/客户资产、客户服务、货币管理、运营代理（Agent）、全渠道客户沟通、快速建站与品牌化运营 |
|
||||
| 🤖 AI与自动化域 | [10_AI_Automation.md](../loops/10_AI_Automation.md) | AI驱动智能决策、自动选品+上架、AI店铺托管、AI动态定价、跨平台套利、策略市场 |
|
||||
| 🛡️ 治理与合规域 | [11_Governance.md](../loops/11_Governance.md) | 合规与证书、合规与风控、异常处理、恶意买家黑名单、高退货率SKU |
|
||||
| 📈 增长与商业化域 | [12_Growth.md](../loops/12_Growth.md) | 商业化与增长、增长飞轮、多商户收益排行榜、首页商业化 |
|
||||
| 🔧 技术基础设施域 | [13_Technical.md](../loops/13_Technical.md) | 技术基础设施、报表与分析、API文档、系统监控、技术债务、用户教育 |
|
||||
| 🌍 跨境电商域 | [14_CrossBorder.md](../loops/14_CrossBorder.md) | 跨境电商、多语言业务 |
|
||||
| 🔒 安全与风控域 | [15_Security.md](../loops/15_Security.md) | 安全与风控、用户管理与权限、多租户隔离、多租户层级、账号/店铺健康、店铺隔离 |
|
||||
| 📋 其他独立闭环 | [16_Others.md](../loops/16_Others.md) | 定价与利润决策、核心服务优先级、多店铺管理、商家选择发货、客户/商家押金 |
|
||||
|
||||
---
|
||||
|
||||
@@ -110,12 +110,6 @@
|
||||
5. 各闭环之间通过数据流转和依赖关系形成完整的业务生态系统。
|
||||
6. 所有业务操作均需遵循项目特定规则，确保系统安全和数据一致性。
|
||||
7. **"闭环写入规则：只要逻辑上能闭环就写，落地方式后置"**
|
||||
8. **系统层级结构**：
|
||||
- L1（业务闭环）：交易系统核心流程
|
||||
- L2（系统决策层）：定价、风控、健康度等系统级能力
|
||||
- L3（数据中台层）：商品主数据、成本基准等数据管理能力
|
||||
- L4（自动化与增长）：任务调度、A/B测试、用户资产等高级能力
|
||||
9. **横切能力**：账号健康度、任务调度、权限审计等能力贯穿所有业务闭环，确保系统稳定性和安全性。
|
||||
|
||||
---
|
||||
|
||||
@@ -123,12 +117,12 @@
|
||||
|
||||
| 文档 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| **Task Overview** | [Task_Overview.md](./Task_Overview.md) | AI开发任务总览，包含所有任务包和状态 |
|
||||
| **AI Strategy** | [../05_AI/01_Strategy.md](../05_AI/01_Strategy.md) | AI协作策略、节点自动决策体系、规则引擎 |
|
||||
| **System Architecture** | [../01_Architecture/01_System.md](../01_Architecture/01_System.md) | 系统架构设计 |
|
||||
| **State Machine** | [../01_Architecture/06_State_Machine.md](../01_Architecture/06_State_Machine.md) | 状态机定义 |
|
||||
| **Backend Design** | [../02_Backend/01_Design.md](../02_Backend/01_Design.md) | 后端设计规范 |
|
||||
| **Frontend Design** | [../03_Frontend/01_Design.md](../03_Frontend/01_Design.md) | 前端设计规范 |
|
||||
| **Task Overview** | [Task_Overview.md](../tasks/Task_Overview.md) | AI开发任务总览，包含所有任务包和状态 |
|
||||
| **AI Strategy** | [../../05_AI/01_Strategy.md](../../05_AI/01_Strategy.md) | AI协作策略、节点自动决策体系、规则引擎 |
|
||||
| **System Architecture** | [../../01_Architecture/01_System.md](../../01_Architecture/01_System.md) | 系统架构设计 |
|
||||
| **State Machine** | [../../01_Architecture/06_State_Machine.md](../../01_Architecture/06_State_Machine.md) | 状态机定义 |
|
||||
| **Backend Design** | [../../02_Backend/01_Design.md](../../02_Backend/01_Design.md) | 后端设计规范 |
|
||||
| **Frontend Design** | [../../03_Frontend/01_Design.md](../../03_Frontend/01_Design.md) | 前端设计规范 |
|
||||
| **Governance Standards** | [./Governance_Standards.md](./Governance_Standards.md) | 治理与审批标准 |
|
||||
|
||||
---
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
# 任务管理 (已归档)
|
||||
|
||||
> ⚠️ **警告**: 本文档已归档，内容可能过时
|
||||
>
|
||||
> **当前有效任务文档**: [../../TASKS/P2_enhancement.md](../../TASKS/P2_enhancement.md)
|
||||
>
|
||||
> **任务领取入口**: [../../TASKS/_index.md](../../TASKS/_index.md)
|
||||
>
|
||||
> **当前有效任务文档**: [../../tasks/P2_enhancement.md](../../tasks/P2_enhancement.md)
|
||||
>
|
||||
> **任务领取入口**: [../../tasks/_index.md](../../tasks/_index.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
|
||||
本文档及子目录中的任务文档为历史归档内容，记录了前期开发阶段的任务分配。
|
||||
|
||||
当前项目已进入**P2优化阶段**，所有活跃任务已迁移至 [TASKS/](../../TASKS/) 目录。
|
||||
当前项目已进入**P2优化阶段**，所有活跃任务已迁移至 [tasks/](../../tasks/) 目录。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
# 任务总览 (Task Overview) - 已归档
|
||||
|
||||
> ⚠️ **警告**: 本文档已归档，内容可能过时
|
||||
>
|
||||
> **当前有效任务文档**: [../../../TASKS/P2_enhancement.md](../../../TASKS/P2_enhancement.md)
|
||||
>
|
||||
> **任务领取入口**: [../../../TASKS/_index.md](../../../TASKS/_index.md)
|
||||
>
|
||||
> **当前有效任务文档**: [../../../tasks/P2_enhancement.md](../../../tasks/P2_enhancement.md)
|
||||
>
|
||||
> **任务领取入口**: [../../../tasks/_index.md](../../../tasks/_index.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -12,11 +12,11 @@
|
||||
|
||||
本文档记录的是前期开发阶段（P0/P1）的任务分配情况。
|
||||
|
||||
当前项目已进入**P2优化阶段**，所有活跃任务已重新整理并迁移至 [TASKS/](../../../TASKS/) 目录。
|
||||
当前项目已进入**P2优化阶段**，所有活跃任务已重新整理并迁移至 [tasks/](../../../tasks/) 目录。
|
||||
|
||||
**请勿基于本文档领取任务**，如需领取任务请查看：
|
||||
- [TASKS/P2_enhancement.md](../../../TASKS/P2_enhancement.md) - P2优化类任务
|
||||
- [TASKS/_index.md](../../../TASKS/_index.md) - 任务领取入口
|
||||
- [tasks/P2_enhancement.md](../../../tasks/P2_enhancement.md) - P2优化类任务
|
||||
- [tasks/_index.md](../../../tasks/_index.md) - 任务领取入口
|
||||
|
||||
---
|
||||
|
||||
|
||||
576
docs/ARCHIVE/05_AI/09_Frontend_Common_Issues.md
Normal file
576
docs/ARCHIVE/05_AI/09_Frontend_Common_Issues.md
Normal file
@@ -0,0 +1,576 @@
|
||||
# 前端常见问题与解决方案
|
||||
|
||||
> 本文档记录前端开发过程中遇到的常见问题及其解决方案，供 AI 和开发者参考。
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
1. [白屏问题](#1-白屏问题)
|
||||
2. [图标问题](#2-图标问题)
|
||||
3. [路由配置问题](#3-路由配置问题)
|
||||
4. [组件导出问题](#4-组件导出问题)
|
||||
5. [编码问题](#5-编码问题)
|
||||
6. [Ant Design 弃用警告](#6-ant-design-弃用警告)
|
||||
|
||||
---
|
||||
|
||||
## 1. 白屏问题
|
||||
|
||||
### 1.1 症状
|
||||
- 页面加载后显示空白
|
||||
- 浏览器控制台显示 `net::ERR_ABORTED` 错误
|
||||
- 页面无法正常渲染
|
||||
|
||||
### 1.2 常见原因
|
||||
|
||||
#### 原因 1：路由未定义
|
||||
**问题**：布局文件中的菜单链接指向未在 `.umirc.ts` 中定义的路由。
|
||||
|
||||
**解决方案**：
|
||||
在 `.umirc.ts` 中添加缺失的路由配置：
|
||||
|
||||
```typescript
|
||||
routes: [
|
||||
// 确保所有菜单链接都有对应的路由
|
||||
{
|
||||
path: '/dashboard/ai-suggestion',
|
||||
component: '@/pages/AISuggestionPage',
|
||||
},
|
||||
// ... 其他路由
|
||||
],
|
||||
```
|
||||
|
||||
#### 原因 2：组件导入错误
|
||||
**问题**：组件文件使用了错误的导出方式，导致导入失败。
|
||||
|
||||
**解决方案**：
|
||||
确保组件使用正确的导出方式：
|
||||
|
||||
```typescript
|
||||
// ❌ 错误：同时使用 export const 和 export default
|
||||
export const MyComponent: React.FC = () => { ... };
|
||||
export default MyComponent;
|
||||
|
||||
// ✅ 正确：只使用 export default
|
||||
const MyComponent: React.FC = () => { ... };
|
||||
export default MyComponent;
|
||||
```
|
||||
|
||||
#### 原因 3：图标不存在
|
||||
**问题**：使用了 `@ant-design/icons` 中不存在的图标。
|
||||
|
||||
**解决方案**：
|
||||
替换为存在的图标：
|
||||
|
||||
```typescript
|
||||
// ❌ 错误：BrainOutlined 不存在
|
||||
import { BrainOutlined } from '@ant-design/icons';
|
||||
|
||||
// ✅ 正确：使用 RobotOutlined
|
||||
import { RobotOutlined } from '@ant-design/icons';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 图标问题
|
||||
|
||||
### 2.1 症状
|
||||
- 页面白屏
|
||||
- 控制台显示 `Element type is invalid` 错误
|
||||
- 图标无法显示
|
||||
|
||||
### 2.2 常见问题图标
|
||||
|
||||
| 问题图标 | 替代图标 | 说明 |
|
||||
|---------|---------|------|
|
||||
| `BrainOutlined` | `RobotOutlined` | AI 相关功能 |
|
||||
| `MindOutlined` | `BulbOutlined` | 思维/想法相关 |
|
||||
|
||||
### 2.3 批量替换命令
|
||||
|
||||
```powershell
|
||||
# 搜索所有使用 BrainOutlined 的文件
|
||||
Get-ChildItem -Path "src" -Recurse -Filter "*.tsx" | Select-String -Pattern "BrainOutlined"
|
||||
|
||||
# 批量替换（注意：必须使用 UTF-8 编码）
|
||||
Get-ChildItem -Path "src" -Recurse -Filter "*.tsx" | ForEach-Object {
|
||||
$content = [System.IO.File]::ReadAllText($_.FullName, [System.Text.Encoding]::UTF8)
|
||||
if ($content -match 'BrainOutlined') {
|
||||
$newContent = $content -replace 'BrainOutlined', 'RobotOutlined'
|
||||
[System.IO.File]::WriteAllText($_.FullName, $newContent, [System.Text.Encoding]::UTF8)
|
||||
Write-Host "Fixed: $($_.Name)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 路由配置问题
|
||||
|
||||
### 3.1 症状
|
||||
- 访问页面返回 404
|
||||
- 页面白屏，显示 `net::ERR_ABORTED`
|
||||
- 菜单链接无法跳转
|
||||
|
||||
### 3.2 路由配置规范
|
||||
|
||||
```typescript
|
||||
// .umirc.ts
|
||||
export default defineConfig({
|
||||
routes: [
|
||||
// 根路由
|
||||
{
|
||||
path: '/',
|
||||
component: '@/pages/Homepage',
|
||||
},
|
||||
// Dashboard 路由
|
||||
{
|
||||
path: '/dashboard',
|
||||
component: '@/pages/DashboardPage',
|
||||
},
|
||||
// 子路由（必须完整定义）
|
||||
{
|
||||
path: '/dashboard/ai-suggestion',
|
||||
component: '@/pages/AISuggestionPage',
|
||||
},
|
||||
// ... 其他路由
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
### 3.3 路由与组件对应关系
|
||||
|
||||
| 路由路径 | 组件文件 | 说明 |
|
||||
|---------|---------|------|
|
||||
| `/dashboard/ai-suggestion` | `AISuggestionPage.tsx` | AI 建议页面 |
|
||||
| `/dashboard/human-approval` | `HumanApprovalPage.tsx` | 人工审批页面 |
|
||||
| `/dashboard/execution-results` | `ExecutionResults.tsx` | 执行结果页面 |
|
||||
| `/dashboard/client-management` | `ClientManagement.tsx` | 客户管理页面 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 组件导出问题
|
||||
|
||||
### 4.1 症状
|
||||
- 页面白屏
|
||||
- 控制台显示 `Element type is invalid` 错误
|
||||
- 组件无法正常渲染
|
||||
|
||||
### 4.2 正确的导出方式
|
||||
|
||||
```typescript
|
||||
// ❌ 错误：同时使用 export const 和 export default
|
||||
export const MyComponent: React.FC = () => {
|
||||
return <div>My Component</div>;
|
||||
};
|
||||
export default MyComponent;
|
||||
|
||||
// ✅ 正确：只使用 export default
|
||||
const MyComponent: React.FC = () => {
|
||||
return <div>My Component</div>;
|
||||
};
|
||||
export default MyComponent;
|
||||
|
||||
// ✅ 正确：命名导出（用于工具函数）
|
||||
export const helperFunction = () => {
|
||||
return 'helper';
|
||||
};
|
||||
```
|
||||
|
||||
### 4.3 批量修复命令
|
||||
|
||||
```powershell
|
||||
# 修复所有使用 export const 的组件文件
|
||||
Get-ChildItem -Path "src\pages" -Recurse -Filter "*.tsx" | ForEach-Object {
|
||||
$content = [System.IO.File]::ReadAllText($_.FullName, [System.Text.Encoding]::UTF8)
|
||||
if ($content -match 'export const (\w+): React\.FC') {
|
||||
$newContent = $content -replace 'export const (\w+): React\.FC', 'const $1: React.FC'
|
||||
[System.IO.File]::WriteAllText($_.FullName, $newContent, [System.Text.Encoding]::UTF8)
|
||||
Write-Host "Fixed: $($_.Name)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 编码问题
|
||||
|
||||
### 5.1 症状
|
||||
- 中文字符显示为乱码
|
||||
- 编译错误：`Unterminated string literal`
|
||||
- 文件内容损坏
|
||||
|
||||
### 5.2 原因
|
||||
PowerShell 的 `Set-Content` 命令默认使用系统编码（通常是 GBK），而不是 UTF-8。
|
||||
|
||||
### 5.3 正确的文件读写方式
|
||||
|
||||
```powershell
|
||||
# ❌ 错误：使用 Set-Content（会损坏中文）
|
||||
$content = Get-Content $_.FullName -Raw
|
||||
Set-Content -Path $_.FullName -Value $newContent
|
||||
|
||||
# ✅ 正确：使用 .NET API 并指定 UTF-8 编码
|
||||
$content = [System.IO.File]::ReadAllText($_.FullName, [System.Text.Encoding]::UTF8)
|
||||
[System.IO.File]::WriteAllText($_.FullName, $newContent, [System.Text.Encoding]::UTF8)
|
||||
```
|
||||
|
||||
### 5.4 恢复损坏的文件
|
||||
|
||||
```bash
|
||||
# 使用 Git 恢复文件
|
||||
git checkout -- src/pages
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Ant Design 弃用警告
|
||||
|
||||
### 6.1 Drawer visible 弃用
|
||||
|
||||
**警告信息**：
|
||||
```
|
||||
Warning: [antd: Drawer] `visible` is deprecated. Please use `open` instead.
|
||||
```
|
||||
|
||||
**解决方案**：
|
||||
```typescript
|
||||
// ❌ 旧写法
|
||||
<Drawer visible={visible} onClose={onClose}>
|
||||
Content
|
||||
</Drawer>
|
||||
|
||||
// ✅ 新写法
|
||||
<Drawer open={visible} onClose={onClose}>
|
||||
Content
|
||||
</Drawer>
|
||||
```
|
||||
|
||||
**批量修复命令**：
|
||||
```powershell
|
||||
Get-ChildItem -Path "src" -Recurse -Filter "*.tsx" | ForEach-Object {
|
||||
$content = [System.IO.File]::ReadAllText($_.FullName, [System.Text.Encoding]::UTF8)
|
||||
if ($content -match 'visible=\{') {
|
||||
$newContent = $content -replace 'visible=\{', 'open={'
|
||||
[System.IO.File]::WriteAllText($_.FullName, $newContent, [System.Text.Encoding]::UTF8)
|
||||
Write-Host "Fixed: $($_.Name)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 Dropdown overlay 弃用
|
||||
|
||||
**警告信息**：
|
||||
```
|
||||
Warning: [antd: Dropdown] `overlay` is deprecated. Please use `menu` instead.
|
||||
```
|
||||
|
||||
**解决方案**：
|
||||
```typescript
|
||||
// ❌ 旧写法
|
||||
<Dropdown overlay={<Menu>...</Menu>}>
|
||||
<Button>Menu</Button>
|
||||
</Dropdown>
|
||||
|
||||
// ✅ 新写法
|
||||
<Dropdown menu={{ items: [...] }}>
|
||||
<Button>Menu</Button>
|
||||
</Dropdown>
|
||||
```
|
||||
|
||||
### 6.2 Tabs.TabPane 弃用
|
||||
|
||||
**警告信息**：
|
||||
```
|
||||
Warning: [antd: Tabs] `Tabs.TabPane` is deprecated. Please use `items` instead.
|
||||
```
|
||||
|
||||
**解决方案**：
|
||||
```typescript
|
||||
// ❌ 旧写法
|
||||
<Tabs>
|
||||
<Tabs.TabPane tab="Tab 1" key="1">Content 1</Tabs.TabPane>
|
||||
<Tabs.TabPane tab="Tab 2" key="2">Content 2</Tabs.TabPane>
|
||||
</Tabs>
|
||||
|
||||
// ✅ 新写法
|
||||
<Tabs
|
||||
items={[
|
||||
{ label: 'Tab 1', key: '1', children: 'Content 1' },
|
||||
{ label: 'Tab 2', key: '2', children: 'Content 2' },
|
||||
]}
|
||||
/>
|
||||
```
|
||||
|
||||
### 6.3 Form.Item defaultValue 警告
|
||||
|
||||
**警告信息**：
|
||||
```
|
||||
Warning: [antd: Form.Item] `defaultValue` will not work on controlled Field. You should use `initialValues` of Form instead.
|
||||
```
|
||||
|
||||
**解决方案**：
|
||||
```typescript
|
||||
// ❌ 错误：在 Form.Item 中使用 defaultValue
|
||||
<Form.Item name="field" defaultValue="value">
|
||||
<Input />
|
||||
</Form.Item>
|
||||
|
||||
// ✅ 正确：在 Form 中使用 initialValues
|
||||
<Form initialValues={{ field: 'value' }}>
|
||||
<Form.Item name="field">
|
||||
<Input />
|
||||
</Form.Item>
|
||||
</Form>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. React Hooks 错误
|
||||
|
||||
### 7.1 Invalid hook call
|
||||
|
||||
**错误信息**：
|
||||
```
|
||||
Warning: Invalid hook call. Hooks can only be called inside of the body of a function component.
|
||||
```
|
||||
|
||||
**常见原因**：
|
||||
1. React 版本不匹配
|
||||
2. 违反 Hooks 使用规则
|
||||
3. 同一个应用中有多个 React 副本
|
||||
|
||||
### 7.2 图表库冲突
|
||||
|
||||
**问题**：同时使用 `@ant-design/plots` 和 `@ant-design/charts` 会导致 React Hooks 错误。
|
||||
|
||||
**解决方案**：
|
||||
统一使用 `@ant-design/charts`：
|
||||
|
||||
```powershell
|
||||
# 批量替换
|
||||
Get-ChildItem -Path "src" -Recurse -Filter "*.tsx" | ForEach-Object {
|
||||
$content = [System.IO.File]::ReadAllText($_.FullName, [System.Text.Encoding]::UTF8)
|
||||
if ($content -match '@ant-design/plots') {
|
||||
$newContent = $content -replace '@ant-design/plots', '@ant-design/charts'
|
||||
[System.IO.File]::WriteAllText($_.FullName, $newContent, [System.Text.Encoding]::UTF8)
|
||||
Write-Host "Fixed: $($_.Name)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 7.3 图表组件内部警告
|
||||
|
||||
**警告信息**：
|
||||
```
|
||||
Warning: The tag <%s> is unrecognized in this browser.
|
||||
ExpressionError: Unexpected character: }
|
||||
```
|
||||
|
||||
**原因**：这是 `@ant-design/charts` 库内部渲染 SVG 元素时产生的警告，不影响页面功能。
|
||||
|
||||
**状态**：无需修复，这是库的内部行为。如果警告过多影响开发，可以考虑：
|
||||
1. 升级 `@ant-design/charts` 到最新版本
|
||||
2. 或者使用其他图表库（如 `recharts`、`echarts`）
|
||||
|
||||
### 7.4 懒加载组件问题
|
||||
|
||||
**错误信息**：
|
||||
```
|
||||
Warning: lazy: Expected the result of a dynamic import() call.
|
||||
Error: Element type is invalid. Received a promise that resolves to: undefined.
|
||||
```
|
||||
|
||||
**原因**：
|
||||
1. Umi 框架的 MFSU（Module Federation Speed Up）特性与某些组件不兼容
|
||||
2. 组件导出方式不正确
|
||||
3. 组件文件路径错误
|
||||
|
||||
**解决方案**：
|
||||
|
||||
1. **检查组件导出方式**：
|
||||
```typescript
|
||||
// ❌ 错误：没有默认导出
|
||||
export const MyComponent = () => { ... };
|
||||
|
||||
// ✅ 正确：使用默认导出
|
||||
const MyComponent: React.FC = () => { ... };
|
||||
export default MyComponent;
|
||||
```
|
||||
|
||||
2. **检查路由配置**：
|
||||
```typescript
|
||||
// .umirc.ts
|
||||
{
|
||||
path: '/dashboard/inventory',
|
||||
component: '@/pages/Inventory/index', // 确保路径正确
|
||||
}
|
||||
```
|
||||
|
||||
3. **清除缓存并重启**：
|
||||
```bash
|
||||
# 清除 Umi 缓存
|
||||
rm -rf .umi node_modules/.cache
|
||||
|
||||
# 重启开发服务器
|
||||
npm run dev
|
||||
```
|
||||
|
||||
4. **禁用 MFSU（临时方案）**：
|
||||
```typescript
|
||||
// .umirc.ts
|
||||
export default defineConfig({
|
||||
mfsu: false,
|
||||
// ... 其他配置
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 快速排查清单
|
||||
|
||||
当遇到白屏问题时，按以下顺序排查：
|
||||
|
||||
1. **检查浏览器控制台**
|
||||
- 是否有 JavaScript 错误？
|
||||
- 是否有网络请求失败？
|
||||
|
||||
2. **检查路由配置**
|
||||
- 路由是否在 `.umirc.ts` 中定义？
|
||||
- 组件路径是否正确？
|
||||
|
||||
3. **检查组件导出**
|
||||
- 是否同时使用了 `export const` 和 `export default`？
|
||||
- 导入语句是否正确？
|
||||
|
||||
4. **检查图标使用**
|
||||
- 是否使用了不存在的图标？
|
||||
- 图标是否从 `@ant-design/icons` 正确导入？
|
||||
|
||||
5. **检查文件编码**
|
||||
- 文件是否使用 UTF-8 编码？
|
||||
- 中文字符是否正常显示？
|
||||
|
||||
---
|
||||
|
||||
## 9. DataSource 抽象层规范
|
||||
|
||||
### 9.1 为什么需要 DataSource 抽象层
|
||||
|
||||
**问题**：直接在组件中硬编码 mock 数据会导致：
|
||||
1. AI 上下文污染 - AI 无法区分真实业务逻辑和 mock 数据
|
||||
2. 维护困难 - 数据分散在各个组件中，难以统一管理
|
||||
3. 切换困难 - 从 mock 切换到真实 API 需要大量修改
|
||||
|
||||
**解决方案**：使用 DataSource 抽象层
|
||||
|
||||
### 9.2 正确的数据获取方式
|
||||
|
||||
```typescript
|
||||
// ❌ 错误：硬编码 mock 数据
|
||||
const MyComponent: React.FC = () => {
|
||||
const mockData = [
|
||||
{ id: 1, name: '商品1' },
|
||||
{ id: 2, name: '商品2' },
|
||||
];
|
||||
// ...
|
||||
};
|
||||
|
||||
// ✅ 正确：使用 DataSource 抽象层
|
||||
import { productDataSource } from '@/services/productDataSource';
|
||||
|
||||
const MyComponent: React.FC = () => {
|
||||
const [products, setProducts] = useState([]);
|
||||
|
||||
useEffect(() => {
|
||||
productDataSource.list().then(data => setProducts(data));
|
||||
}, []);
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
### 9.3 DataSource 文件规范
|
||||
|
||||
**位置**：`src/services/*DataSource.ts`
|
||||
|
||||
**命名**：`[模块名]DataSource.ts`
|
||||
|
||||
**标记**：所有 mock 实现必须包含标记：
|
||||
```typescript
|
||||
/**
|
||||
* [MOCK-XXX] 模块名DataSource
|
||||
* AI注意: 这是Mock实现，不是真实业务逻辑
|
||||
* 仅在USE_MOCK=true时启用
|
||||
*/
|
||||
```
|
||||
|
||||
### 9.4 现有 DataSource 列表
|
||||
|
||||
| 模块 | DataSource 文件 | 状态 |
|
||||
|------|----------------|------|
|
||||
| 商品 | productDataSource.ts | ✅ 已实现 |
|
||||
| 订单 | orderDataSource.ts | ✅ 已实现 |
|
||||
| 库存 | inventoryDataSource.ts | ✅ 已实现 |
|
||||
| 财务 | financeDataSource.ts | ✅ 已实现 |
|
||||
| 分析 | analyticsDataSource.ts | ✅ 已实现 |
|
||||
| 物流 | logisticsDataSource.ts | ✅ 已实现 |
|
||||
| 供应商 | suppliersDataSource.ts | ✅ 已实现 |
|
||||
| 用户 | userDataSource.ts | ✅ 已实现 |
|
||||
| 设置 | settingsDataSource.ts | ✅ 已实现 |
|
||||
| 广告 | adOptimizationDataSource.ts | ✅ 已实现 |
|
||||
|
||||
### 9.5 待改进的页面（使用硬编码 mock 数据）
|
||||
|
||||
以下 35 个页面使用了硬编码 mock 数据，需要迁移到 DataSource 抽象层：
|
||||
|
||||
| 页面 | 文件路径 |
|
||||
|------|---------|
|
||||
| AI 决策日志 | `AIDecisionLog/index.tsx` |
|
||||
| 订单管理 | `Orders/index.tsx` |
|
||||
| 异常订单 | `Orders/ExceptionOrder.tsx` |
|
||||
| 任务中心 | `TaskCenter/index.tsx` |
|
||||
| 报表 | `Reports/index.tsx` |
|
||||
| 执行结果 | `ExecutionResults.tsx` |
|
||||
| 人工审批 | `HumanApprovalPage.tsx` |
|
||||
| AI 任务管理 | `AIActionTaskManager.tsx` |
|
||||
| 运营代理增强 | `OperationAgentEnhanced.tsx` |
|
||||
| B2B 批量订单 | `B2B/BatchOrder.tsx` |
|
||||
| B2B 合同管理 | `B2B/ContractManage.tsx` |
|
||||
| B2B 企业报价 | `B2BTrade/EnterpriseQuote.tsx` |
|
||||
| B2B 贸易合同 | `B2BTrade/ContractManage.tsx` |
|
||||
| 售后退款 | `AfterSales/RefundProcess.tsx` |
|
||||
| 客户服务 | `AfterSales/CustomerService.tsx` |
|
||||
| 平台账户配置 | `Settings/PlatformAccountConfig.tsx` |
|
||||
| 系统设置 | `Settings/SystemSettings.tsx` |
|
||||
| 用户管理 | `Settings/UserManagement.tsx` |
|
||||
| 成本模板配置 | `Settings/CostTemplateConfig.tsx` |
|
||||
| Win 节点配置 | `Settings/WinNodeConfig.tsx` |
|
||||
| 汇率配置 | `Settings/ExchangeRateConfig.tsx` |
|
||||
| 供应商详情 | `Suppliers/SupplierDetail.tsx` |
|
||||
| 域名管理 | `IndependentSite/DomainManagement.tsx` |
|
||||
| 独立站订单 | `IndependentSite/IndependentSiteOrder.tsx` |
|
||||
| 竞品分析 | `Marketing/Competitors.tsx` |
|
||||
| 广告自动调整 | `Ad/AutoAdjustment/index.tsx` |
|
||||
| AI 优化 | `Ad/AIOptimization/index.tsx` |
|
||||
| 广告效果 | `Ad/Performance/index.tsx` |
|
||||
| AI 定价 | `Product/AIPricing/index.tsx` |
|
||||
| ROI 分析 | `Product/ROIAnalysis/index.tsx` |
|
||||
| 利润监控 | `Product/ProfitMonitor/index.tsx` |
|
||||
| 利润报表 | `Reports/ProfitReport.tsx` |
|
||||
| 绩效报表 | `Reports/PerformanceReport.tsx` |
|
||||
| 库存预测 | `Inventory/InventoryForecast.tsx` |
|
||||
| 批量上架 | `OperationAgent/components/ProductBatch/BatchListingModal.tsx` |
|
||||
|
||||
---
|
||||
|
||||
## 10. 相关文档
|
||||
|
||||
- [TypeScript 编译规约](./13_TypeScript_Standards.md)
|
||||
- [代码质量规范](./14_Code_Quality_Standards.md)
|
||||
- [前端开发指南](../03_Frontend/02_Development_Guide.md)
|
||||
- [Mock 架构设计](./11_Mock_Architecture.md)
|
||||
|
||||
---
|
||||
|
||||
*最后更新：2026-03-26*
|
||||
513
docs/Integrated_Review_Optimization_Plan.md
Normal file
513
docs/Integrated_Review_Optimization_Plan.md
Normal file
@@ -0,0 +1,513 @@
|
||||
# 综合审查优化计划
|
||||
|
||||
## 1. 优化目标
|
||||
|
||||
- **提高代码质量**：消除未使用的导入、注释掉的代码和重复代码
|
||||
- **完善功能实现**：确保所有方法和插件功能都有完整的实现
|
||||
- **优化服务和插件架构**：提高系统的可维护性和扩展性
|
||||
- **确保配置一致性**：确保服务和插件的配置与注册一致
|
||||
- **统一错误处理**：建立全局错误处理机制
|
||||
- **完善监控体系**：实现系统运行状态的实时监控
|
||||
|
||||
## 2. 编译错误分析（2026-03-26）
|
||||
|
||||
### 2.1 当前编译状态
|
||||
|
||||
| 项目 | 错误数 | 主要问题 |
|
||||
|------|--------|----------|
|
||||
| **Server** | 252 | 装饰器配置问题（TS1206/1240/1241/1270）、类型不匹配（TS7006/2339） |
|
||||
| **Dashboard** | 104 | 类型不匹配、productManagementDataSource状态类型冲突、aiSuggestionDataSource问题 |
|
||||
|
||||
### 2.2 Server 错误分布
|
||||
|
||||
| 错误代码 | 数量 | 说明 |
|
||||
|----------|------|------|
|
||||
| TS1241 | 50 | 无法解析方法装饰器签名 |
|
||||
| TS1270 | 50 | 装饰器函数返回类型不可分配 |
|
||||
| TS1206 | 32 | 装饰器无效 |
|
||||
| TS1240 | 27 | 装饰器签名不匹配 |
|
||||
| TS7006 | 37 | 参数类型隐式具有 any 类型 |
|
||||
| TS2339 | 21 | 属性不存在于类型上 |
|
||||
| TS2305 | 6 | 模块找不到成员 |
|
||||
| 其他 | 39 | 各种类型错误 |
|
||||
|
||||
### 2.3 Dashboard 错误分布
|
||||
|
||||
| 文件 | 错误数 | 主要问题 |
|
||||
|------|--------|----------|
|
||||
| productManagementDataSource.ts | 15 | 状态类型冲突（DRAFT vs active） |
|
||||
| OperationLogs/index.tsx | 2 | 日期选择器空值检查 |
|
||||
| aiSuggestionDataSource.ts | 2 | 类型不匹配 |
|
||||
| orderManagementDataSource.ts | 5 | 类型不匹配 |
|
||||
| 其他页面组件 | ~80 | 各种类型问题 |
|
||||
|
||||
### 2.4 核心问题
|
||||
|
||||
1. **tsoa装饰器配置问题**：Server的TS1206/1240/1241/1270错误均为tsoa装饰器配置不正确
|
||||
2. **状态类型不一致**：productManagementDataSource的ProductStatus类型定义冲突
|
||||
3. **参数类型any问题**：TS7006错误表明部分参数缺少显式类型声明
|
||||
|
||||
## 2. 现状分析
|
||||
|
||||
### 2.1 服务配置与注册概况
|
||||
|
||||
#### SERVICE_CONFIGS 定义的服务（约60个）
|
||||
|
||||
| 类别 | 数量 | 示例 |
|
||||
|------|------|------|
|
||||
| CORE | 9 | AuthService, TurboGateway, FeatureGovernance, QuotaGovernance, TenantService, DomainEventBus, BillingService, AuditService, RBACService |
|
||||
| BUSINESS | 5 | ProductService, SyncService, WarehouseService, WebhookService |
|
||||
| TELEMETRY | 10 | MemoryWatchdog, WorkerProfiler, DeadlockAdvisor, DLQMonitor, TransactionScopeService, PredictiveHealth, AutoDiagnostics, CostAttribution, TracingTopo, SemanticLog |
|
||||
| SECURITY | 7 | SecurityScan, CacheConsistency, PermissionAudit, ContainerSecurity, SSLWatch, DIDHandshake, VaultService |
|
||||
| NETWORK | 3 | FederatedNode, P2PConnection, PrivateInventorySync |
|
||||
| AI | 8 | AI Decision, AI Suggestion, AI Agent, AI Analytics等 |
|
||||
| LOGISTICS | 15+ | RouteOptimizer, LastMileOptimizer, FreightAudit等 |
|
||||
| FINANCE | 20+ | ReconciliationService, PaymentTermsService, TaxComplianceService等 |
|
||||
| MARKETING | 10+ | KOLService, MarketingCalendarService, SocialPulseService等 |
|
||||
|
||||
#### DomainBootstrap 注册的服务（100+个）
|
||||
|
||||
按优先级分组：
|
||||
- **CORE_INFRA**：FeatureGovernance, QuotaGovernance, AuthService, TurboGateway, CreativeService, TenantService, DomainEventBus, AuditService, ActionAudit, BillingService, BillingEngine等
|
||||
- **TELEMETRY & GOVERNANCE**：AutoDiagnostics, CostAttribution, TracingTopo, SemanticLog, PredictiveHealth, QuotaCircuitBreaker, RedTeaming, DataCompliance等
|
||||
- **RUNTIME**：RuntimeSystem, PriorityAsyncEngine, V2MigrationAdvisor, DocsSync, EventBus, PrivateInventorySync, SnowflakeID, PluginManager, Warmup等
|
||||
- **SECURITY**：SSLWatch, LogMasking, SecureVault, VaultService, DIDHandshake, SecurityScan, CacheConsistency, PermissionAudit, ContainerSecurity等
|
||||
- **AI-2 Customer**：CustomerService, SupportService, DisputeAdvisorService, BehavioralRiskService等
|
||||
- **AI-3 Business**：Finance/Logistics/Marketing/Trade各业务域服务
|
||||
|
||||
### 2.2 发现的问题
|
||||
|
||||
#### 问题1：配置与注册不一致
|
||||
- **SERVICE_CONFIGS** 定义了约60个服务
|
||||
- **DomainBootstrap** 注册了100+个服务
|
||||
- 部分服务命名不一致（如ChatBot vs ChatBotService）
|
||||
|
||||
#### 问题2：服务实现不完整
|
||||
- 约30个服务使用 `Promise.resolve()` 作为init实现，无实际功能
|
||||
- 部分服务init方法可能抛出异常但未正确处理
|
||||
- 部分服务依赖外部资源但缺乏重试和熔断机制
|
||||
|
||||
#### 问题3：代码质量问题
|
||||
- 存在未使用的导入
|
||||
- 存在注释掉的代码
|
||||
- 部分服务职责边界不清晰
|
||||
|
||||
#### 问题4：架构问题
|
||||
- 服务注册方式为硬编码，缺乏动态注册机制
|
||||
- 服务依赖关系缺乏自动化检测
|
||||
- 配置分散在多个文件中，缺乏统一管理
|
||||
|
||||
## 3. 优化步骤
|
||||
|
||||
### 3.1 配置与注册优化
|
||||
|
||||
#### 任务1：服务配置与注册比对分析
|
||||
**执行步骤**：
|
||||
1. 提取SERVICE_CONFIGS中所有服务名称
|
||||
2. 提取DomainBootstrap中所有注册的服务名称
|
||||
3. 比对并识别不一致的服务
|
||||
|
||||
#### 任务2：实现服务自动同步机制
|
||||
**执行步骤**：
|
||||
1. 创建ServiceRegistry同步服务
|
||||
2. 实现DomainBootstrap启动时自动注册所有SERVICE_CONFIGS中定义的服务
|
||||
3. 添加注册状态监控和告警
|
||||
|
||||
#### 任务3：插件配置与注册分析
|
||||
**执行步骤**：
|
||||
1. 检查dashboard/plugins目录结构
|
||||
2. 验证PluginManager的插件加载逻辑
|
||||
3. 识别未注册的插件
|
||||
|
||||
### 3.2 代码质量优化
|
||||
|
||||
#### 任务4：核心服务代码质量检查
|
||||
**执行步骤**：
|
||||
1. 检查核心基础设施服务
|
||||
2. 检查AI服务
|
||||
3. 检查业务域服务
|
||||
|
||||
#### 任务5：清理未使用导入和注释代码
|
||||
**执行步骤**：
|
||||
1. 使用TypeScript编译器识别未使用导入
|
||||
2. 清理注释掉的代码
|
||||
3. 验证修改后代码仍能正常编译
|
||||
|
||||
### 3.3 功能模块整合
|
||||
|
||||
#### 任务6：识别功能重叠
|
||||
**执行步骤**：
|
||||
1. 分析相似服务
|
||||
2. 识别重复功能
|
||||
3. 提出整合建议
|
||||
|
||||
#### 任务7：明确服务职责边界
|
||||
**执行步骤**：
|
||||
1. 梳理服务依赖关系图
|
||||
2. 识别职责不清的服务
|
||||
3. 重命名或拆分职责不清的服务
|
||||
|
||||
### 3.4 架构优化
|
||||
|
||||
#### 任务8：实现服务注册自动化
|
||||
**执行步骤**：
|
||||
1. 创建统一的注册入口
|
||||
2. 实现基于装饰器的自动注册
|
||||
3. 添加依赖注入支持
|
||||
|
||||
#### 任务9：建立统一配置管理
|
||||
**执行步骤**：
|
||||
1. 集中管理所有服务配置
|
||||
2. 实现配置热更新
|
||||
3. 添加配置变更审计
|
||||
|
||||
#### 任务10：完善监控体系
|
||||
**执行步骤**：
|
||||
1. 实现服务健康状态实时监控
|
||||
2. 添加异常告警机制
|
||||
3. 建立性能指标收集
|
||||
|
||||
## 4. 质量提升标准
|
||||
|
||||
### 4.1 代码质量标准
|
||||
- **代码规范**：符合项目代码规范，无未使用的导入和注释掉的代码
|
||||
- **功能完整性**：所有方法和插件功能都有完整的实现，无功能缺失
|
||||
- **错误处理**：统一的错误处理机制，异常处理规范
|
||||
- **代码冗余**：无重复代码，功能相似的方法和代码得到合并
|
||||
|
||||
### 4.2 架构标准
|
||||
- **注册机制**：服务和插件注册机制自动化，配置与注册一致
|
||||
- **依赖管理**：依赖关系清晰，无循环依赖
|
||||
- **配置管理**：统一的配置管理机制，配置集中管理
|
||||
- **监控体系**：完善的监控和日志体系，系统运行状态可监控
|
||||
|
||||
### 4.3 性能标准
|
||||
- **响应时间**：服务和插件响应时间符合业务要求
|
||||
- **资源使用**：系统资源使用合理，无资源泄漏
|
||||
- **可扩展性**：系统能够支持业务增长，性能随资源增加而线性提升
|
||||
|
||||
## 5. 实施计划
|
||||
|
||||
### 阶段1：配置与注册优化（1周）
|
||||
| 任务 | 描述 | 优先级 |
|
||||
|------|------|--------|
|
||||
| T1.1 | 服务配置与注册比对分析 | P0 |
|
||||
| T1.2 | 识别未注册/未配置服务 | P0 |
|
||||
| T1.3 | 补充缺失的服务注册/配置 | P1 |
|
||||
| T1.4 | 插件配置与注册分析 | P1 |
|
||||
|
||||
### 阶段2：代码质量优化（2周）
|
||||
| 任务 | 描述 | 优先级 |
|
||||
|------|------|--------|
|
||||
| T2.1 | 核心服务代码质量检查 | P0 |
|
||||
| T2.2 | 清理未使用导入 | P1 |
|
||||
| T2.3 | 清理注释代码 | P1 |
|
||||
| T2.4 | 完善功能实现 | P1 |
|
||||
|
||||
### 阶段3：功能模块整合（2周）
|
||||
| 任务 | 描述 | 优先级 |
|
||||
|------|------|--------|
|
||||
| T3.1 | 识别功能重叠 | P1 |
|
||||
| T3.2 | 整合重复功能 | P2 |
|
||||
| T3.3 | 明确服务边界 | P1 |
|
||||
|
||||
### 阶段4：架构优化（3周）
|
||||
| 任务 | 描述 | 优先级 |
|
||||
|------|------|--------|
|
||||
| T4.1 | 服务注册自动化 | P1 |
|
||||
| T4.2 | 统一配置管理 | P2 |
|
||||
| T4.3 | 完善监控体系 | P2 |
|
||||
|
||||
## 6. 风险评估
|
||||
|
||||
### 6.1 风险识别
|
||||
- **注册失败**：自动同步机制可能导致服务或插件注册失败
|
||||
- **功能冲突**：功能整合可能导致功能冲突
|
||||
- **依赖循环**：依赖管理可能出现循环依赖
|
||||
- **性能下降**：架构优化可能导致性能下降
|
||||
|
||||
### 6.2 风险缓解策略
|
||||
- **注册失败**：建立注册状态的实时监控和告警机制
|
||||
- **功能冲突**：在整合前进行充分的功能分析和测试
|
||||
- **依赖循环**：建立依赖关系的自动检测和验证机制
|
||||
- **性能下降**：在优化过程中进行性能测试，确保性能不下降
|
||||
|
||||
## 7. 结论
|
||||
|
||||
通过实施综合审查优化计划，我们将显著提高系统的可维护性、可扩展性和稳定性，为业务发展提供更加坚实的技术基础。
|
||||
|
||||
## 8. 执行记录
|
||||
|
||||
### 执行记录
|
||||
|
||||
#### 2026-03-26 (上午)
|
||||
- ✅ T10: 分析了30个Promise.resolve()服务，确认大部分为合理设计
|
||||
- ✅ T12: 确认未使用导入问题（主要存在于tsoa装饰器）
|
||||
- ✅ T13: 确认DomainBootstrap中注释为合理代码组织注释
|
||||
- ✅ T14: 分析了占位符服务，确认大部分有实际业务逻辑
|
||||
- ✅ T15: 发现了2组同名服务冲突（BehavioralRiskService, PaymentRiskService）
|
||||
|
||||
#### 2026-03-26 (下午)
|
||||
- ✅ T15.1: 合并BehavioralRiskService - 将core/governance版本合并到services/security
|
||||
- ✅ T15.2: 合并PaymentRiskService - 将domains/Finance版本合并到services/settlement
|
||||
- ✅ T16: GreenSupplyChain分析 - 确认不是重复，功能不同
|
||||
- ✅ 前端冗余清理: 删除OrderListRefactored.tsx、B2B/目录、Return/目录
|
||||
- ✅ T17: 操作日志可视化 - 在13_Technical.md中添加操作日志可视化方案
|
||||
- ✅ T17.1: 创建operationLogDataSource.ts
|
||||
- ✅ T17.2: 创建OperationLogs/index.tsx前端页面
|
||||
- ✅ T17.3: 扩展AuditService支持loop/stage字段
|
||||
- ✅ T17.4: 扩展AuditController.getTimeline支持闭环筛选
|
||||
- ✅ T17.5: 添加/dashboard/operation-logs路由
|
||||
- ✅ T25.1: Server tsoa装饰器配置 - 添加experimentalDecorators和emitDecoratorMetadata
|
||||
- Server错误从 **252 降至 93**（减少159个装饰器错误）
|
||||
- ✅ T25.2: Dashboard编译错误修复 - 修复operationLogDataSource.ts和OperationLogs/index.tsx
|
||||
- ✅ 更新Business_ClosedLoops.md: 修正文档路径引用
|
||||
- ✅ tasks目录审查: 发现P3_development.md统计数字不一致（19 vs 22）
|
||||
|
||||
### 前端重叠冗余分析
|
||||
|
||||
#### 已清理的冗余
|
||||
| 文件/目录 | 说明 | 状态 |
|
||||
|-----------|------|------|
|
||||
| `pages/Orders/OrderListRefactored.tsx` | 与OrderList.tsx功能重复，无路由引用 | ✅ 已删除 |
|
||||
| `pages/B2B/` 目录 | 与B2BTrade重复，无路由引用 | ✅ 已删除 |
|
||||
|
||||
#### 待确认清理
|
||||
| 文件/目录 | 说明 | 建议 |
|
||||
|-----------|------|------|
|
||||
| `pages/Return/` | 无路由引用，可能是遗留 | ✅ 已删除 |
|
||||
|
||||
#### 正常的设计（已验证非重复）
|
||||
| 文件对 | 关系 | 说明 |
|
||||
|--------|------|------|
|
||||
| cloud-service.ts | 独立服务 | 云服务器管理API |
|
||||
| cloud-control-layer.ts | 独立服务 | 云控制四层架构 |
|
||||
| lightweightClientService.ts | 被引用 | 被clientDataSource和OperationAgentEnhanced使用 |
|
||||
|
||||
### ⚠️ 待处理: 同名服务合并、功能重叠分析
|
||||
|
||||
### 分析发现
|
||||
|
||||
#### 服务命名不一致示例（部分）
|
||||
| SERVICE_CONFIGS | DomainBootstrap | 状态 |
|
||||
|------|------|------|
|
||||
| ChatBot | ChatBotService | ⚠️ 命名不一致 |
|
||||
| ImageRecognition | ImageRecognitionService | ⚠️ 命名不一致 |
|
||||
| NaturalLanguageProcessing | NaturalLanguageProcessingService | ⚠️ 命名不一致 |
|
||||
| Recommendation | RecommendationService | ⚠️ 命名不一致 |
|
||||
| RouteOptimizer | RouteOptimizerService | ⚠️ 命名不一致 |
|
||||
| LastMileAI | LastMileAIService | ⚠️ 命名不一致 |
|
||||
| FreightAudit | FreightAuditService | ⚠️ 命名不一致 |
|
||||
| LogisticTelemetry | LogisticTelemetryService | ⚠️ 命名不一致 |
|
||||
| CashflowForecast | CashflowForecastService | ⚠️ 命名不一致 |
|
||||
| DynamicPricing | DynamicPricingService | ⚠️ 命名不一致 |
|
||||
| CurrencyRisk | CurrencyRiskService | ⚠️ 命名不一致 |
|
||||
| TaxCompliance | TaxComplianceService | ⚠️ 命名不一致 |
|
||||
| FinanceReconciliation | FinanceReconciliationService | ⚠️ 命名不一致 |
|
||||
| OrderProfit | OrderProfitService | ⚠️ 命名不一致 |
|
||||
| PricingAudit | PricingAuditService | ⚠️ 命名不一致 |
|
||||
| KOL | KOLService | ⚠️ 命名不一致 |
|
||||
| SocialPulse | SocialPulseService | ⚠️ 命名不一致 |
|
||||
| MarketingCalendar | MarketingCalendarService | ⚠️ 命名不一致 |
|
||||
|
||||
#### 使用Promise.resolve()作为init实现的服务（约30个）
|
||||
这些服务没有实际的初始化逻辑，需要评估是否需要实现或移除：
|
||||
- VisualSourcing, SLAScoring, TrustEvolution, DisputeClassifier
|
||||
- GreenSupply, HolidayRisk, PackingOptimizer, StuckTracking
|
||||
- InvoiceLateRisk, ContentGap, GlobalCSMonitor, ProcurementAudit
|
||||
- SensibleStock, PaymentRisk, DynamicShipping, LeadTimeDrift
|
||||
- InventoryAging, SupplierRiskRadar, PlatformFeeWatcher, StyleWar
|
||||
- SeaFreightAdvisor, AutoRCA, SandboxROIAdvisor, V2MigrationAdvisor
|
||||
- PrivateInventorySync, TrustEvolution, LogisticTelemetry等
|
||||
|
||||
#### 插件系统现状
|
||||
**前端插件（dashboard/src/plugins/）**：7个feature
|
||||
- AIOperationsFeature, AutoPricingFeature, MultiShopFeature
|
||||
- B2BTradeFeature, IndependentSiteFeature, AdvancedAnalyticsFeature, APIAccessFeature
|
||||
|
||||
**后端插件（server/plugins/）**：PluginManager自动加载.plugin.ts文件
|
||||
|
||||
#### 核心服务代码质量
|
||||
检查AuthService和ReconciliationService：
|
||||
- ✅ 有完整的JSDoc注释
|
||||
- ✅ 有完善的错误处理
|
||||
- ✅ 五元组（tenantId, shopId, taskId, traceId, businessType）贯穿整个服务
|
||||
- ⚠️ 部分服务实现使用硬编码值（如汇率7.25）
|
||||
|
||||
### Promise.resolve()服务分析（30个）
|
||||
|
||||
#### 有正当理由（不需要表初始化）的服务
|
||||
| 服务名 | 原因 |
|
||||
|--------|------|
|
||||
| DynamicPricing | 注释说明不需要初始化表 |
|
||||
| VisualSourcing | 使用sourcing_audit表 |
|
||||
| SLAScoring | 使用sourcing_audit表 |
|
||||
|
||||
#### 需要实现或移除的服务（占位符）
|
||||
TrustEvolution, DisputeClassifier, GreenSupply, HolidayRisk, PackingOptimizer, StuckTracking, InvoiceLateRisk, ContentGap, GlobalCSMonitor, ProcurementAudit, SensibleStock, PaymentRisk, DynamicShipping, LeadTimeDrift, InventoryAging, SupplierRiskRadar, PlatformFeeWatcher, StyleWar, SeaFreightAdvisor, AutoRCA, SandboxROIAdvisor, V2MigrationAdvisor, PrivateInventorySync, LogisticTelemetry, GlobalTracing
|
||||
|
||||
### 功能重叠和冗余分析
|
||||
|
||||
#### 同名服务冲突（需要合并或重构）
|
||||
| 冲突1 | 路径1 | 路径2 | 建议 |
|
||||
|-------|-------|-------|------|
|
||||
| BehavioralRiskService | `core/governance/` | `services/security/` | 合并到统一位置 |
|
||||
| PaymentRiskService | `domains/Finance/` | `services/settlement/` | 合并到统一位置 |
|
||||
|
||||
#### 待执行任务
|
||||
1. **T15.1 合并BehavioralRiskService** - 两个同名服务功能可能重叠
|
||||
2. **T15.2 合并PaymentRiskService** - 两个同名服务功能可能重叠
|
||||
3. **T16 清理GreenSupplyChain重复** - GreenSupplyService vs GreenSupplyChainService
|
||||
|
||||
### 待执行任务
|
||||
|
||||
#### 高优先级
|
||||
| 任务ID | 描述 | 说明 | 状态 |
|
||||
|--------|------|------|------|
|
||||
| T17 | 统一命名机制应用 | DomainBootstrap应用resolveServiceName()解析别名 | pending |
|
||||
| T18 | 服务配置重复检查 | 定期检查serviceConfig.ts是否有重复定义 | pending |
|
||||
| T19 | 验证合并结果 | 验证BehavioralRiskService和PaymentRiskService合并后正常工作 | pending |
|
||||
| T25 | Server tsoa装饰器配置 | 修复Server 252个装饰器相关编译错误 | pending |
|
||||
| T26 | Dashboard类型冲突 | 修复productManagementDataSource状态类型冲突 | pending |
|
||||
|
||||
#### 中优先级
|
||||
| 任务ID | 描述 | 说明 | 状态 |
|
||||
|--------|------|------|------|
|
||||
| T20 | 评估30个Promise.resolve()服务 | 确定是否需要实现或移除 | pending |
|
||||
| T21 | tsoa装饰器问题 | 框架级配置问题，需单独处理 | blocked by T25 |
|
||||
| T22 | 服务注册自动化 | 实现基于装饰器的自动注册 | pending |
|
||||
|
||||
#### 低优先级
|
||||
| 任务ID | 描述 | 说明 | 状态 |
|
||||
|--------|------|------|------|
|
||||
| T23 | 统一配置管理 | 集中管理所有服务配置 | pending |
|
||||
| T24 | 完善监控体系 | 实现服务健康状态实时监控 | pending |
|
||||
|
||||
### Dashboard 31个编译错误修复进度
|
||||
|
||||
| 优先级 | 文件 | 错误数 | 修复策略 | 状态 |
|
||||
|--------|------|--------|----------|------|
|
||||
| P0 | DataSource层 (4个文件) | 0 | 类型定义修复 | ✅ 已完成 |
|
||||
| P0 | 页面组件导入问题 | 0 | export default修复 | ✅ 已完成 |
|
||||
| P0 | ProductList null类型 | 0 | null改为undefined | ✅ 已完成 |
|
||||
| P0 | Ads/Ad status类型 | 0 | 添加as const断言 | ✅ 已完成 |
|
||||
| P0 | ProductBatch组件 | 0 | Input导入/as const修复 | ✅ 已完成 |
|
||||
| P0 | BatchListingModal | 0 | PlatformTik→ShopOutlined | ✅ 已完成 |
|
||||
| P0 | orderManagementDataSource | 0 | mockShops类型添加 | ✅ 已完成 |
|
||||
| P1 | 测试文件 | 21 | jest mock类型问题 | pending |
|
||||
| P2 | ProductPublishForm | 2 | 表单类型问题 | pending |
|
||||
| P2 | HumanApprovalForm | 4 | 组件类型问题 | pending |
|
||||
|
||||
### Server 93个编译错误修复进度
|
||||
|
||||
| 优先级 | 问题 | 错误数 | 修复策略 | 状态 |
|
||||
|--------|------|--------|----------|------|
|
||||
| P0 | tsoa装饰器配置 | 0 | 配置tsconfig.json | ✅ 已完成 |
|
||||
| P1 | sequelize模块缺失 | ~15 | 安装依赖或使用替代方案 | pending |
|
||||
| P1 | TS7006参数any | 37 | 为参数添加显式类型 | pending |
|
||||
| P1 | TS2339属性不存在 | 21 | 检查并修复类型定义 | pending |
|
||||
| P2 | 其他 | ~20 | 逐个修复 | pending |
|
||||
|
||||
|
||||
、
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
# JS 统一管理 import 导入（推荐方案）
|
||||
完全可以！**把所有模块的 import 统一放到一个单独文件里**，再统一导出，其他文件直接从这个文件引入，这是 JS/TS 项目最常用的规范写法。
|
||||
|
||||
## 一、最简实战示例
|
||||
### 1. 创建统一导入文件（推荐命名：`utils/index.js`）
|
||||
```javascript
|
||||
// 统一导入所有需要的模块
|
||||
import axios from 'axios';
|
||||
import dayjs from 'dayjs';
|
||||
import { ref, reactive } from 'vue';
|
||||
import { getUserInfo } from './api/user';
|
||||
import { formatMoney } from './tools/format';
|
||||
|
||||
// 统一导出（其他文件直接从这里引入）
|
||||
export {
|
||||
axios,
|
||||
dayjs,
|
||||
ref,
|
||||
reactive,
|
||||
getUserInfo,
|
||||
formatMoney
|
||||
};
|
||||
```
|
||||
|
||||
### 2. 其他文件使用（无需重复写长路径）
|
||||
```javascript
|
||||
// 原来的写法（繁琐、重复）
|
||||
// import axios from 'axios';
|
||||
// import { ref } from 'vue';
|
||||
// import { formatMoney } from '../../tools/format';
|
||||
|
||||
// 新写法（一行搞定，清爽统一）
|
||||
import { axios, ref, formatMoney } from '@/utils';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、进阶写法：按模块分组（大型项目推荐）
|
||||
如果模块很多，可以**分文件管理**，结构更清晰：
|
||||
```
|
||||
src/
|
||||
├─ imports/ # 统一导入文件夹
|
||||
│ ├─ index.js # 主入口
|
||||
│ ├─ libs.js # 第三方库（axios、dayjs）
|
||||
│ ├─ vue.js # Vue 相关 API
|
||||
│ └─ tools.js # 项目自定义工具
|
||||
```
|
||||
|
||||
**`imports/index.js`（总入口）**
|
||||
```javascript
|
||||
// 聚合所有子文件，统一导出
|
||||
export * from './libs';
|
||||
export * from './vue';
|
||||
export * from './tools';
|
||||
```
|
||||
|
||||
**使用**
|
||||
```javascript
|
||||
import { axios, ref, formatMoney } from '@/imports';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、核心优势
|
||||
1. **代码更简洁**：不用每个文件都写一堆 import
|
||||
2. **维护更方便**：要修改依赖只改一个文件
|
||||
3. **路径更短**：解决多层 `../../` 嵌套问题
|
||||
4. **规范统一**：团队协作导入方式一致
|
||||
|
||||
---
|
||||
|
||||
## 四、小提示
|
||||
1. 这种写法**不会影响打包体积**，Tree-Shaking（摇树优化）依然生效，没用到的模块不会打包进去
|
||||
2. 配合别名（`@/`）使用体验最佳，Vue/React/Vite 都支持配置路径别名
|
||||
3. 不要过度统一，只把**高频使用**的模块放进去即可
|
||||
|
||||
### 总结
|
||||
1. 新建一个文件统一 `import` + `export`
|
||||
2. 其他文件直接从这个文件引入
|
||||
3. 大型项目可分组管理，结构更清晰
|
||||
4. 安全无副作用，打包体积不受影响
|
||||
|
||||
|
||||
|
||||
能统一的，全部统一；
|
||||
能抽离的，全部抽离；
|
||||
能复用的，全部复用。
|
||||
前端最值得统一的 8 类：
|
||||
导入（imports）
|
||||
工具函数
|
||||
接口请求
|
||||
常量
|
||||
枚举
|
||||
全局组件
|
||||
表单校验
|
||||
全局配置
|
||||
@@ -70,6 +70,157 @@
|
||||
- **输入**：系统数据、日志数据、监控指标
|
||||
- **输出**：监控报告、告警通知、运维操作记录
|
||||
|
||||
### 6️⃣5️⃣.1 操作日志可视化
|
||||
|
||||
> 为业务闭环提供统一的操作日志记录和可视化追踪
|
||||
|
||||
#### 日志数据模型
|
||||
|
||||
```typescript
|
||||
interface OperationLog {
|
||||
id: string; // 唯一ID (UUID)
|
||||
timestamp: string; // ISO 8601 时间戳
|
||||
businessType: 'TOC' | 'TOB'; // 业务类型
|
||||
|
||||
// 五元组
|
||||
tenantId: string;
|
||||
shopId: string;
|
||||
taskId?: string;
|
||||
traceId: string;
|
||||
|
||||
// 操作信息
|
||||
loop: string; // 闭环标识，如 "OrderFulfillment"
|
||||
loopName: string; // 闭环名称，如 "订单履约"
|
||||
stage: string; // 当前阶段
|
||||
stageName: string; // 阶段名称
|
||||
|
||||
// 执行者
|
||||
actor: 'AI' | 'USER' | 'SYSTEM';
|
||||
actorId?: string; // 操作人ID
|
||||
actorName?: string; // 操作人名称
|
||||
|
||||
// 状态变化
|
||||
beforeState?: string;
|
||||
afterState: string;
|
||||
|
||||
// 操作详情
|
||||
action: string; // 操作类型：CREATE/UPDATE/DELETE/APPROVE/REJECT
|
||||
actionName: string; // 操作名称
|
||||
details?: Record<string, any>; // 详细信息
|
||||
|
||||
// 异常处理
|
||||
error?: string;
|
||||
errorCode?: string;
|
||||
|
||||
// 关联
|
||||
parentTraceId?: string; // 父链路追踪ID
|
||||
children?: string[]; // 子链路IDs
|
||||
}
|
||||
```
|
||||
|
||||
#### 日志表设计
|
||||
|
||||
```sql
|
||||
CREATE TABLE cf_operation_logs (
|
||||
id VARCHAR(64) PRIMARY KEY,
|
||||
timestamp DATETIME(3) NOT NULL,
|
||||
business_type ENUM('TOC', 'TOB') NOT NULL,
|
||||
|
||||
-- 五元组
|
||||
tenant_id VARCHAR(64) NOT NULL,
|
||||
shop_id VARCHAR(64) NOT NULL,
|
||||
task_id VARCHAR(64),
|
||||
trace_id VARCHAR(64) NOT NULL,
|
||||
|
||||
-- 操作信息
|
||||
loop VARCHAR(64) NOT NULL, -- 闭环标识
|
||||
loop_name VARCHAR(128) NOT NULL, -- 闭环名称
|
||||
stage VARCHAR(64) NOT NULL, -- 阶段标识
|
||||
stage_name VARCHAR(128) NOT NULL, -- 阶段名称
|
||||
|
||||
-- 执行者
|
||||
actor ENUM('AI', 'USER', 'SYSTEM') NOT NULL,
|
||||
actor_id VARCHAR(64),
|
||||
actor_name VARCHAR(128),
|
||||
|
||||
-- 状态
|
||||
before_state VARCHAR(64),
|
||||
after_state VARCHAR(64) NOT NULL,
|
||||
|
||||
-- 操作
|
||||
action VARCHAR(32) NOT NULL,
|
||||
action_name VARCHAR(128) NOT NULL,
|
||||
details JSON,
|
||||
|
||||
-- 异常
|
||||
error TEXT,
|
||||
error_code VARCHAR(32),
|
||||
|
||||
-- 关联
|
||||
parent_trace_id VARCHAR(64),
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
|
||||
INDEX idx_tenant_shop (tenant_id, shop_id),
|
||||
INDEX idx_trace_id (trace_id),
|
||||
INDEX idx_timestamp (timestamp),
|
||||
INDEX idx_loop_stage (loop, stage)
|
||||
);
|
||||
```
|
||||
|
||||
#### 可视化界面设计
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 📋 操作日志中心 [导出] [筛选] │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ 租户: [T001 - 测试租户 ▼] 店铺: [全部 ▼] │
|
||||
│ 闭环: [全部 ▼] 阶段: [全部 ▼] 操作: [全部 ▼] │
|
||||
│ 时间: [2026-03-26 00:00] ~ [2026-03-26 23:59] [搜索...] │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ● 14:32:15 AI 订单履约 - 订单审核 │
|
||||
│ │ tenant: T001 shop: S001 trace: TRX-789456 │
|
||||
│ │ ✅ 待审核 → 已确认 │
|
||||
│ │ 📝 AI建议：订单金额$299，低于阈值，自动通过 │
|
||||
│ ▼ │
|
||||
│ │
|
||||
│ ● 14:30:02 USER 订单履约 - 分仓 │
|
||||
│ │ tenant: T001 shop: S001 trace: TRX-789123 │
|
||||
│ │ ✅ 已确认 → 已分仓 │
|
||||
│ │ 👤 操作人: admin@company.com │
|
||||
│ │ 📦 仓库: WH-SH-01 (上海仓) │
|
||||
│ ▼ │
|
||||
│ │
|
||||
│ ● 14:28:45 SYSTEM 订单履约 - 订单确认 │
|
||||
│ │ tenant: T001 shop: S001 trace: TRX-789000 │
|
||||
│ │ ⏰ 5分钟前异常已自动恢复 │
|
||||
│ │ ⚠️ 告警: 支付回调延迟，但已自动重试成功 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### 日志节点状态对应
|
||||
|
||||
| 状态 | 图标 | 颜色 | 说明 |
|
||||
|------|------|------|------|
|
||||
| SUCCESS | ✅ | green | 操作成功 |
|
||||
| PENDING | ⏳ | yellow | 待处理 |
|
||||
| FAILED | ❌ | red | 操作失败 |
|
||||
| WARNING | ⚠️ | orange | 警告/异常已恢复 |
|
||||
| AI_SUGGESTION | 💡 | blue | AI建议 |
|
||||
| HUMAN_ACTION | 👤 | purple | 人工操作 |
|
||||
| SYSTEM_ACTION | 🔧 | gray | 系统自动 |
|
||||
|
||||
#### 与其他闭环的联动
|
||||
|
||||
| 闭环 | 日志记录节点 |
|
||||
|------|-------------|
|
||||
| 订单履约 (02_Order) | 订单获取、审核确认、分仓、发货、签收 |
|
||||
| 商品管理 (01_Product) | 商品上架、审核、下架、价格调整 |
|
||||
| AI自动化 (10_AI_Automation) | AI决策、人工确认、执行、日志记录 |
|
||||
| 财务结算 (04_Finance) | 对账、结算、退款、佣金 |
|
||||
| 售后逆向 (02_Order - Returns) | 退货受理、退货确认、退款 |
|
||||
|
||||
***
|
||||
|
||||
## 6️⃣8️⃣ 技术债务管理闭环（Technical Debt Management Loop）
|
||||
|
||||
@@ -828,10 +828,10 @@ AI自动执行 推送给用户
|
||||
|
||||
| 文档 | 路径 |
|
||||
|------|------|
|
||||
| AI自动化域 | docs/LOOPS/10_AI_Automation.md |
|
||||
| 广告页面前端 | docs/ARCHIVE/01_Architecture/frontend/03_Ad.md |
|
||||
| 后端广告服务 | docs/ARCHIVE/00_Business/tasks/backend/08_advertisement.md |
|
||||
| 统一类型管理 | docs/ARCHIVE/01_Architecture/16_Unified_Type_Management.md |
|
||||
| AI自动化域 | docs/loops/10_AI_Automation.md |
|
||||
| 广告页面前端 | docs/archive/01_Architecture/frontend/03_Ad.md |
|
||||
| 后端广告服务 | docs/archive/00_Business/tasks/backend/08_advertisement.md |
|
||||
| 统一类型管理 | docs/archive/01_Architecture/16_Unified_Type_Management.md |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
> **状态说明**: 指闭环**文档**的完成状态，非代码实现状态
|
||||
> - ✅ 已完成 = 文档已完善，业务逻辑已定义
|
||||
> - 📝 待开发 = 文档待完善或业务逻辑待定义
|
||||
> - 代码实现状态请查看 [任务中心](../TASKS/_index.md)
|
||||
> - 代码实现状态请查看 [任务中心](../tasks/_index.md)
|
||||
|
||||
| 文件 | 内容 | 重要性 | 文档状态 |
|
||||
|------|------|--------|----------|
|
||||
@@ -84,10 +84,9 @@ AI自动化 → 平台管理 → 商户管理
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
- [规则中心](../RULES/_index.md)
|
||||
- [服务地图](../SERVICES/_index.md)
|
||||
- [架构设计](../ARCH/_index.md)
|
||||
- [任务中心](../TASKS/_index.md)
|
||||
- [规则中心](../rules/_index.md)
|
||||
- [服务地图](../services/_index.md)
|
||||
- [任务中心](../tasks/_index.md)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -65,12 +65,13 @@ B2C利润率 < 20%: 触发风控预警
|
||||
```
|
||||
docs/
|
||||
├── README.md ← 你在这里
|
||||
├── RULES/ # 硬性规则
|
||||
├── TASKS/ # 任务中心
|
||||
├── rules/ # 硬性规则
|
||||
├── tasks/ # 任务中心
|
||||
├── ARCH/ # 系统架构
|
||||
├── SERVICES/ # 服务地图
|
||||
├── LOOPS/ # 业务闭环
|
||||
└── ARCHIVE/ # 历史归档
|
||||
├── services/ # 服务地图
|
||||
├── loops/ # 业务闭环
|
||||
├── api/ # API文档
|
||||
└── archive/ # 历史归档
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -48,6 +48,6 @@ TOC利润率 < 20%: 触发风控预警
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
- [任务中心](../TASKS/_index.md)
|
||||
- [任务中心](../tasks/_index.md)
|
||||
- [架构设计](../ARCH/_index.md)
|
||||
- [服务地图](../SERVICES/_index.md)
|
||||
- [服务地图](../services/_index.md)
|
||||
|
||||
152
docs/RULES/documentation.md
Normal file
152
docs/RULES/documentation.md
Normal file
@@ -0,0 +1,152 @@
|
||||
# 文档规范标准
|
||||
|
||||
## 1. 目录命名规范
|
||||
|
||||
### 1.1 目录命名规则
|
||||
|
||||
| 类别 | 格式 | 示例 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 主目录 | 中文或英文 | `docs/Business/` | 业务线/域 |
|
||||
| 子目录 | 数字前缀+英文 | `docs/Business/01_Product/` | 模块序号 |
|
||||
| 归档目录 | `ARCHIVE/` | `docs/ARCHIVE/` | 历史文档 |
|
||||
|
||||
### 1.2 目录大小写规则
|
||||
|
||||
- **全部使用小写**：所有目录名必须使用小写字母
|
||||
- **分隔符**：使用 `-` 或 `_`，保持一致
|
||||
- **示例**：
|
||||
- ✅ `docs/business/`, `docs/architecture/`
|
||||
- ❌ `docs/Business/`, `docs/ARCHIVE/`
|
||||
|
||||
### 1.3 主目录结构
|
||||
|
||||
```
|
||||
docs/
|
||||
├── business/ # 业务文档
|
||||
├── architecture/ # 架构文档
|
||||
├── api/ # API文档
|
||||
├── rules/ # 规范文档
|
||||
├── tasks/ # 任务文档
|
||||
├── loops/ # 业务闭环文档
|
||||
└── services/ # 服务文档
|
||||
```
|
||||
|
||||
## 2. 文件命名规范
|
||||
|
||||
### 2.1 命名规则
|
||||
|
||||
| 类别 | 格式 | 示例 |
|
||||
|------|------|------|
|
||||
| 索引文件 | `index.md` | `business/index.md` |
|
||||
| 模块文档 | `NN_Name.md` | `01_Product.md` |
|
||||
| 规范文档 | `kebab-case.md` | `code-quality-rules.md` |
|
||||
| 报告文档 | `YYYY-MM-DD_Name.md` | `2026-03-20_Code_Review.md` |
|
||||
|
||||
### 2.2 文件后缀
|
||||
|
||||
- 统一使用 `.md` 后缀
|
||||
- 禁止使用 `.md_txt`、`.markdown` 等变体
|
||||
|
||||
### 2.3 命名大小写
|
||||
|
||||
- **目录**: 全部小写
|
||||
- **文件**: 首字母大写，驼峰命名（除非是 `index.md`）
|
||||
|
||||
## 3. 索引文件规范
|
||||
|
||||
### 3.1 索引文件命名
|
||||
|
||||
- **标准索引**: `index.md`
|
||||
- **禁止**: `_index.md`、`00_Index.md`、`INDEX.md`
|
||||
|
||||
### 3.2 索引文件位置
|
||||
|
||||
- 每个目录必须有 `index.md` 作为入口
|
||||
- 索引文件必须包含该目录内容的概览和链接
|
||||
|
||||
### 3.3 索引文件格式
|
||||
|
||||
```markdown
|
||||
# 模块名称
|
||||
|
||||
## 目录结构
|
||||
|
||||
- [子模块1](01_SubModule/) - 简短描述
|
||||
- [子模块2](02_SubModule/) - 简短描述
|
||||
|
||||
## 内容概览
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
## 4. 文档格式规范
|
||||
|
||||
### 4.1 标题层级
|
||||
|
||||
```markdown
|
||||
# 一级标题 (页面标题)
|
||||
## 二级标题 (主要章节)
|
||||
### 三级标题 (子章节)
|
||||
#### 四级标题 (细节内容)
|
||||
```
|
||||
|
||||
### 4.2 代码块
|
||||
|
||||
````markdown
|
||||
```typescript
|
||||
// 代码内容
|
||||
const example = 'code';
|
||||
```
|
||||
````
|
||||
|
||||
### 4.3 表格格式
|
||||
|
||||
````markdown
|
||||
| 列1 | 列2 | 列3 |
|
||||
|-----|-----|-----|
|
||||
| 内容 | 内容 | 内容 |
|
||||
````
|
||||
|
||||
## 5. 常见错误
|
||||
|
||||
### 5.1 已识别的格式错误
|
||||
|
||||
| 错误类型 | 错误示例 | 正确示例 |
|
||||
|----------|----------|----------|
|
||||
| 大小写错误 | `ARCHIVE/00_Business/` | `archive/00_business/` |
|
||||
| 索引文件命名 | `_index.md` | `index.md` |
|
||||
| 文件后缀 | `document.md_txt` | `document.md` |
|
||||
| 中文目录 | `文档/` | `documents/` |
|
||||
|
||||
### 5.2 需要修复的目录
|
||||
|
||||
| 当前路径 | 建议路径 |
|
||||
|----------|----------|
|
||||
| `docs/ARCHIVE/` | `docs/archive/` |
|
||||
| `docs/LOOPS/` | `docs/loops/` |
|
||||
| `docs/SERVICES/` | `docs/services/` |
|
||||
| `docs/TASKS/` | `docs/tasks/` |
|
||||
| `docs/RULES/` | `docs/rules/` |
|
||||
| `docs/API_Documentations/` | `docs/api/` |
|
||||
|
||||
## 6. 迁移计划
|
||||
|
||||
### 阶段1：创建规范文件
|
||||
- [x] 创建 `docs/rules/documentation.md`
|
||||
|
||||
### 阶段2：识别需要迁移的目录
|
||||
- [x] 识别所有大小写不一致的目录
|
||||
- [x] 识别所有命名不规范的目录
|
||||
|
||||
### 阶段3：执行迁移（2026-03-26）
|
||||
- [x] 重命名目录为小写（archive, api, loops, rules, services, tasks）
|
||||
- [x] 更新所有相关引用
|
||||
|
||||
### 阶段4：验证
|
||||
- [x] 检查所有链接是否有效
|
||||
- [x] 验证文档结构完整性
|
||||
|
||||
## 7. 参考
|
||||
|
||||
- 项目术语表: [TERMINOLOGY.md](../rules/TERMINOLOGY.md)
|
||||
- 业务闭环: [loops/_index.md](../loops/_index.md)
|
||||
@@ -79,6 +79,6 @@
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
- [规则中心](../RULES/_index.md)
|
||||
- [规则中心](../rules/_index.md)
|
||||
- [架构设计](../ARCH/_index.md)
|
||||
- [业务闭环](../LOOPS/_index.md)
|
||||
- [业务闭环](../loops/_index.md)
|
||||
|
||||
@@ -16,9 +16,9 @@
|
||||
|
||||
| 文件 | 内容 | 说明 |
|
||||
|------|------|------|
|
||||
| [P0_critical.md](ARCHIVE/P0_critical.md) | P0 阻塞性任务 | 核心基础功能（已完成） |
|
||||
| [P1_important.md](ARCHIVE/P1_important.md) | P1 高优先级任务 | 重要业务功能（已完成） |
|
||||
| [P2_enhancement.md](ARCHIVE/P2_enhancement.md) | P2 优化类任务 | 体验优化和增强功能（已完成） |
|
||||
| [P0_critical.md](archive/ARCHIVE/P0_critical.md) | P0 阻塞性任务 | 核心基础功能（已完成） |
|
||||
| [P1_important.md](archive/ARCHIVE/P1_important.md) | P1 高优先级任务 | 重要业务功能（已完成） |
|
||||
| [P2_enhancement.md](archive/ARCHIVE/P2_enhancement.md) | P2 优化类任务 | 体验优化和增强功能（已完成） |
|
||||
|
||||
---
|
||||
|
||||
@@ -177,9 +177,9 @@
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
- [规则中心](../RULES/_index.md)
|
||||
- [规则中心](../rules/_index.md)
|
||||
- [架构设计](../ARCH/_index.md)
|
||||
- [服务地图](../SERVICES/_index.md)
|
||||
- [服务地图](../services/_index.md)
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user