# 故事 011.006：视频与系统管理功能实现

## 状态
Ready for Review

## 故事
**作为**企业用户，
**我希望**管理企业相关的视频资料和查看企业基本信息，
**以便**进行资料归档和账户管理。

## 验收标准

1. [ ] 视频查看下载页功能完整，支持企业维度和个人维度的视频查看和下载（只读功能）
2. [ ] 视频支持播放、下载、分享、批量下载功能（均为只读查看功能）
3. [ ] 企业设置页面基础功能可用（企业信息展示，只读查看）
4. [ ] 账号管理、安全设置等高级功能标记为"后期优化"（因系统设置API延期，且写操作在管理后台执行）
5. [ ] 页面设计符合原型标准，与系统其他部分无缝集成

**重要说明**：用人方小程序仅用于查看（只读），所有管理操作（编辑、上传、删除、状态变更等）都由管理员在管理后台执行。小程序仅提供数据展示、播放、下载、分享等只读功能。

## 任务 / 子任务

**注意：用人方小程序仅用于查看（只读），所有写操作（编辑、上传、删除等）都在管理后台执行**

- [ ] 任务1：实现视频查看下载页面（AC：1）
  - [ ] 创建视频管理页面组件，使用基础布局组件
  - [ ] 集成视频管理API（史诗012提供，企业专用版本）
  - [ ] 实现视频列表展示（缩略图、标题、类型、大小、上传时间等）- 只读展示
  - [ ] 支持企业维度和个人维度的视频筛选 - 只读筛选功能
  - [ ] 添加视频分类和标签功能 - 只读展示
  - [ ] **不实现视频上传功能**（在管理后台执行）
- [ ] 任务2：实现视频操作功能（AC：2）
  - [ ] 实现视频播放功能（内置播放器或调用系统播放器）- 只读播放
  - [ ] 实现视频下载功能（单个下载）- 只读下载
  - [ ] 实现视频分享功能（生成分享链接）- 只读分享
  - [ ] 实现批量视频选择和多选下载 - 只读批量下载
  - [ ] 添加视频搜索和筛选功能 - 只读搜索筛选
  - [ ] **不实现视频删除、编辑、状态更新功能**（在管理后台执行）
- [ ] 任务3：实现企业设置页面基础功能（AC：3,4）
  - [ ] 创建企业设置页面组件
  - [ ] 集成企业管理API（company模块）获取企业信息
  - [ ] 展示企业基本信息（公司名称、统一社会信用代码、联系人、电话等）- 只读展示
  - [ ] **不实现企业信息编辑功能**（在管理后台执行）
  - [ ] 添加"账号管理"、"安全设置"等功能的占位界面，标注"后期优化"（因API延期且写操作在管理后台执行）
- [ ] 任务4：优化视频管理用户体验（AC：5）
  - [ ] 参考原型设计：`docs/小程序原型/yongren.html`中的视频管理页面
  - [ ] 实现视频缩略图生成和缓存（服务端生成，客户端只读展示）
  - [ ] 优化大视频文件的加载和播放体验
  - [ ] **不添加视频上传进度显示**（上传功能在管理后台执行）
  - [ ] 确保移动端视频播放兼容性
- [ ] 任务5：处理系统设置API延期（AC：4）
  - [ ] 识别受系统设置API延期影响的功能
  - [ ] 实现降级方案（如本地配置、默认值）
  - [ ] 添加功能不可用的友好提示
  - [ ] 标记延期功能为"后期优化"状态
- [ ] 任务6：集成Navbar导航栏组件（页面层级结构规范）
  - [ ] 视频管理页：集成Navbar组件，标题"视频管理"，隐藏左侧返回按钮（主页面配置）
    - 导入Navbar组件：`import { Navbar } from '@d8d/mini-shared-ui-components/components/navbar'`
    - 配置navbar：`title="视频管理"`，`leftIcon=""`，`leftText=""`
    - 保持YongrenTabBarLayout包裹，`activeTab="settings"`（视频管理在企业设置页面内）
    - 调整ScrollView布局：`px-4 pb-4 pt-0`（移除顶部内边距适配navbar占位）
  - [ ] 企业设置页：集成Navbar组件，标题"企业设置"，隐藏左侧返回按钮（主页面配置）
    - 导入Navbar组件，配置：`title="企业设置"`，`leftIcon=""`，`leftText=""`
    - 保持YongrenTabBarLayout包裹，`activeTab="settings"`
    - 调整ScrollView布局：`px-4 pb-4 pt-0`（移除顶部内边距适配navbar占位）
  - [ ] 统一页面层级结构：主页面使用YongrenTabBarLayout+Navbar（无返回）
  - [ ] 验证类型检查：确保所有页面类型检查通过
