纺织行业采购计划管理系统

一款专为纺织行业设计的全流程协作管理平台，连接采购商（布行）、纺织厂、水洗厂三方，实现从计划制定到成品交付的数字化管理。

核心功能

多角色协作

• 采购商/布行：创建生产计划、管理坯布库存、跟踪生产进度、处理结款
• 纺织厂：接收生产计划、管理生产流程、坯布入库、纱线库存管理
• 水洗厂：接收水洗订单、管理水洗流程

计划管理

• 自动生成唯一计划编号和坯布识别码
• 纱线配比配置与用量自动计算
• 生产流程节点跟踪（确认计划 → 采纱 → 染纱 → 上机 → 坯布入库）
• 实时进度可视化，支持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+

安装依赖

pnpm install

开发模式

pnpm run dev

服务启动在 http://localhost:3015

构建生产版本

pnpm run build

数据库迁移

# 查看云服务状态
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 平滑动画

使用示例：

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

• 项目初始化
• 完成基础架构搭建
• 实现用户认证系统
• 完成数据库设计和迁移

测试

类型检查

pnpm run typecheck

代码规范

pnpm run lint

构建验证

pnpm run build

CI/CD 配置

项目使用 GitHub Actions 进行持续集成和部署：

工作流配置

# .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)

# 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 数据架构章节。

枚举类型

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() 进行数据隔离：

-- 示例：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 调用示例

查询计划列表

const { data } = await supabase
  .from('production_plans')
  .select('*')
  .eq('purchaser_id', companyId)
  .order('created_at', { ascending: false });

创建入库记录

await supabase.from('inventory_records').insert({
  plan_id: planId,
  warehouse_id: warehouseId,
  quantity: quantity,
  rolls: rolls,
  company_id: companyId,
  operator_id: userId
});

实时订阅库存更新

// 使用单例管理器（推荐）
import { useInventoryRealtime } from '../hooks/useRealtime';
useInventoryRealtime(companyId, onDataChange);

// 或直接订阅
supabase
  .channel('inventory_changes')
  .on('postgres_changes', {
    event: '*', schema: 'public', table: 'inventory_records'
  }, callback)
  .subscribe();

分享链接加密

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 热更新失败
• 类型检查错误阻止构建
• 环境变量配置错误

解决方案：

# 1. 清除缓存重新构建
rm -rf node_modules dist
pnpm install
pnpm run dev

# 2. 检查类型错误
pnpm run typecheck

# 3. 检查环境变量
cat .env.local

Q2: 数据无法保存/读取

可能原因：

• RLS 策略限制
• 网络连接问题
• 权限不足

解决方案：

# 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 未正确加载

解决方案：

# 1. 检查 Tailwind 配置
cat tailwind.config.js

# 2. 检查 PostCSS 配置
cat postcss.config.js

# 3. 重新构建样式
pnpm run build

Q4: 实时数据不更新

可能原因：

• Realtime 未启用
• 订阅配置错误
• 网络问题

解决方案：

// 检查订阅是否正确设置
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' 无法在沙箱访问

解决方案：

// webpack.config.js - 正确配置
devServer: {
  port: 3015,
  host: '0.0.0.0',  // 必须使用 0.0.0.0
  allowedHosts: 'all',
  hot: true,
  historyApiFallback: true,
  // 不要配置 static 和 devMiddleware
}

验证方法：

# 1. 类型检查
pnpm run typecheck

# 2. 构建验证（关键）
pnpm run build

# 3. 检查产物
ls -la dist/

# 4. 启动服务器（沙箱中预览可能受限，但构建成功即可部署）
pnpm run dev

注意：沙箱环境中 curl 可能仍超时，这不影响实际部署。只要 pnpm run build 成功，应用即可正常发布。

---

性能优化建议

1. 图片优化

• 使用 WebP 格式
• 实现懒加载
• 使用 CDN 加速

2. 代码分割

// 使用 React.lazy 进行代码分割
const HeavyComponent = React.lazy(() => import('./HeavyComponent'));

function App() {
  return (
    <Suspense fallback={<Loading />}>
      <HeavyComponent />
    </Suspense>
  );
}

3. 数据缓存

// 使用 SWR 或 React Query 进行数据缓存
import useSWR from 'swr';

const { data, error } = useSWR('/api/data', fetcher, {
  revalidateOnFocus: false,
  dedupingInterval: 5000
});

4. 虚拟列表

对于大数据列表，使用虚拟列表组件避免渲染过多 DOM 节点。

---

安全最佳实践

1. 输入验证

// 始终验证用户输入
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. 敏感数据处理

// 不要在客户端暴露敏感信息
// ❌ 错误
const apiKey = 'sk-live-xxx';

// ✅ 正确 - 使用环境变量
const apiKey = process.env.VITE_API_KEY;

3. 认证检查

// 每个需要认证的页面都添加检查
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: 构建/工具相关