977 lines
37 KiB
Markdown
977 lines
37 KiB
Markdown
# 纺织行业采购计划管理系统
|
||
|
||
一款专为纺织行业设计的全流程协作管理平台，连接采购商（布行）、纺织厂、水洗厂三方，实现从计划制定到成品交付的数字化管理。
|
||
|
||
## 核心功能
|
||
|
||
### 多角色协作
|
||
- **采购商/布行**：创建生产计划、管理坯布库存、跟踪生产进度、处理结款
|
||
- **纺织厂**：接收生产计划、管理生产流程、坯布入库、纱线库存管理
|
||
- **水洗厂**：接收水洗订单、管理水洗流程
|
||
|
||
### 计划管理
|
||
- 自动生成唯一计划编号和坯布识别码
|
||
- 纱线配比配置与用量自动计算
|
||
- 生产流程节点跟踪（确认计划 → 采纱 → 染纱 → 上机 → 坯布入库）
|
||
- 实时进度可视化，支持97%完成度自动提醒
|
||
|
||
### 库存管理
|
||
- **产品信息**：按坯布码分组管理，入库记录追溯
|
||
- 产品管理：支持按名称、克重、颜色多级分组展示
|
||
- 出入库历史：查看每个产品的完整库存变动记录
|
||
- 价格历史：追踪采购价格变动
|
||
- 产品唯一性：产品码全局唯一，色号在"成品名称-克重-颜色"组合中唯一
|
||
- **原料纱仓库**：库存预警、最低库存提醒
|
||
- 实时库存数据同步，入库自动更新
|
||
|
||
### 结款管理
|
||
- 按完成米数自动计算结款金额
|
||
- 待结款汇总统计
|
||
- 一键确认结款，记录结款时间
|
||
|
||
### 分享与导入
|
||
- 加密分享链接，保护敏感信息
|
||
- 支持剪贴板自动识别导入
|
||
- 扫码或链接快速关联计划
|
||
|
||
## 技术特性
|
||
|
||
### 前端技术栈
|
||
- **React 18** + TypeScript - 类型安全的函数组件开发（strict模式）
|
||
- **Webpack 5** - 构建工具，开发服务器端口 3015，host: 0.0.0.0
|
||
- **TailwindCSS 3** + PostCSS - 原子化CSS，自定义CSS变量体系
|
||
- **Framer Motion** - 页面过渡、交互动画、性能降级
|
||
- **Lucide React** - 现代化图标库
|
||
- **Recharts** - 数据可视化图表
|
||
- **React Router v6** - HashRouter 模式，25条路由配置
|
||
|
||
### 多角色主题色系统
|
||
| 角色 | 主色调 | 渐变配色 | 应用场景 |
|
||
|------|--------|---------|---------|
|
||
| 采购商 | Amber | `from-amber-400 to-orange-500` | Dashboard、Layout、通知中心 |
|
||
| 纺织厂 | Emerald | `from-emerald-400 to-teal-400` | Dashboard、Layout、通知中心 |
|
||
| 水洗厂 | Violet | `from-violet-400 to-fuchsia-400` | Dashboard、通知中心 |
|
||
| 系统/公共 | Blue | `from-blue-500 to-blue-600` | 登录页、通用组件 |
|
||
|
||
### 设计架构
|
||
- **CSS变量体系**: 完整50-900色阶、6级阴影系统、毛玻璃/滚动条美化等自定义工具类
|
||
- **动效规范**: 页面过渡(opacity+slide, 0.35s)、列表交错(stagger 0.08)、Spring弹簧交互
|
||
- **性能降级**: `usePerformance` Hook 自动检测设备性能，低配设备仅使用opacity过渡
|
||
- **响应式设计**: 移动优先，断点 sm(640)/md(768)/lg(1024)/xl(1280)，桌面表格↔移动卡片自动切换
|
||
- **触控优化**: 44px最小触控区域、防双击缩放、数字键盘自动唤起
|
||
|
||
### 布局架构
|
||
| 角色 | 布局组件 | 导航项数 | 路由模式 |
|
||
|------|---------|---------|---------|
|
||
| 采购商 | PurchaserLayout | 8项 | 嵌套Outlet |
|
||
| 纺织厂 | TextileLayout | 5项 | 嵌套Outlet |
|
||
| 水洗厂 | 无独立Layout | 6项 | 扁平路由 |
|
||
|
||
### 后端服务
|
||
- **Meoo Cloud (Supabase)** - 云数据库 + 认证 + 实时订阅 + 文件存储
|
||
- **PostgreSQL** - 31张业务表，支持复杂查询和事务
|
||
- **Row Level Security** - 行级安全策略，基于 company_id 的数据隔离
|
||
- **Realtime** - 实时数据同步，单例管理器 + 引用计数自动清理
|
||
- **Storage** - avatars + product_images 两个存储桶
|
||
|
||
### 数据安全
|
||
- **RLS 策略** - 所有表启用行级安全，严格的数据访问控制
|
||
- **公司隔离** - 基于 company_id + get_user_master_company_id() 的数据隔离
|
||
- **子账号支持** - 主账号/子账号权限继承，master_id 关联
|
||
- **分享加密** - HMAC-SHA256签名 + Base64编码，30分钟有效期
|
||
- **合作关系** - company_relationships 表实现首次合作确认机制
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
- Node.js 18+
|
||
- pnpm 8+
|
||
|
||
### 安装依赖
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
### 开发模式
|
||
```bash
|
||
pnpm run dev
|
||
```
|
||
服务启动在 http://localhost:3015
|
||
|
||
### 构建生产版本
|
||
```bash
|
||
pnpm run build
|
||
```
|
||
|
||
### 数据库迁移
|
||
```bash
|
||
# 查看云服务状态
|
||
meoo-cli cloud status
|
||
|
||
# 执行数据库迁移
|
||
meoo-cli cloud migrate --sql "..." --name "migration_name" --changes "变更说明"
|
||
```
|
||
|
||
## 项目结构（2026-06-04 更新）
|
||
|
||
```
|
||
src/
|
||
├── App.tsx # 根组件（25条HashRouter路由 + PageErrorBoundary）
|
||
├── components/ # 共享组件（33个）
|
||
│ ├── layout/ # 布局组件（3个）
|
||
│ │ ├── Sidebar.tsx # 可折叠侧边栏导航
|
||
│ │ ├── PurchaserLayout.tsx # 采购商布局（8项导航 + amber主题）
|
||
│ │ └── TextileLayout.tsx # 纺织厂布局（5项导航 + emerald主题）
|
||
│ ├── warehouse/ # 仓库管理组件（6个）
|
||
│ │ ├── WarehouseNav.tsx # 仓库类型导航
|
||
│ │ ├── ProductForm.tsx # 产品创建/编辑表单
|
||
│ │ ├── InboundForm.tsx # 入库表单
|
||
│ │ ├── OutboundForm.tsx # 出库表单
|
||
│ │ ├── ProductList.tsx # 产品列表（桌面表格+移动卡片）
|
||
│ │ └── InboundRecords.tsx # 入库记录列表
|
||
│ ├── plans/ # 计划管理组件（3个）
|
||
│ │ ├── PlanGroup.tsx # 工厂分组 + 计划卡片
|
||
│ │ ├── ShareModal.tsx # 分享链接弹窗（短链+长链+隐藏敏感信息）
|
||
│ │ └── PlanEditModal.tsx # 计划编辑弹窗
|
||
│ ├── PlanCard.tsx # 计划卡片（进度条+状态+流程节点）
|
||
│ ├── ProcessFlow.tsx # 生产流程节点（呼吸动画+弹窗确认）
|
||
│ ├── ProgressBar.tsx / StatusBadge.tsx # 基础UI组件
|
||
│ ├── InventoryRecordsModal.tsx # 入库记录弹窗
|
||
│ ├── YarnAllocationModal.tsx # 纱线分配弹窗（自动/手动模式）
|
||
│ ├── NotificationCenter.tsx # 通知中心（amber/emerald/violet主题）
|
||
│ ├── HelpCenter.tsx / UserManual.tsx / OnboardingGuide.tsx # 帮助系统
|
||
│ ├── VersionUpdate.tsx / FeedbackModal.tsx / AboutModal # 版本与反馈
|
||
│ ├── CrashReporter.tsx / ErrorBoundary.tsx # 错误处理
|
||
│ ├── DemoDisclaimerModal.tsx / DemoWatermark.tsx # Demo标识
|
||
│ ├── PageTransition.tsx / VirtualList.tsx / Tooltip.tsx # UI增强
|
||
│ └── NetworkStatusBar.tsx / ComingSoonModal.tsx # 辅助组件
|
||
├── pages/ # 页面组件（25个）
|
||
│ ├── LoginPage.tsx / RegisterPage.tsx / RoleSelectPage.tsx # 认证页
|
||
│ ├── MemberManage.tsx # 子账号管理 + 帮助系统入口
|
||
│ ├── ImportPlanPage.tsx # 分享链接导入（解密+确认/拒绝）
|
||
│ ├── DemoDataSharing.tsx # 数据共享演示
|
||
│ ├── purchaser/ # 采购商页面（8个，PurchaserLayout嵌套）
|
||
│ │ ├── Dashboard.tsx # 首页（统计+最近计划+快捷操作）
|
||
│ │ ├── PlanOverview.tsx # 纺织计划总览
|
||
│ │ ├── NewPlan.tsx / NewWashingPlan.tsx # 新建计划
|
||
│ │ ├── WarehouseManage.tsx # 产品信息管理
|
||
│ │ ├── FinishedWarehouse.tsx # 成品仓库
|
||
│ │ ├── FactoryManage.tsx # 工厂管理
|
||
│ │ └── AccountsPayable.tsx # 应付账款
|
||
│ ├── textile/ # 纺织厂页面（5个，TextileLayout嵌套）
|
||
│ │ ├── Dashboard.tsx # 生产概览
|
||
│ │ ├── PlanOverview.tsx # 接单与生产进度
|
||
│ │ ├── YarnWarehouse.tsx # 原料纱仓库（出入库记录）
|
||
│ │ ├── FabricWarehouse.tsx # 已生产坯布（Realtime订阅）
|
||
│ │ └── PaymentPending.tsx # 待结款
|
||
│ └── washing/ # 水洗厂页面（6个，扁平路由无Layout）
|
||
│ ├── Dashboard.tsx # 首页（violet主题）
|
||
│ ├── PlanOverview.tsx # 水洗计划总览
|
||
│ ├── PendingFabric.tsx / CompletedFabric.tsx # 待洗/已完成
|
||
│ ├── FinishedWarehouse.tsx # 成品仓库
|
||
│ └── PaymentPending.tsx # 待结款
|
||
├── hooks/ # 自定义Hooks（9个）
|
||
│ ├── useInventoryData.ts # 库存数据（5秒缓存+Realtime）
|
||
│ ├── usePlanData.ts # 计划数据（10秒缓存+分页+Realtime）
|
||
│ ├── usePlanStatusSync.ts # 计划状态自动同步（10秒测试间隔）
|
||
│ ├── useRealtime.ts # Realtime单例管理器（引用计数）
|
||
│ ├── useResponsive.ts # 响应式断点检测
|
||
│ ├── useTheme.ts # 主题管理（暗黑模式class策略）
|
||
│ ├── usePerformance.ts # 性能检测（三档动画降级）
|
||
│ ├── useNetworkStatus.ts # 网络状态监听
|
||
│ └── useVirtualScroll.ts # 虚拟滚动
|
||
├── contexts/AuthContext.tsx # 认证上下文（login/register/logout）
|
||
├── styles/index.css # 全局样式（CSS变量+工具类+移动端适配）
|
||
├── supabase/ # Supabase客户端（自动生成，禁止修改）
|
||
├── types/index.ts # 统一类型定义中心（30+接口）
|
||
└── utils/ # 工具函数
|
||
├── constants.ts # 状态映射、动画配置、分页配置
|
||
├── helpers.ts # 日期格式化、数字解析、分组计算
|
||
└── shareCrypto.ts # HMAC-SHA256签名加密
|
||
```
|
||
|
||
## 路由结构
|
||
|
||
| URL 路径 | 组件 | 布局 | 说明 |
|
||
|----------|------|------|------|
|
||
| `/login` | LoginPage | - | 登录页（演示账号+三角色主题色） |
|
||
| `/register` | RegisterPage | - | 企业注册 |
|
||
| `/role-select` | RoleSelectPage | - | 角色选择 |
|
||
| `/purchaser` | PurchaserDashboard | PurchaserLayout | 采购商首页 |
|
||
| `/purchaser/plans` | PlanOverview | PurchaserLayout | 纺织计划总览 |
|
||
| `/purchaser/plans/new` | NewPlan | PurchaserLayout | 新建纺织计划 |
|
||
| `/purchaser/washing-plans/new` | NewWashingPlan | PurchaserLayout | 新建水洗计划 |
|
||
| `/purchaser/warehouse` | WarehouseManage | PurchaserLayout | 产品信息管理 |
|
||
| `/purchaser/finished-warehouse` | FinishedWarehouse | PurchaserLayout | 成品仓库 |
|
||
| `/purchaser/factories` | FactoryManage | PurchaserLayout | 工厂管理 |
|
||
| `/purchaser/accounts-payable` | AccountsPayable | PurchaserLayout | 应付账款 |
|
||
| `/textile` | TextileDashboard | TextileLayout | 纺织厂首页 |
|
||
| `/textile/plans` | TextilePlanOverview | TextileLayout | 接单与生产进度 |
|
||
| `/textile/yarn-warehouse` | YarnWarehouse | TextileLayout | 原料纱仓库 |
|
||
| `/textile/fabric-warehouse` | FabricWarehouse | TextileLayout | 已生产坯布 |
|
||
| `/textile/payments` | PaymentPending | TextileLayout | 待结款 |
|
||
| `/washing` | WashingDashboard | - | 水洗厂首页 |
|
||
| `/washing/plans` | WashingPlanOverview | - | 水洗计划总览 |
|
||
| `/washing/pending` | PendingFabric | - | 待水洗坯布 |
|
||
| `/washing/completed` | CompletedFabric | - | 已完成水洗 |
|
||
| `/washing/finished-warehouse` | FinishedWarehouse | - | 成品仓库 |
|
||
| `/washing/payments` | WashingPaymentPending | - | 待结款 |
|
||
| `/members` | MemberManage | - | 子账号管理 |
|
||
| `/import` | ImportPlanPage | - | 分享链接导入 |
|
||
| `/demo/data-sharing` | DemoDataSharing | - | 数据共享演示 |
|
||
|
||
## 组件说明
|
||
|
||
### InventoryRecordsModal 入库记录弹窗
|
||
统一风格的入库记录详情弹窗，支持采购商和纺织厂页面复用。
|
||
|
||
**特性：**
|
||
- 统计摘要：显示总匹数和总米数
|
||
- 记录列表：按时间倒序显示所有入库记录
|
||
- 详细信息：日期时间、计划编号、工厂名称、批号、匹数、米数
|
||
- 动画效果：Framer Motion 平滑动画
|
||
|
||
**使用示例：**
|
||
```tsx
|
||
import { InventoryRecordsModal } from '../../components/InventoryRecordsModal';
|
||
|
||
<InventoryRecordsModal
|
||
isOpen={recordsModalOpen}
|
||
onClose={() => setRecordsModalOpen(false)}
|
||
records={selectedRecords}
|
||
title="产品名称 - 入库记录"
|
||
/>
|
||
```
|
||
|
||
### OnboardingGuide 新用户引导
|
||
首次进入系统时展示的功能引导动画，支持采购商和纺织厂角色。
|
||
|
||
**特性：**
|
||
- 分步骤功能介绍
|
||
- 支持跳转到对应功能区
|
||
- 进度条和步骤指示器
|
||
- 可跳过引导
|
||
|
||
### DemoDisclaimerModal Demo免责声明
|
||
访问网站时显示的Demo阶段免责声明弹窗。
|
||
|
||
### ComingSoonModal 功能开发中
|
||
点击未开发功能时显示的提示弹窗。
|
||
|
||
## 使用指南
|
||
|
||
### 采购商操作流程
|
||
1. 注册/登录账号，选择"采购商"角色
|
||
2. 创建新计划，填写产品信息、纱线配比
|
||
3. 通过分享链接将计划发送给纺织厂
|
||
4. 实时查看生产进度，管理坯布库存
|
||
5. 生产完成后确认结款
|
||
|
||
### 纺织厂操作流程
|
||
1. 注册/登录账号，选择"纺织厂"角色
|
||
2. 通过分享链接或剪贴板导入计划
|
||
3. 按流程节点确认生产进度
|
||
4. 坯布入库时填写入库数量和匹数
|
||
5. 查看待结款，确认收款
|
||
|
||
### 子账号管理
|
||
- 主账号可创建子账号，分配不同权限
|
||
- 子账号可独立操作，数据归属主账号公司
|
||
- **用户名全局唯一**：子账号用户名不可与其他主账号或子账号重复
|
||
|
||
## 数据安全
|
||
|
||
- 分享链接采用加密传输，不包含敏感信息
|
||
- 导入页面隐藏成品名称、颜色、色号等敏感字段
|
||
- RLS策略确保数据隔离，仅授权用户可访问
|
||
- 虚拟邮箱格式 `{username}@meoo.local` 保护隐私
|
||
|
||
## 浏览器支持
|
||
|
||
- Chrome 90+
|
||
- Safari 14+
|
||
- Firefox 88+
|
||
- Edge 90+
|
||
|
||
## 更新日志
|
||
|
||
### 2026-06-04 (v2.0.0) - 重大版本更新
|
||
- **系统审计与质量保障**
|
||
- 完成四维度系统审计（文件关联/内存安全/路由配置/权限授权），全部通过
|
||
- 新增 Bug 快速排查检查单（12大类90+检查项）
|
||
- 修复数据完整性问题（孤儿记录/状态不一致/过期链接）
|
||
- **文档体系完善**
|
||
- 完善数据库31张表完整文档，按6大模块组织
|
||
- 新增设计架构规范（CSS变量/动效/响应式/布局差异）
|
||
- API 调用示例扩展（Realtime/分享链接加密）
|
||
- **测试体系建设**
|
||
- 新增 E2E 全流程测试 `e2e/full-workflow.spec.ts`
|
||
- 完成端到端业务流程模拟测试并验证数据一致性
|
||
- **代码质量**
|
||
- 项目目录结构更新至最新（33组件/25页面/9 Hooks）
|
||
|
||
### 2025-06-02 (v1.0.36)
|
||
- **水洗厂功能完善**
|
||
- 新增已完成坯布仓库页面，展示水洗完成的坯布库存
|
||
- 新增待水洗坯布页面，展示待水洗的坯布列表
|
||
- 新增水洗厂计划总览页面，统一管理水洗计划
|
||
- 新增水洗厂结款页面，支持查看和确认水洗费用
|
||
- **采购商功能增强**
|
||
- 新增成品仓库页面，管理已完成水洗的成品
|
||
- 新增应付账款页面，查看各工厂的应付费用
|
||
- **组件优化**
|
||
- 新增 YarnAllocationModal 组件，优化纱线分配流程
|
||
- 新增 DemoWatermark 组件，Demo 模式显示水印
|
||
- 新增 PageTransition 组件，统一页面过渡动画
|
||
- 优化 VirtualList 组件，支持大数据列表虚拟滚动
|
||
- **布局优化**
|
||
- 新增 Sidebar 侧边栏组件，统一导航结构
|
||
- 新增 PurchaserLayout 采购商布局组件
|
||
- 统一各角色工作台的布局风格
|
||
|
||
### 2025-06-01 (v1.0.35)
|
||
- **分享链接自动过期机制**
|
||
- 创建 `check_share_links_expired()` 数据库函数，自动更新过期链接状态
|
||
- 完善分享链接流程，符合业务流程图要求
|
||
- 移除 `plan_factories` 表错误唯一约束 `unique_plan_factory_type`
|
||
- **系统逻辑闭环检查**
|
||
- 全面检查采购商与纺织厂关联流程
|
||
- 修复 NewPlan.tsx 子操作错误处理（纱线配比、流程节点、价格历史）
|
||
- 验证系统符合计划分享流程图和计划确认流程图
|
||
|
||
### 2025-05-30 (v1.0.34)
|
||
- **计划创建流程修复**
|
||
- 修复创建计划时自动关联工厂的问题
|
||
- 创建计划时不再自动在 `plan_factories` 表中插入关联记录
|
||
- 工厂关联改为通过分享链接或推送功能，由工厂确认后才建立
|
||
- 删除 `auto_sync_plan_trigger` 触发器，避免自动关联历史工厂
|
||
- **Bug修复**
|
||
- 修复 `factory_type` 枚举类型错误（`'textile' as FactoryType`）
|
||
- 修复触发器函数 `auto_sync_plan_to_factory()` 中变量类型声明（`TEXT` → `factory_type`）
|
||
|
||
### 2025-05-30 (v1.0.33)
|
||
- **采购商移动端UI重构**
|
||
- 移动端界面风格与纺织厂保持一致，采用卡片式布局
|
||
- 统计卡片改为3列紧凑布局，与纺织厂一致
|
||
- 最近计划支持左右滑动展示，带滑动按钮和指示器
|
||
- 快捷操作区域显示6个功能按钮（3列布局）：新建纺织计划、新建水洗计划、产品信息、水洗仓库、工厂管理、应付账款
|
||
- 背景使用渐变风格（amber-50/orange-50）
|
||
- **页面切换优化**
|
||
- 添加数据缓存机制（dataLoaded状态），避免重复加载
|
||
- 从其他页面返回时保持原有数据，不显示加载动画，页面瞬间呈现
|
||
- 添加页面可见性监听（visibilitychange），后台返回前台时自动刷新数据
|
||
- **Bug修复**
|
||
- 修复快捷操作路由路径错误（应付账款、水洗仓库）
|
||
- 修复CreditCard图标未导入导致的运行时错误
|
||
|
||
### 2025-05-30 (v1.0.32)
|
||
- **分享链接流程重构**
|
||
- 新增 `company_relationships` 表记录采购商与工厂的合作关系
|
||
- 重构分享逻辑：已有合作关系直接推送，无合作关系生成30分钟有效期的分享链接
|
||
- 新增链接状态追踪：pending → clicked → confirmed/rejected/expired/cancelled
|
||
- 工厂可确认或拒绝计划，拒绝时可填写原因反馈给采购商
|
||
- 确认后自动建立合作关系，后续计划可直接推送
|
||
- 链接30分钟过期自动失效，可重新生成
|
||
- **数据库 RLS 策略修复**
|
||
- 修复 `yarn_ratios` INSERT 策略缺失 WITH CHECK 条件导致 403 错误
|
||
- 简化 `share_links` SELECT 策略，避免复杂查询导致 500 错误
|
||
- 添加 `companies` DELETE 策略，支持删除工厂信息
|
||
- **Bug 修复**
|
||
- 修复 `usePlanData` Hook 依赖项导致无限循环、页面卡加载问题
|
||
- 修复删除工厂时未清理 `company_relationships` 关联导致外键约束错误
|
||
- 修复 `ShareModal` 和 `ImportPlanPage` Date 构造类型错误
|
||
- 修复计划总览 factories 查询逻辑，显示所有工厂而非仅有关联的
|
||
- **计划状态同步修复**：创建 `usePlanStatusSync` Hook，每5分钟自动检查并修复计划状态不一致问题
|
||
- **分享链接导入修复**：修复导入成功后未更新 `production_plans.status` 为 `producing` 的问题
|
||
- **采购商界面优化**：计划卡片显示关联纺织厂公司名称，便于二次确认
|
||
- **水洗计划数据加载修复**：修复 RLS 策略冲突导致产品库存数据无法加载的问题
|
||
- **入库记录产品信息显示修复**：修复 `useInventoryData` 返回数据缺少产品信息导致"未知产品"显示问题
|
||
- **UI 优化**
|
||
- 采购商 Dashboard "新建水洗"更名为"新建水洗计划"
|
||
- 工厂管理添加删除功能，支持删除无关联计划的工厂
|
||
|
||
### 2025-05-28 (v1.0.31)
|
||
- **动画性能优化**
|
||
- 创建 `usePerformance` Hook，自动检测设备性能级别
|
||
- 支持三种性能模式：高性能/中等性能/低性能
|
||
- 自动检测系统减少动画偏好设置
|
||
- 简化页面过渡动画，仅使用 opacity 变化
|
||
- 优化 Dashboard 页面，使用 CSS transition 替代复杂动画
|
||
- 添加 CSS 硬件加速优化（GPU加速、内容可见性）
|
||
- 支持低配置电脑流畅运行
|
||
- **分享链接安全修复**
|
||
- 统一加密/解密为带 HMAC-SHA256 签名的异步版本，消除同步版本无签名验证的安全隐患
|
||
- `decryptShareParams` 返回类型扩展，补回之前丢失的 `hideSensitive` 字段
|
||
- `ShareModal` 长链接 token 改为异步生成，确保签名完整性
|
||
- `ImportPlanPage` 长链接解析改为异步解密，启用签名验证
|
||
- **短链 hideSensitive 同步修复**
|
||
- 用户切换"隐藏成品信息"开关后，短链对应的 `hide_sensitive` 值实时同步到数据库
|
||
- 纺织厂通过短链导入时，敏感信息显示状态与采购商当前设置一致
|
||
- **已知未修复问题**
|
||
- `production_plans` SELECT RLS 策略过于宽松：任何登录用户可通过 `plan_factories` 存在关联这一条件查看计划详情，存在数据泄露风险
|
||
- **导入流程修复**
|
||
- 导入成功后跳转到计划总览而非 Dashboard，确保用户能立即看到导入的计划
|
||
- 纺织厂计划总览添加 `plan_factories` Realtime 订阅，导入新计划后自动刷新
|
||
- **分享链接失效机制**
|
||
- `share_links` 表新增 `used_at` 字段，导入成功后标记短链为已使用
|
||
- 解析短链时检查 `used_at`，已使用的链接显示"链接已失效"提示
|
||
- 防止同一分享链接被重复导入
|
||
|
||
### 2025-05-28 (v1.0.3)
|
||
- **原料纱仓库出入库记录功能**
|
||
- 创建 `yarn_stock_records` 表，记录原料纱出入库历史
|
||
- 采纱环节自动记录出库，关联到对应生产计划
|
||
- 原料纱入库时自动记录入库
|
||
- 原料纱仓库页面新增"出入库记录"标签页
|
||
- 显示出入库类型、数量、关联计划、时间等信息
|
||
- **采纱环节优化**
|
||
- 添加自动/手动分配模式切换
|
||
- 自动匹配失败时提示切换到手动分配
|
||
- 手动模式支持输入实际使用纱线名称和重量
|
||
- 确认时显示实际消耗统计（各纱线用量+总计）
|
||
- 库存不足时强制阻止确认，必须先补充库存
|
||
- **Bug 修复**
|
||
- 修复纱线占比显示为10000%的问题
|
||
|
||
### 2025-05-27 (v1.0.2)
|
||
- **账号管理页面帮助系统集成**
|
||
- 新增"帮助与支持"卡片区域，集成用户手册、用户反馈、关于窗口
|
||
- 用户手册：详细使用指南，支持搜索功能
|
||
- 用户反馈：支持提交问题或建议到数据库
|
||
- 关于窗口：显示版本号 v1.0.2、版权信息、技术支持联系方式
|
||
- **帮助系统组件完善**
|
||
- 内置帮助中心（F1快捷键）：功能介绍、常见操作步骤、快捷键列表
|
||
- 新手指引：首次登录自动弹窗，引导完成关键设置
|
||
- 工具提示：所有按钮悬停显示功能说明
|
||
- 版本更新检查：自动检测新版本，仅弹窗一次
|
||
- 崩溃报告系统：全局错误监听，自动收集错误日志
|
||
- **通知中心主题色适配**
|
||
- 采购商工作台：琥珀色主题（bg-amber-100/text-amber-700）
|
||
- 纺织厂工作台：翠绿色主题（bg-emerald-100/text-emerald-700）
|
||
- 水洗厂工作台：紫色主题（bg-purple-100/text-purple-700）
|
||
- **计划拒绝功能优化**
|
||
- 使用 localStorage 持久化拒绝状态，跨页面保持同步
|
||
- 被拒绝的计划显示灰色卡片和"已拒绝"标签
|
||
- 被拒绝的计划自动从 Dashboard "最近计划"中移除
|
||
- 每个被拒绝的计划弹窗仅显示一次
|
||
|
||
### 2025-05-26
|
||
- **计划详情字段完善**
|
||
- 采购商和纺织厂计划总览页面统一显示所有技术字段
|
||
- 新增显示字段：克重、经线克重、纬线克重、总克重、生产采购价、产品图片、纱线配比、每米纱用量
|
||
- 新增时间字段：创建时间、计划开始时间
|
||
- 新增备注字段显示
|
||
- 纺织厂页面隐藏敏感信息（成品名称、颜色、色号）以保护采购商数据
|
||
- **移动端 UI 优化**
|
||
- 计划卡片移动端适配：缩小图片尺寸（64x64）、字体调整为 text-xs
|
||
- 字段标签简化（如"计划编号:"→"编号:"）
|
||
- 网格布局优化，避免内容溢出
|
||
- 所有工作台退出按钮在移动端变为图标形式（LogOut图标）
|
||
- **拒绝计划功能增强**
|
||
- 纺织厂拒绝计划后立即显示灰色卡片和"已拒绝"标签
|
||
- 被拒绝的计划自动折叠
|
||
- 被拒绝的计划从 Dashboard "最近计划"中消失
|
||
- 使用 localStorage 持久化拒绝状态，跨页面保持同步
|
||
|
||
### 2025-05-25
|
||
- **产品图片上传功能**
|
||
- 为采购商产品信息管理添加图片上传功能
|
||
- 支持在产品创建和编辑时上传产品图片（JPG、PNG格式，最大5MB）
|
||
- 产品列表展示40x40px缩略图，无图片时显示默认占位图标
|
||
- 产品表单支持图片预览、重新上传和删除功能
|
||
- 使用 Supabase Storage `product_images` 存储桶存储图片
|
||
- 数据库 `products` 表新增 `image_url` 字段
|
||
- **UI 优化**
|
||
- 纺织厂工作台"原坯布仓库"更名为"已生产坯布"（页面标题和首页快捷操作）
|
||
|
||
### 2025-05-24
|
||
- **新增出入库历史功能**
|
||
- 采购商产品信息列表新增"出入库历史"按钮
|
||
- 支持查看每个产品的完整库存变动记录（批号、匹数、米数、时间）
|
||
- 桌面端和移动端均支持
|
||
- **类型系统优化**
|
||
- 修复 `ProductInRecord` 类型定义，与数据库表结构保持一致
|
||
- 区分数据库必需字段和前端展示扩展字段
|
||
- **新增组件**
|
||
- `OutboundForm.tsx` - 出库表单组件
|
||
- `PlanEditModal.tsx` - 计划编辑弹窗
|
||
- `NotificationCenter.tsx` - 通知中心
|
||
- `NetworkStatusBar.tsx` - 网络状态栏
|
||
- `VirtualList.tsx` - 虚拟列表组件
|
||
- `ErrorBoundary.tsx` - 错误边界组件
|
||
|
||
### 2025-05-23
|
||
- 优化纺织厂工作台UI动画流畅度
|
||
- 全面适配移动端，优化触控体验
|
||
- 添加实时数据订阅，入库记录自动更新
|
||
- 优化坯布入库输入框布局
|
||
- 修复采购商仓库管理数据同步问题
|
||
- 创建统一的入库记录弹窗组件 `InventoryRecordsModal`
|
||
|
||
### 2025-05-22
|
||
- 项目初始化
|
||
- 完成基础架构搭建
|
||
- 实现用户认证系统
|
||
- 完成数据库设计和迁移
|
||
|
||
## 测试
|
||
|
||
### 类型检查
|
||
```bash
|
||
pnpm run typecheck
|
||
```
|
||
|
||
### 代码规范
|
||
```bash
|
||
pnpm run lint
|
||
```
|
||
|
||
### 构建验证
|
||
```bash
|
||
pnpm run build
|
||
```
|
||
|
||
## CI/CD 配置
|
||
|
||
项目使用 GitHub Actions 进行持续集成和部署：
|
||
|
||
### 工作流配置
|
||
```yaml
|
||
# .github/workflows/ci.yml
|
||
name: CI
|
||
|
||
on:
|
||
push:
|
||
branches: [main, develop]
|
||
pull_request:
|
||
branches: [main]
|
||
|
||
jobs:
|
||
build:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
- uses: pnpm/action-setup@v2
|
||
with:
|
||
version: 8
|
||
- uses: actions/setup-node@v3
|
||
with:
|
||
node-version: 18
|
||
cache: 'pnpm'
|
||
- run: pnpm install
|
||
- run: pnpm run typecheck
|
||
- run: pnpm run lint
|
||
- run: pnpm run build
|
||
```
|
||
|
||
## 环境变量配置
|
||
|
||
项目使用以下环境变量：
|
||
|
||
### 开发环境 (.env.local)
|
||
```env
|
||
# Supabase 配置
|
||
VITE_SUPABASE_URL=https://your-project.supabase.co
|
||
VITE_SUPABASE_ANON_KEY=your-anon-key
|
||
|
||
# 应用配置
|
||
VITE_APP_NAME=昱森（Demo版）
|
||
VITE_APP_VERSION=2.0.0
|
||
```
|
||
|
||
### 生产环境
|
||
生产环境变量通过 CI/CD 流水线注入，请勿在代码中硬编码敏感信息。
|
||
|
||
## 数据库架构（2026-06-04 更新）
|
||
|
||
### 概览
|
||
|
||
共 **31张业务表**，按功能分为6大模块：
|
||
|
||
| 模块 | 表数量 | 核心表 |
|
||
|------|--------|--------|
|
||
| 用户与权限 | 4 | companies, profiles, company_members, company_relationships |
|
||
| 生产计划 | 5 | production_plans, plan_factories, yarn_ratios, plan_process_steps, washing_plans |
|
||
| 库存管理 | 8 | products, warehouses, inventory_records, product_inventory_records, yarn_stock, yarn_stock_records, finished_products, finished_product_inventory_records |
|
||
| 财务结算 | 5 | payments, accounts_payable, accounts_payable_items, production_price_history, product_price_history |
|
||
| 分享与协作 | 2 | share_links, notifications |
|
||
| 系统辅助 | 7 | audit_logs, user_feedback, crash_reports, product_yarn_ratios, product_outbound_records, washing_plan_completions, washing_process_steps |
|
||
|
||
### 核心表结构
|
||
|
||
**companies** - 公司表
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | UUID PK | gen_random_uuid() |
|
||
| name | TEXT NOT NULL | 公司名称 |
|
||
| role | app_role NOT NULL | purchaser/textile/washing |
|
||
| address / contact_phone | TEXT | 地址/电话 |
|
||
| created_at | TIMESTAMPTZ | now() |
|
||
|
||
**profiles** - 用户配置表
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | UUID PK | 关联 auth.users.id |
|
||
| username | TEXT UNIQUE | 用户名 |
|
||
| company_id | UUID FK | 所属公司 |
|
||
| is_master | BOOLEAN | 是否主账号 |
|
||
| master_id | UUID FK | 主账号ID（子账号） |
|
||
| display_name / image_url | TEXT | 显示名/头像 |
|
||
|
||
**production_plans** - 生产计划表
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | UUID PK | gen_random_uuid() |
|
||
| plan_code | TEXT UNIQUE | 计划编号 |
|
||
| product_name / color / fabric_code / color_code | TEXT | 产品信息 |
|
||
| purchaser_id | UUID FK | 采购商公司ID |
|
||
| target_quantity / completed_quantity | INTEGER | 计划/完成产量(米) |
|
||
| yarn_usage_per_meter / production_price | NUMERIC | 纱用量/单价 |
|
||
| status | plan_status | pending/producing/completed |
|
||
|
||
**products** - 产品信息表
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | UUID PK | gen_random_uuid() |
|
||
| company_id | UUID FK | 所属公司 |
|
||
| product_name / color / fabric_code / color_code | TEXT | 产品标识 |
|
||
| weight / warp_weight / weft_weight / total_weight | NUMERIC | 克重信息 |
|
||
| yarn_types (TEXT[]) / yarn_ratios (NUMERIC[]) | ARRAY | 纱线配置 |
|
||
| production_price / image_url | NUMERIC/TEXT | 价格/图片 |
|
||
|
||
**washing_plans** - 水洗计划表
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | UUID PK | gen_random_uuid() |
|
||
| company_id / product_id / washing_factory_id | UUID FK | 关联ID |
|
||
| planned_meters / washing_price | NUMERIC | 计划米数/单价 |
|
||
| estimated_shrinkage_rate / actual_shrinkage_rate | NUMERIC | 缩水率 |
|
||
| status | TEXT | pending/in_progress/completed |
|
||
|
||
**share_links** - 分享链接表
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| short_code | TEXT | 短码 |
|
||
| plan_id | UUID FK | 计划ID |
|
||
| factory_type | TEXT | textile/washing |
|
||
| hide_sensitive | BOOLEAN | 隐藏敏感信息 |
|
||
| used_at | TIMESTAMPTZ | 使用时间 |
|
||
| status | TEXT | pending/clicked/confirmed/rejected/expired/cancelled |
|
||
|
||
> 完整31张表的详细字段定义请参阅 `AGENTS.md` 数据架构章节。
|
||
|
||
### 枚举类型
|
||
|
||
```sql
|
||
app_role: purchaser | textile | washing
|
||
factory_type: textile | washing
|
||
plan_status: pending | producing | completed
|
||
step_type: confirm | yarn_purchase | dyeing | machine_start | fabric_warehouse
|
||
step_status: pending | active | completed | rejected
|
||
warehouse_type: raw_fabric | fabric | finished | yarn
|
||
payment_status: pending | completed
|
||
```
|
||
|
||
### RLS 策略
|
||
|
||
所有表启用 Row Level Security，基于 `company_id` + `get_user_master_company_id()` 进行数据隔离：
|
||
|
||
```sql
|
||
-- 示例：production_plans 表 RLS 策略
|
||
CREATE POLICY company_select_plans ON production_plans
|
||
FOR SELECT USING (purchaser_id = get_user_master_company_id());
|
||
|
||
CREATE POLICY company_insert_plans ON production_plans
|
||
FOR INSERT WITH CHECK (purchaser_id = get_user_master_company_id());
|
||
```
|
||
|
||
### API 调用示例
|
||
|
||
**查询计划列表**
|
||
```typescript
|
||
const { data } = await supabase
|
||
.from('production_plans')
|
||
.select('*')
|
||
.eq('purchaser_id', companyId)
|
||
.order('created_at', { ascending: false });
|
||
```
|
||
|
||
**创建入库记录**
|
||
```typescript
|
||
await supabase.from('inventory_records').insert({
|
||
plan_id: planId,
|
||
warehouse_id: warehouseId,
|
||
quantity: quantity,
|
||
rolls: rolls,
|
||
company_id: companyId,
|
||
operator_id: userId
|
||
});
|
||
```
|
||
|
||
**实时订阅库存更新**
|
||
```typescript
|
||
// 使用单例管理器（推荐）
|
||
import { useInventoryRealtime } from '../hooks/useRealtime';
|
||
useInventoryRealtime(companyId, onDataChange);
|
||
|
||
// 或直接订阅
|
||
supabase
|
||
.channel('inventory_changes')
|
||
.on('postgres_changes', {
|
||
event: '*', schema: 'public', table: 'inventory_records'
|
||
}, callback)
|
||
.subscribe();
|
||
```
|
||
|
||
**分享链接加密**
|
||
```typescript
|
||
import { encryptShareParams, decryptShareParams } from '../utils/shareCrypto';
|
||
|
||
// 生成加密链接（HMAC-SHA256签名）
|
||
const token = await encryptShareParams(planId, factoryType, hideSensitive);
|
||
|
||
// 解密验证
|
||
const result = await decryptShareParams(token);
|
||
// result: { planId, factoryType, hideSensitive } | null
|
||
```
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 技术支持
|
||
|
||
如有问题或建议，请联系开发团队。
|
||
|
||
---
|
||
|
||
## 常见问题与解决方案
|
||
|
||
### Q1: 页面白屏/无法加载
|
||
**可能原因**：
|
||
- Webpack 热更新失败
|
||
- 类型检查错误阻止构建
|
||
- 环境变量配置错误
|
||
|
||
**解决方案**：
|
||
```bash
|
||
# 1. 清除缓存重新构建
|
||
rm -rf node_modules dist
|
||
pnpm install
|
||
pnpm run dev
|
||
|
||
# 2. 检查类型错误
|
||
pnpm run typecheck
|
||
|
||
# 3. 检查环境变量
|
||
cat .env.local
|
||
```
|
||
|
||
### Q2: 数据无法保存/读取
|
||
**可能原因**：
|
||
- RLS 策略限制
|
||
- 网络连接问题
|
||
- 权限不足
|
||
|
||
**解决方案**：
|
||
```bash
|
||
# 1. 检查云服务状态
|
||
meoo-cli cloud status
|
||
|
||
# 2. 检查 RLS 策略
|
||
meoo-cli cloud query --sql "\dt"
|
||
meoo-cli cloud query --sql "SELECT * FROM pg_policies WHERE tablename = 'your_table'"
|
||
|
||
# 3. 检查用户权限
|
||
meoo-cli cloud query --sql "SELECT * FROM profiles WHERE id = 'your-user-id'"
|
||
```
|
||
|
||
### Q3: 移动端样式错乱
|
||
**可能原因**：
|
||
- Tailwind 配置问题
|
||
- 响应式断点使用错误
|
||
- CSS 未正确加载
|
||
|
||
**解决方案**：
|
||
```bash
|
||
# 1. 检查 Tailwind 配置
|
||
cat tailwind.config.js
|
||
|
||
# 2. 检查 PostCSS 配置
|
||
cat postcss.config.js
|
||
|
||
# 3. 重新构建样式
|
||
pnpm run build
|
||
```
|
||
|
||
### Q4: 实时数据不更新
|
||
**可能原因**：
|
||
- Realtime 未启用
|
||
- 订阅配置错误
|
||
- 网络问题
|
||
|
||
**解决方案**：
|
||
```typescript
|
||
// 检查订阅是否正确设置
|
||
const channel = supabase
|
||
.channel('table_changes')
|
||
.on('postgres_changes', {
|
||
event: '*',
|
||
schema: 'public',
|
||
table: 'your_table'
|
||
}, (payload) => {
|
||
console.log('Change received:', payload);
|
||
})
|
||
.subscribe((status) => {
|
||
console.log('Subscription status:', status);
|
||
});
|
||
```
|
||
|
||
### Q5: 开发服务器预览加载失败（沙箱环境）
|
||
**现象**：
|
||
- `pnpm run dev` 启动正常，端口 3015 在监听
|
||
- 但浏览器预览无法加载，curl 请求超时
|
||
|
||
**根本原因**：
|
||
- 沙箱环境网络限制：`net.ipv4.conf.all.forwarding = 0`
|
||
- Webpack devServer 配置不当：`host: '127.0.0.1'` 无法在沙箱访问
|
||
|
||
**解决方案**：
|
||
```javascript
|
||
// webpack.config.js - 正确配置
|
||
devServer: {
|
||
port: 3015,
|
||
host: '0.0.0.0', // 必须使用 0.0.0.0
|
||
allowedHosts: 'all',
|
||
hot: true,
|
||
historyApiFallback: true,
|
||
// 不要配置 static 和 devMiddleware
|
||
}
|
||
```
|
||
|
||
**验证方法**：
|
||
```bash
|
||
# 1. 类型检查
|
||
pnpm run typecheck
|
||
|
||
# 2. 构建验证（关键）
|
||
pnpm run build
|
||
|
||
# 3. 检查产物
|
||
ls -la dist/
|
||
|
||
# 4. 启动服务器（沙箱中预览可能受限，但构建成功即可部署）
|
||
pnpm run dev
|
||
```
|
||
|
||
**注意**：沙箱环境中 curl 可能仍超时，这不影响实际部署。只要 `pnpm run build` 成功，应用即可正常发布。
|
||
|
||
---
|
||
|
||
## 性能优化建议
|
||
|
||
### 1. 图片优化
|
||
- 使用 WebP 格式
|
||
- 实现懒加载
|
||
- 使用 CDN 加速
|
||
|
||
### 2. 代码分割
|
||
```typescript
|
||
// 使用 React.lazy 进行代码分割
|
||
const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
|
||
|
||
function App() {
|
||
return (
|
||
<Suspense fallback={<Loading />}>
|
||
<HeavyComponent />
|
||
</Suspense>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 3. 数据缓存
|
||
```typescript
|
||
// 使用 SWR 或 React Query 进行数据缓存
|
||
import useSWR from 'swr';
|
||
|
||
const { data, error } = useSWR('/api/data', fetcher, {
|
||
revalidateOnFocus: false,
|
||
dedupingInterval: 5000
|
||
});
|
||
```
|
||
|
||
### 4. 虚拟列表
|
||
对于大数据列表，使用虚拟列表组件避免渲染过多 DOM 节点。
|
||
|
||
---
|
||
|
||
## 安全最佳实践
|
||
|
||
### 1. 输入验证
|
||
```typescript
|
||
// 始终验证用户输入
|
||
const validateInput = (input: string): boolean => {
|
||
// 防止 XSS
|
||
const xssPattern = /<script|javascript:|onerror=/i;
|
||
if (xssPattern.test(input)) return false;
|
||
|
||
// 防止 SQL 注入（虽然 Supabase 已防护）
|
||
const sqlPattern = /(\b(SELECT|INSERT|UPDATE|DELETE|DROP|CREATE)\b)/i;
|
||
if (sqlPattern.test(input)) return false;
|
||
|
||
return true;
|
||
};
|
||
```
|
||
|
||
### 2. 敏感数据处理
|
||
```typescript
|
||
// 不要在客户端暴露敏感信息
|
||
// ❌ 错误
|
||
const apiKey = 'sk-live-xxx';
|
||
|
||
// ✅ 正确 - 使用环境变量
|
||
const apiKey = process.env.VITE_API_KEY;
|
||
```
|
||
|
||
### 3. 认证检查
|
||
```typescript
|
||
// 每个需要认证的页面都添加检查
|
||
useEffect(() => {
|
||
const checkAuth = async () => {
|
||
const { data: { user } } = await supabase.auth.getUser();
|
||
if (!user) {
|
||
navigate('/login');
|
||
}
|
||
};
|
||
checkAuth();
|
||
}, []);
|
||
```
|
||
|
||
---
|
||
|
||
## 贡献指南
|
||
|
||
### 提交代码
|
||
1. Fork 项目
|
||
2. 创建功能分支 (`git checkout -b feature/xxx`)
|
||
3. 提交更改 (`git commit -m 'Add xxx'`)
|
||
4. 推送到分支 (`git push origin feature/xxx`)
|
||
5. 创建 Pull Request
|
||
|
||
### 代码规范
|
||
- 使用 TypeScript 严格模式
|
||
- 遵循 ESLint 规则
|
||
- 编写单元测试
|
||
- 更新相关文档
|
||
|
||
### 提交信息规范
|
||
```
|
||
feat: 新增功能
|
||
fix: 修复 bug
|
||
docs: 文档更新
|
||
style: 代码格式调整
|
||
refactor: 重构代码
|
||
test: 测试相关
|
||
chore: 构建/工具相关
|
||
```
|