- [ ] 任务7：编写集成测试
  - [ ] 编写视频管理功能测试（只读查看功能测试）
  - [ ] 测试批量下载功能（只读下载测试）
  - [ ] 测试企业信息展示功能（只读展示测试）
  - [ ] 验证延期功能的处理方式
  - [ ] **不测试视频上传、删除、编辑功能**（在管理后台测试）
  - [ ] **不测试企业信息编辑功能**（在管理后台测试）

## 开发笔记

### 依赖关系
**依赖故事**：
- ✅ **011.001（基础框架搭建）**：已完成，提供以下已就绪的基础设施：
  - **API客户端架构**：mini-ui-packages架构，API客户端在各UI包内创建
  - **路由配置**：用人方小程序页面路由已配置，包括视频管理和企业设置页面
  - **基础布局组件**：`YongrenTabBarLayout`、`Navbar`、`PageContainer`
  - **企业用户认证框架**：`EnterpriseAuthProvider`、`useEnterpriseAuth`钩子
- ✅ **011.002（认证与首页）**：已完成，提供以下已就绪的功能：
  - **认证状态管理**：自动token刷新、登录状态检查中间件
  - **Navbar组件集成规范**：主页面使用YongrenTabBarLayout+Navbar（无返回按钮）
- ✅ **011.004（订单管理）**：已完成，提供以下已就绪的功能：
  - **视频管理API集成经验**：订单管理页面已实现视频统计和批量下载功能
  - **企业专用视频API客户端**：`enterpriseOrderClient['company-videos']`、`['batch-download']`等路由已可用
  - **Navbar集成和页面结构规范**：主页面和二级页面的导航栏集成模式
- ⚠️ **史诗012系统设置API**：延期（P2优先级），需要降级处理方案

**API依赖状态**：
- ✅ **企业专用视频管理API**：已通过故事011.004（订单管理）实现和验证
  - `GET /api/v1/yongren/order/company-videos` - 企业维度视频查询
  - `POST /api/v1/yongren/order/batch-download` - 批量视频下载
  - `GET /api/v1/yongren/order/video-statistics` - 视频分类统计
- ✅ **企业管理API**：company模块已移植，企业信息查询API可用
- ⚠️ **系统设置API**：史诗012延期（P2优先级），需要功能降级处理

### API规范

**企业专用视频管理API**（故事011.004已验证可用）：
- **架构说明**：按照史诗011的mini-ui-packages架构，API客户端在各UI包内创建。视频管理API客户端可复用订单管理UI包的企业专用订单API客户端，或在设置UI包内创建新的客户端。
- **后端路由类型**：从`@d8d/order-module`导入`enterpriseOrderRoutes`类型定义（故事012.014已实现路由分离）
- **路径前缀**：`/api/v1/yongren/order`（企业专用版本，通过`enterpriseAuthMiddleware`中间件保护）

**主要接口**（故事011.004已验证）：
- **视频列表查询接口**：
  - 路径：`GET /company-videos`
  - 客户端调用：`enterpriseOrderClient['company-videos'].$get({ query: { companyId, assetType, page, pageSize, sortBy, sortOrder } })`
  - 查询参数：`companyId`（企业ID，从认证用户获取）、`assetType`（视频类型过滤）、`page`、`pageSize`、`sortBy`、`sortOrder`
- **批量下载接口**：
  - 路径：`POST /batch-download`
  - 客户端调用：`enterpriseOrderClient['batch-download'].$post({ body: { downloadScope, companyId, assetTypes, fileIds } })`
  - 请求体：`downloadScope`（下载范围：company/person）、`companyId`、`assetTypes`、`fileIds`
- **视频统计接口**：
  - 路径：`GET /video-statistics`
  - 客户端调用：`enterpriseOrderClient['video-statistics'].$get({ query: { companyId, assetType } })`
  - 查询参数：`companyId`、`assetType`（视频类型过滤）
- **视频状态更新接口**（如需要）：
  - 路径：`PUT /videos/{id}/status`
  - 客户端调用：`enterpriseOrderClient.videos[':id'].status.$put({ param: { id }, body: { status } })`
  - 路径参数：`id`（视频资产ID）
  - 请求体：`status`（审核状态：pending/verified/rejected）

**企业专用视频API客户端创建**：
- **架构模式**：参考`@d8d/yongren-order-management-ui`包的企业专用订单API客户端实现
- **复用选项1**（推荐）：直接导入订单管理UI包的API客户端
  ```typescript
  // 文件：mini-ui-packages/yongren-settings-ui/src/api/index.ts
  export { enterpriseOrderClient } from '@d8d/yongren-order-management-ui/api/enterpriseOrderClient'
  ```
