Commit a6a726

2026-11-15 03:14:08 sijie: 新增用户教程与Wiki方案、车队系统性能测试方案页面 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Home.md ..
@@ 4,6 4,8 @@
原有角色、场景和用例统一标记为**早期规划**,保留作历史参考,不代表当前系统功能或验收口径;其原有的“草稿 / 待业务确认”状态仍保留。排班条目原有的“暂缓”标记也保留。
+ - [用户教程与 Wiki 方案](用户教程与Wiki方案) · [车队系统性能测试方案](车队系统性能测试方案)
+
当前功能核对以[前后端功能与数据一致性检查(2026-10-03)](前后端功能与数据一致性检查-2026-10-03)为入口。是否向最终用户开放某项能力单独决定;决定开放后,前端操作、后端规则与实际数据必须一致。
- **访客可直接编辑**:打开页面上的条目旁 **编辑**,可直接进入对应页面;使用编辑器的表格菜单增删行列,修改后按 **Save**。新增角色、场景或用例可点击下方 **+新增**。无需 GitLab 账号。
/dev/null .. 用户教程与Wiki方案.md
@@ 0,0 1,28 @@
+ # 用户教程与 Wiki 方案
+
+ ## 结论
+
+ 继续使用 **Gollum**(`ty-wiki-portal`)作为用例与教程的协作编辑入口,Git 仓库为唯一事实源;正式交付的教程站与 PDF/DOCX 从同一仓库由 CI 构建。
+
+ ```
+ GitLab Wiki 仓库(唯一事实源)
+ ▲ push/pull(sync.sh,每 2 分钟) ▲ MR / push
+ Gollum 网页编辑(系统账号登录) VS Code / Obsidian / Typora 本地编辑
+ └─ CI:Markdown → VitePress 教程站 / PDF / DOCX(正式交付、可白标)
+ ```
+
+ ## 待补齐:登录与审计
+
+ 1. **oauth2-proxy** 放在 Gollum 前面,接统一身份源(车队/仓库系统账号,如 Supabase Auth OIDC 或 Keycloak/Authentik),按用户组限制可登录人员。
+ 2. **`config.rb` Rack 中间件**:读取 `X-Forwarded-User` / `X-Forwarded-Email`,写入 `session['gollum.author']`,使每次网页编辑的 Git 提交作者为真实用户;缺少请求头的请求一律拒绝。
+ 3. **读写分离**:只读实例(`--no-edit`)与可编辑实例指向同一仓库。
+
+ ## 外部文档联动
+
+ - 技术人员克隆仓库直接编辑并推送。
+ - 客户 DOCX 由 CI 用 Pandoc 转为 Markdown 入库;反向导出 DOCX/PDF 交付。
+ - 截图由 Playwright 脚本在测试环境自动生成,界面变化后重跑更新。
+
+ ## 相关
+
+ - [车队系统性能测试方案](车队系统性能测试方案)
/dev/null .. 车队系统性能测试方案.md
@@ 0,0 1,120 @@
+ # 车队系统性能测试方案
+
+ 目标:测准车队系统在**不同数据量 × 不同访问频次 × 不同用户角色**下的延迟与故障率。用可重复的测试矩阵,而不是一次性并发压测。
+
+ 最终要回答三个问题:
+ 1. 当前日常容量是多少?
+ 2. 性能从哪个负载点开始恶化?
+ 3. 瓶颈在前端、接口、权限逻辑、数据库还是存储?
+
+ ## 1. 测试维度
+
+ ### 数据规模
+
+ | 档位 | 典型规模 | 用途 |
+ |---|---|---|
+ | S | 当前生产量的 10% | 基线与开发回归 |
+ | M | 当前生产量 | 模拟现状 |
+ | L | 当前生产量的 3–5 倍 | 未来增长 |
+ | XL | 当前生产量的 10 倍 | 找系统极限 |
+
+ 扩数据时要同步放大:车辆、司机、客户、订单;发车、轨迹、维修、轮胎、油料历史;报关单、提单、集装箱;工资、扣款、审批、附件;以及每个用户可访问的数据范围。性能常由历史明细、关联深度、权限过滤和分页方式决定,而不是主表行数。
+
+ ### 访问频次(按每秒业务操作数描述)
+
+ | 模式 | 在线用户 | 操作/秒 |
+ |---|---|---|
+ | 低频 | 10–20 | 1–3 |
+ | 日常 | 50–100 | 5–15 |
+ | 高峰 | 200–500 | 30–100 |
+ | 突发 | 30–60 秒内从日常升到高峰 | — |
+ | 耐久 | 日常或高峰保持 4–12 小时 | — |
+
+ 操作类型分开统计:浏览/搜索/分页;新建与修改;审批、批量确认、结算;上传与预览附件;导入、导出、报表。
+
+ ### 用户角色
+
+ 分别模拟调度、司机、HR、维修、报关、财务、办公室管理员。不同角色的权限过滤、接口调用量和查询复杂度不同。
+
+ ## 2. 真实业务场景
+
+ 编写约 10–20 条完整流程,例如:
+
+ ```
+ 登录 → 车辆列表 → 搜索车牌 → 车辆详情 → 维修历史 → 新增维修记录 → 月度汇总
+ ```
+
+ 按真实比例混合:
+
+ | 流程 | 占比 |
+ |---|---|
+ | 页面浏览和列表查询 | 40% |
+ | 搜索、筛选、详情 | 25% |
+ | 订单和调度操作 | 15% |
+ | 维修、HR、报关写入 | 10% |
+ | 审批和批量操作 | 5% |
+ | 上传、导出及其他 | 5% |
+
+ 操作之间加入 2–15 秒思考时间。
+
+ ## 3. 指标
+
+ - **用户体验**:首屏加载、点击到可操作时间、LCP / INP / CLS、前端错误与白屏率。
+ - **接口与业务操作**:P50 / P95 / P99 / 最大延迟、吞吐量、超时率、HTTP/RPC 错误率、**业务失败率**(返回 200 但数据未落库、状态错误、导出不完整也算故障)。
+ - **后端与数据库**:CPU、内存、连接数、等待队列;慢查询、锁等待、死锁;各 RPC/SQL 与 Edge Function 耗时;缓存命中率;存储上传下载延迟;各层网络时间。
+
+ ## 4. 测试矩阵
+
+ 每次只改变一个主要变量;每个组合至少跑 3 次取中位数,并记录代码版本、数据库快照、时间和配置。
+
+ | 数据规模 | 在线用户 | 模式 | 时长 |
+ |---|---|---|---|
+ | S | 10 | 正常 | 15 分钟 |
+ | M | 50 | 正常 | 30 分钟 |
+ | M | 200 | 高峰 | 30 分钟 |
+ | L | 50 | 正常 | 30 分钟 |
+ | L | 200 | 高峰 | 60 分钟 |
+ | XL | 200 | 高峰 | 60 分钟 |
+ | L | 100 | 耐久 | 8 小时 |
+ | L | 50→500 | 突发 | 20 分钟 |
+
+ ## 5. 四类测试
+
+ 1. **基准**:单用户、无竞争,得到每项操作的本底耗时。
+ 2. **阶梯负载**:逐步加用户,找延迟拐点。
+ 3. **压力**:超过拐点,确认极限、失败方式与恢复能力。
+ 4. **耐久**:持续数小时,发现连接泄漏、缓存膨胀、队列堆积。
+
+ 工具:接口负载用 k6 或 Locust;完整页面体验用 Playwright。两类结果不能互相替代。
+
+ ## 6. 验收门槛(初始值,按基线调整)
+
+ - 核心页面和操作 P95 ≤ 2 秒;普通查询 P95 ≤ 1 秒
+ - 复杂报表、批量操作走异步任务,不长期阻塞页面
+ - 非预期错误率 ≤ 1%;核心保存、审批、结算业务失败率为 0
+ - 无连接耗尽、死锁或持续增长的等待队列
+ - 负载停止后 5 分钟内恢复到基线
+ - 相同代码与负载下性能回退超过 10%–15% 时阻止发布
+
+ ## 7. 容易漏测的部分
+
+ - 大量历史记录下的车辆、司机、维修详情
+ - 多条件筛选、排序、深分页
+ - 权限范围很大的管理员账号
+ - 月度汇总、结算、审批后的缓存刷新
+ - 同一司机或车辆被多人同时保存
+ - 大文件上传、扫描 PDF 预览、批量导出
+ - 冷缓存与热缓存差异;统计信息更新前后的执行计划
+ - 批量导入与日常操作同时发生
+ - 登录、Token 刷新、权限查询的额外负载
+
+ ## 8. 安全落地
+
+ - 先在隔离环境使用**脱敏生产快照**,按比例扩充数据。
+ - 生产环境只做低风险、受控的热测试:
+ - 使用唯一的 `HOT-<批次>` 测试数据
+ - 只走正式页面和正式接口
+ - 测试账号仅在测试期间启用
+ - 不修改真实业务记录
+ - 出现非隔离写入、非预期错误超过 1% 或关键 P95 超过 2 秒,立即停止
+ - 工资批量确认等高风险场景必须有近期备份、精确批次和回滚方案。
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9