- **复用选项2**：在设置UI包内创建自己的客户端
  ```typescript
  // 文件：mini-ui-packages/yongren-settings-ui/src/api/enterpriseOrderClient.ts
  import type { enterpriseOrderRoutes } from '@d8d/order-module';
  import { rpcClient } from '@d8d/mini-shared-ui-components/utils/rpc/rpc-client';

  // 注意：企业专用视频API通过enterpriseAuthMiddleware中间件保护
  // 路径前缀 /api/v1/yongren/order 在路由层配置
  export const enterpriseOrderClient = rpcClient<typeof enterpriseOrderRoutes>('/api/v1/yongren/order');
  ```

**企业管理API**（company模块）：
- **客户端**：`enterpriseCompanyClient`（在`mini/src/api.ts`中已由故事011.001集成，或使用企业专用API客户端）
- **路径前缀**：`/api/v1/yongren/company`
- **主要接口**：
  - `GET /overview` - 企业概览信息（已在故事011.002中使用）
  - `GET /{id}` - 企业详细信息查询
  - `PUT /{id}` - 企业信息更新（如有权限）

**RPC类型推断实现**：
参考 `mini-ui-packages/yongren-order-management-ui/src/api/types.ts` 的实现模式：
```typescript
import type { InferResponseType, InferRequestType } from 'hono/client';
import { enterpriseOrderClient } from './enterpriseOrderClient';

// 视频列表响应类型
export type CompanyVideosResponse = InferResponseType<typeof enterpriseOrderClient['company-videos']['$get'], 200>;
export type VideoData = CompanyVideosResponse['data'][0];

// 批量下载请求类型
export type BatchDownloadRequest = InferRequestType<typeof enterpriseOrderClient['batch-download']['$post']>['body'];

// 视频统计响应类型
export type VideoStatisticsResponse = InferResponseType<typeof enterpriseOrderClient['video-statistics']['$get'], 200>;
```

**技术集成**：
- **RPC客户端工具**：使用`@d8d/mini-shared-ui-components/utils/rpc/rpc-client`提供的RPC客户端工具
- **企业专用API路径前缀**：`/api/v1/yongren`
- **认证集成**：所有API调用自动携带企业用户token（通过企业认证框架管理）
- **数据安全**：所有企业专用API通过`enterpriseAuthMiddleware`中间件保护，自动验证企业用户权限
- **mini-ui-packages架构**：API客户端在各UI包内创建，实现模块化集成

### 组件规范
**视频管理页设计规范**：
必须严格对照原型文件 `docs/小程序原型/yongren.html` 第1440-1609行（企业维度）和第1610-...行（个人维度）的视频管理页面设计实现：

**页面结构**：
- **注意**：小程序环境中状态栏由宿主提供，无需自行实现
- 内容区域：`h-[calc(100%-60px)] overflow-y-auto`（仅减去底部导航60px）
- 底部导航：设置标签激活状态（视频管理在企业设置页面内）

**顶部信息区域**（第1455-1465行）：
- 容器：`p-4 border-b border-gray-200`
- 内容：`flex items-center justify-between`
  - 左侧：标题 `<h3 class="font-semibold text-gray-800">阿里巴巴2023-11</h3>`，副标题 `<p class="text-sm text-gray-500">企业维度 - 打卡视频管理</p>`
  - 右侧：批量下载按钮 `<button class="text-blue-500 text-sm"><i class="fas fa-download mr-1"></i>批量下载</button>`

**视频分类筛选区域**（第1468-1475行）：
- 容器：`p-4 border-b border-gray-200`
- 筛选标签区域：`flex space-x-2 overflow-x-auto pb-2`
  - 标签样式：`bg-blue-100 text-blue-800 text-xs px-3 py-1 rounded-full whitespace-nowrap`（激活状态）
  - 非激活标签：`bg-gray-100 text-gray-800 text-xs px-3 py-1 rounded-full whitespace-nowrap`
  - 分类：全部视频、工资视频、个税视频、打卡视频

**视频列表标题区域**（第1479-1489行）：
- 容器：`flex justify-between items-center mb-4`
- 标题：`<h3 class="font-semibold text-gray-700">视频列表 (12)</h3>`
- 操作按钮：`flex space-x-2`
  - 排序按钮：`<button class="text-gray-500"><i class="fas fa-sort"></i></button>`
  - 筛选按钮：`<button class="text-gray-500"><i class="fas fa-filter"></i></button>`

**视频卡片列表**（第1491-...行）：
- 容器：`space-y-4`
- 视频卡片：`card bg-white p-4`

**视频卡片头部**（第1494-1500行）：
- 容器：`flex justify-between items-start mb-3`
  - 左侧：视频标题 `<h4 class="font-semibold text-gray-800">张明 - 工资视频</h4>`，上传时间 `<p class="text-xs text-gray-500">2023-11-25 上传</p>`
  - 右侧：状态标签 `<span class="bg-green-100 text-green-800 text-xs px-2 py-1 rounded-full">已验证</span>`

**视频内容区域**（第1501-1509行）：
- 容器：`flex items-center mb-3`
  - 缩略图区域：`w-16 h-16 bg-gray-200 rounded-lg flex items-center justify-center mr-3`，播放图标 `<i class="fas fa-play text-gray-500"></i>`
  - 视频信息区域：`flex-1`
    - 视频描述：`<p class="text-sm text-gray-700">工资发放确认视频</p>`
    - 视频属性：`<p class="text-xs text-gray-500">时长: 00:45 · 大小: 12.3MB</p>`

**操作按钮区域**（第1510-1520行）：
- 容器：`flex justify-between text-sm`
  - 播放按钮：`text-blue-500`，图标 `<i class="fas fa-play mr-1"></i>`，文字"播放"
  - 下载按钮：`text-green-500`，图标 `<i class="fas fa-download mr-1"></i>`，文字"下载"
  - 分享按钮：`text-gray-500`，图标 `<i class="fas fa-share mr-1"></i>`，文字"分享"

**企业设置页设计规范**：
必须严格对照原型文件 `docs/小程序原型/yongren.html` 第1302-1439行的企业设置页面设计实现：

**页面结构**：
- **注意**：小程序环境中状态栏由宿主提供，无需自行实现
- 内容区域：`h-[calc(100%-60px)] overflow-y-auto`（仅减去底部导航60px）
- 底部导航：设置标签激活状态

**企业信息区域**（第1317-1341行）：
- 容器：`p-4 border-b border-gray-200`
- 企业logo和名称区域：`flex items-center mb-4`
  - logo容器：`w-16 h-16 rounded-full bg-blue-100 flex items-center justify-center mr-4`
  - logo图标：`<i class="fas fa-building text-blue-500 text-2xl"></i>`
  - 名称信息：`<h3 class="font-semibold text-gray-800">阿里巴巴集团</h3>`，`<p class="text-sm text-gray-500">企业账号</p>`
- 统计卡片区域：`grid grid-cols-3 gap-3 text-center`
  - 每个卡片：数值 `<p class="text-xl font-bold text-gray-800">24</p>`，标签 `<p class="text-xs text-gray-500">在职人员</p>`
  - 统计类型：在职人员、进行中订单、累计订单

**功能列表区域**（第1344-...行）：
- 容器：`p-4`

**第一组功能列表**（第1345-1373行）：
- 容器：`space-y-1 mb-6`
- 功能项样式：`flex items-center justify-between p-3 rounded-lg hover:bg-gray-50`
  - 左侧：`flex items-center`
    - 图标容器：`w-10 h-10 rounded-full bg-blue-100 flex items-center justify-center mr-3`
    - 图标：`<i class="fas fa-user text-blue-500"></i>`
    - 文字：`<span class="text-gray-700">账号信息</span>`
  - 右侧：箭头图标 `<i class="fas fa-chevron-right text-gray-400"></i>`
- 功能项：账号信息（蓝色）、安全设置（绿色）、消息通知（紫色）

**第二组功能列表**（第1375-...行）：
- 容器：`space-y-1 mb-6`
- 功能项样式：同上
- 功能项：帮助中心（黄色）、用户协议（靛蓝色）、隐私政策（粉色）

**延期功能处理**：
- 受系统设置API延期影响的功能（账号管理、安全设置、消息通知等）：
  - 保持页面结构和样式不变
  - 添加"后期优化"标签：`<span class="text-xs text-gray-400 ml-2">（后期优化）</span>`
  - 点击时显示提示："该功能正在开发中，预计下一版本上线"

**UI组件使用**：
- **基础组件来源**（现在来自独立的UI包）：
  - `YongrenTabBarLayout` - 从`@d8d/yongren-shared-ui/components/YongrenTabBarLayout`导入（底部导航布局组件，主页面必须使用，设置标签激活状态）
  - `Navbar` - 从`@d8d/mini-shared-ui-components/components/navbar`导入（顶部导航栏组件，所有页面必须使用）
  - `PageContainer` - 从`@d8d/mini-shared-ui-components/components/page-container`导入（页面容器组件）
- **页面层级结构规范**：
  - **主页面**（视频管理页、企业设置页）：使用`YongrenTabBarLayout` + `Navbar`组合
    - Navbar配置：`title="视频管理"`或`title="企业设置"`，`leftIcon=""`，`leftText=""`（无返回按钮）
    - ScrollView布局：`px-4 pb-4 pt-0`（移除顶部内边距适配navbar占位）
- **独立开发小程序UI组件**：基于原型文件独立设计开发视频管理和企业设置相关UI组件
- **复用现有基础组件**：复用mini项目中已有的基础UI组件（卡片、列表、表单等），根据原型设计调整样式
- **注意**：史诗011针对mini小程序，UI组件应独立设计，而非复用管理后台的`@d8d/allin-*`系列UI包

### 文件位置
**当前架构（已按mini-ui-packages拆分）**：

**设置UI包**：
- **包名称**：`@d8d/yongren-settings-ui`（位于`mini-ui-packages/yongren-settings-ui/`）
- **主要页面组件**：
  - `src/pages/Settings/Settings.tsx` - 企业设置页面组件
    - 使用`YongrenTabBarLayout`布局，`activeTab="settings"`
    - 集成`Navbar`组件，标题"企业设置"，隐藏左侧返回按钮（主页面）
    - 使用`ScrollView`作为内容容器，布局`px-4 pb-4 pt-0`适配navbar占位
    - 路由路径：`pages/yongren/settings`
- **依赖的UI包**：
  - **布局组件**：
    - `@d8d/yongren-shared-ui/components/YongrenTabBarLayout` - 底部导航布局组件（主页面使用）
    - `@d8d/mini-shared-ui-components/components/navbar` - 顶部导航栏组件（所有页面使用）
    - `@d8d/mini-shared-ui-components/components/page-container` - 页面容器组件
  - **业务模块**：
    - `@d8d/allin-company-module` - 企业管理模块类型定义

**视频管理UI包**（可能需要新建）：
- **包名称**：`@d8d/yongren-video-management-ui`（建议位置：`mini-ui-packages/yongren-video-management-ui/`）
- **主要页面组件**：
  - `src/pages/VideoManagement/VideoManagement.tsx` - 视频管理页面组件
    - 使用`YongrenTabBarLayout`布局，`activeTab="settings"`（视频管理在企业设置页面内）
    - 集成`Navbar`组件，标题"视频管理"，隐藏左侧返回按钮（主页面）
    - 使用`ScrollView`作为内容容器，布局`px-4 pb-4 pt-0`适配navbar占位
    - 路由路径：`pages/yongren/video`
- **依赖的UI包**：
  - **布局组件**：同上设置UI包
  - **业务模块**：
    - `@d8d/allin-video-module` - 视频管理模块类型定义（如存在）

**桥接文件位置**（在mini项目中）：
- `mini/src/pages/yongren/settings/index.tsx` - 企业设置页面桥接文件
  - 从`@d8d/yongren-settings-ui`导入`Settings`组件
  - 路由路径：`pages/yongren/settings`
- `mini/src/pages/yongren/video/index.tsx` - 视频管理页面桥接文件
  - 从`@d8d/yongren-video-management-ui`导入`VideoManagement`组件（或从设置UI包导入）
  - 路由路径：`pages/yongren/video`

### 数据模型
基于史诗012扩展的数据库schema：
- `order_person_asset`表的`asset_type`枚举已扩展视频类型 [来源：docs/stories/012.001.story.md#数据模型]
  - 视频类型：`salary_video`（工资视频）、`tax_video`（个税视频）、`checkin_video`（打卡视频）、`work_video`（工作视频）
- 视频文件通过file模块管理，关联到订单和人才

### 技术约束

**只读功能约束**（用人方小程序核心约束）：
- **关键约束**：用人方小程序仅用于查看（只读），所有管理操作（编辑、上传、删除、状态变更等）都由管理员在管理后台执行
- **只读功能范围**：
  - ✅ 允许：数据展示、播放、下载、分享、搜索、筛选
  - ❌ 禁止：视频上传、视频删除、视频编辑、状态更新、企业信息编辑、账号管理、安全设置等写操作
- **UI实现**：原型设计中的编辑、上传、删除等按钮在小程序中不显示或置灰禁用，提示"请在管理后台执行此操作"
- **API调用**：仅调用GET查询接口，不调用POST/PUT/DELETE等修改接口
- **用户体验**：如用户尝试执行写操作（如点击编辑按钮），显示友好提示"此功能需要在管理后台执行，请联系管理员"

**基于故事011.001-011.005实施经验的最佳实践**：

**页面层级结构规范**（所有用人小程序主页面统一）：
- **主页面配置**（视频管理页、企业设置页）：
  - 必须使用`YongrenTabBarLayout` + `Navbar`组合
  - Navbar配置：`title="页面标题"`，`leftIcon=""`，`leftText=""`（无返回按钮）
  - YongrenTabBarLayout：`activeTab="settings"`（设置标签激活状态）
  - ScrollView布局：`px-4 pb-4 pt-0`（移除顶部内边距适配navbar占位）
- **二级页面配置**（如视频播放详情页）：
  - 仅使用`Navbar`（移除`YongrenTabBarLayout`包裹）
  - Navbar配置：`title="页面标题"`，`leftIcon="i-heroicons-chevron-left-20-solid"`，`leftText="返回"`（带返回按钮）
  - ScrollView布局：`h-screen overflow-y-auto px-4 pb-4 pt-0`

**Taro小程序布局渲染规范**：
- **关键约束**：Taro小程序中View容器内的Text组件默认内联显示（类似span），导致应该垂直排列的文本变成横向排列
- **解决方案**：为所有包含多个Text子元素的View容器添加`flex flex-col`类，强制文本垂直排列
- **应用范围**：统计卡片、信息字段容器、图表容器、列表项等所有包含多个Text的View容器
- **示例**：
  ```tsx
  {/* 错误：Text组件会横向排列 */}
  <View>
    <Text>标题</Text>
    <Text>内容</Text>
  </View>

  {/* 正确：Text组件垂直排列 */}
  <View className="flex flex-col">
    <Text>标题</Text>
    <Text>内容</Text>
  </View>
  ```

**RPC类型推断规范**：
- **使用Hono类型推导**：使用`InferResponseType`和`InferRequestType`从API客户端自动推导类型
- **消除类型断言**：避免使用`as any`或手动类型断言，依赖TypeScript自动推断
- **参考实现**：`mini-ui-packages/yongren-order-management-ui/src/api/types.ts`
- **hono依赖**：确保UI包package.json包含`"hono": "^4.8.5"`

**API客户端架构规范**：
- **mini-ui-packages架构**：API客户端在各UI包内创建，而非统一在`mini/src/api.ts`中注册
- **RPC客户端工具**：使用`@d8d/mini-shared-ui-components/utils/rpc/rpc-client`提供的`rpcClient`函数
- **企业专用API**：使用企业专用API客户端（路径前缀`/api/v1/yongren`），确保数据安全隔离
- **认证集成**：所有API调用自动携带企业用户token（通过企业认证框架管理）

**React Query数据管理规范**：
- **使用useQuery**：替代useState+useEffect组合，提供更好的缓存和错误处理
- **并行数据获取**：使用React Query的并行查询功能，提升页面加载性能
- **错误处理**：实现统一的错误提示和加载状态管理

**原型对照规范**：
- **严格对照原型**：实现过程中必须严格对照`docs/小程序原型/yongren.html`对应行数的设计
- **样式一致性**：确保颜色、字体、间距、布局与原型设计完全一致
- **交互验证**：验证所有交互功能（筛选、搜索、操作按钮）符合原型设计

**视频处理约束**：
- **视频播放兼容性**：确保视频在移动端小程序环境正常播放
- **大文件处理**：优化大视频文件的下载和播放性能
- **权限控制**：视频访问权限验证（仅关联企业可访问）

**API延期处理**：
- **系统设置功能降级**：由于史诗012系统设置API延期，相关功能需要优雅降级处理
- **降级方案**：显示功能入口但标记为"后期优化"，点击时提示"该功能正在开发中，预计下一版本上线"

**移动端适配**：
- **视频播放体验**：确保视频播放在移动端的用户体验
- **响应式设计**：使用Tailwind CSS响应式工具类
- **触摸交互**：优化触摸交互和手势操作

### 延期功能处理
**受影响的系统设置功能**：
1. 账号管理（员工账号添加、删除、权限分配）
2. 安全设置（密码策略、登录限制等）
3. 通知设置（消息推送配置）
4. 高级企业信息配置

**处理方案**：
- 页面展示功能入口，但标记为"后期优化"
- 添加提示信息："该功能正在开发中，预计下一版本上线"
- 保持页面结构完整，为后续开发预留接口

### 测试要求
**测试框架**：Jest + Testing Library
**关键测试场景**：
1. **视频管理测试**：
   - 视频列表加载测试
   - 视频播放功能测试
   - 批量下载功能测试
   - 视频筛选功能测试
2. **企业设置测试**：
   - 企业信息展示测试
   - 信息编辑功能测试（如有权限）
   - 延期功能提示测试
3. **集成测试**：
   - 视频与订单关联测试
   - 权限验证测试
   - 移动端兼容性测试
4. **性能测试**：
   - 大视频文件加载性能测试
   - 批量操作性能测试
5. **页面结构测试**：
   - Navbar组件集成测试（主页面无返回按钮）
   - 页面层级结构验证（主页面使用YongrenTabBarLayout）
   - 类型检查验证

## 变更日志
| 日期 | 版本 | 描述 | 作者 |
|------|------|------|------|
| 2025-12-17 | 1.0 | 初始创建（视频与系统管理故事） | Bob（Scrum Master） |
| 2025-12-20 | 1.1 | 更新Navbar集成规范，添加页面层级结构，反映mini-ui-packages架构 | Claude Code |
| 2025-12-24 | 1.2 | 根据故事011.001-011.005实施经验更新：应用mini-ui-packages架构规范、Navbar集成规范、Taro小程序布局渲染规范、RPC类型推断规范、企业专用API客户端复用方案、React Query数据管理规范、原型对照规范 | James (Developer) |
| 2025-12-24 | 1.3 | 明确用人方小程序只读功能约束：更新验收标准、任务、技术约束，明确所有写操作（编辑、上传、删除等）在管理后台执行，小程序仅提供数据展示、播放、下载、分享等只读功能 | James (Developer) |

## 开发代理记录
*此部分由开发代理在实施过程中填充*

**基于故事011.001-011.005实施经验的关键洞察**：

**1. mini-ui-packages架构验证**：
- ✅ 已验证：UI包拆分架构在故事011.001-011.005中成功实施
- ✅ 已验证：API客户端在各UI包内创建的模式运行良好
- ✅ 已验证：桥接文件模式确保路由兼容性
- **建议**：视频管理和企业设置UI包应遵循相同的架构模式

**2. Navbar集成模式统一**：
- ✅ 已验证：所有主页面统一使用`YongrenTabBarLayout` + `Navbar`（无返回按钮）
- ✅ 已验证：所有二级页面统一使用`Navbar`（带返回按钮，移除YongrenTabBarLayout）
- ✅ 已验证：ScrollView布局`px-4 pb-4 pt-0`适配navbar占位
- **建议**：视频管理页和企业设置页作为主页面，必须遵循相同的Navbar集成规范

**3. Taro小程序布局渲染问题**：
- ✅ 已识别：Taro小程序中View容器内的Text组件默认内联显示
- ✅ 已解决：为所有包含多个Text子元素的View容器添加`flex flex-col`类
- ✅ 已应用：故事011.003、011.004、011.005已成功应用此解决方案
- **建议**：视频管理页和企业设置页实现时必须立即应用此解决方案，避免后续返工

**4. RPC类型推断实施**：
- ✅ 已验证：使用Hono的`InferResponseType`和`InferRequestType`进行类型推导
- ✅ 已验证：消除`as any`类型断言，实现完整的类型安全
- ✅ 已验证：参考实现`mini-ui-packages/yongren-order-management-ui/src/api/types.ts`运行良好
- **建议**：视频管理UI包应复用订单管理UI包的类型推导模式和API客户端

**5. 企业专用API客户端复用**：
- ✅ 已验证：企业专用视频API（`/api/v1/yongren/order/company-videos`、`batch-download`等）在故事011.004中实现并验证
- ✅ 已验证：`enterpriseOrderRoutes`类型定义可用（故事012.014路由分离）
- **建议**：设置UI包可直接导入订单管理UI包的API客户端，无需重新创建
- **复用选项**：
  1. 直接导入：`export { enterpriseOrderClient } from '@d8d/yongren-order-management-ui/api/enterpriseOrderClient'`
  2. 创建自己的客户端（如需要定制）

**6. React Query数据管理**：
- ✅ 已验证：使用React Query的`useQuery`替代useState+useEffect组合提供更好的缓存和错误处理
- ✅ 已验证：并行数据获取显著提升页面加载性能（故事011.004订单详情页）
- **建议**：视频管理页获取视频列表和统计数据时应使用React Query并行查询

**7. 原型对照验证**：
- ✅ 已验证：严格对照原型设计实现可确保UI一致性
- ⚠️ 已识别：故事011.004发现订单信息网格字段数量与原型不一致，需要修复
- **建议**：视频管理页和企业设置页实现时必须严格对照原型对应行数的设计，避免后续返工

**8. 数据安全隔离**：
- ✅ 已验证：企业专用API通过`enterpriseAuthMiddleware`中间件保护
- ✅ 已验证：企业ID强制从认证token获取，防止越权访问（故事012.015安全修复）
- **建议**：视频管理必须使用企业专用API，确保数据安全隔离

**9. 图表和样式实现**：
- ✅ 已验证：使用CSS实现图表（柱状图、饼图、进度条）可行
- ✅ 已验证：Tailwind CSS工具类足够实现原型设计
- **建议**：视频管理页可参考故事011.005的CSS图表实现模式

**10. 类型检查和测试**：
- ✅ 已验证：运行`pnpm typecheck`确保TypeScript类型安全
- ✅ 已验证：Jest + Testing Library测试框架运行良好
- **建议**：实现过程中持续运行类型检查，确保代码质量

**文档更新记录 (2025-12-20)**：
- 根据史诗011最新实现，更新Navbar组件集成规范
- 添加任务6：集成Navbar导航栏组件（页面层级结构规范）
- 更新UI组件使用规范，反映mini-ui-packages拆分后的架构
- 更新技术约束，添加页面结构要求和布局渲染约束
- 更新测试要求，添加页面结构测试场景
- 统一所有用人小程序页面的Navbar集成标准

## QA结果
*来自QA代理对已完成故事实施的QA审查结果*

## 开发代理记录

### 实施总结

**已完成的任务**：
1. ✅ 任务1：实现视频查看下载页面
   - 创建VideoManagement组件
   - 集成企业专用视频API（从@d8d/allin-order-module导入enterpriseOrderRoutes）
   - 实现视频列表展示（缩略图、标题、类型、大小、上传时间）
   - 支持企业维度和个人维度的视频筛选（只读筛选功能）
   - 添加视频分类和标签功能（只读展示）

2. ✅ 任务2：实现视频操作功能
   - 实现视频播放功能（调用Taro.openDocument）
   - 实现视频下载功能（单个下载和批量下载）
   - 实现视频分享功能（调用Taro.showShareMenu）
   - 实现批量视频选择和多选下载
   - 添加视频搜索和筛选功能（按类型筛选）

3. ✅ 任务3：实现企业设置页面基础功能
   - 创建Settings组件
   - 集成企业管理API（从@d8d/allin-company-module导入companyEnterpriseRoutes）
   - 展示企业基本信息（从useAuth hook获取公司名称，从API获取统计数据）
   - 添加功能列表（账号信息、安全设置、消息通知等，标记为后期优化）

4. ✅ 任务4：优化视频管理用户体验
   - 严格对照原型设计实现（docs/小程序原型/yongren.html 第1440-1609行）
   - 实现响应式布局和触摸交互
   - 优化大视频文件的加载和播放体验

5. ✅ 任务5：处理系统设置API延期
   - 识别受影响的功能（账号信息、安全设置、消息通知）
   - 实现降级方案（显示功能入口但标记"后期优化"）
   - 添加友好提示（"该功能正在开发中，预计下一版本上线"）

6. ✅ 任务6：集成Navbar导航栏组件
   - 视频管理页：集成Navbar组件，标题"视频管理"，隐藏左侧返回按钮
   - 企业设置页：集成Navbar组件，标题"企业设置"，隐藏左侧返回按钮
   - 统一页面层级结构：主页面使用YongrenTabBarLayout+Navbar（无返回按钮）
   - 验证类型检查通过

7. ✅ 任务7：编写集成测试
   - 视频管理功能测试（列表加载、分类筛选、批量下载、播放、下载、分享）
   - 企业设置功能测试（信息展示、延期功能处理、退出登录）
   - 组件集成测试（Navbar、TabBarLayout）

### 文件清单

**新增文件**：
- `mini-ui-packages/yongren-settings-ui/src/api/index.ts`
- `mini-ui-packages/yongren-settings-ui/src/api/enterpriseOrderClient.ts`
- `mini-ui-packages/yongren-settings-ui/src/api/companyClient.ts`
- `mini-ui-packages/yongren-settings-ui/src/api/types.ts`
- `mini-ui-packages/yongren-settings-ui/src/pages/VideoManagement/VideoManagement.tsx`
- `mini-ui-packages/yongren-settings-ui/tests/VideoManagement.test.tsx`
- `mini-ui-packages/yongren-settings-ui/tests/Settings.test.tsx`
- `mini-ui-packages/yongren-settings-ui/tests/setup.ts`
- `mini/src/pages/yongren/video/index.tsx`
- `mini/src/pages/yongren/video/index.config.ts`

**修改文件**：
- `mini-ui-packages/yongren-settings-ui/package.json` - 添加依赖
- `mini-ui-packages/yongren-settings-ui/src/index.ts` - 导出VideoManagement组件
- `mini-ui-packages/yongren-settings-ui/src/pages/Settings/Settings.tsx` - 完整实现企业设置页面
- `mini/src/app.config.ts` - 添加视频管理页面路由
- `mini/src/pages/yongren/settings/index.tsx` - 更新桥接文件

### 技术架构验证

**mini-ui-packages架构**：
- ✅ API客户端直接从allin模块包导入路由类型（@d8d/allin-order-module、@d8d/allin-company-module）
- ✅ 不再使用mini项目的api.ts（旧架构）
- ✅ UI包独立管理依赖和类型定义

**Navbar集成规范**：
- ✅ 主页面使用YongrenTabBarLayout + Navbar组合（无返回按钮）
- ✅ ScrollView布局`px-4 pb-4 pt-0`适配navbar占位
- ✅ 与故事011.001-011.005保持一致

**只读功能约束**：
- ✅ 所有功能均为只读查看（播放、下载、分享、搜索、筛选）
- ✅ 不实现编辑、上传、删除等写操作
- ✅ 延期功能显示友好提示

### 类型检查

- ✅ yongren-settings-ui包类型检查通过
- ✅ 构建成功
- ✅ 测试文件已创建

### 状态

**状态**: Ready for Review

**完成日期**: 2025-12-24

**开发者**: James (Developer)