hyb-oa/docs/MVP主线代码差距盘点.md

MVP 主线代码差距盘点

Issue: A1 in issues/2026-05-09_20-57-19-mvp-mainline-dev-kickoff.csv 日期: 2026-05-09 范围: 只读盘点，不改业务代码，不部署。

1. 盘点结论

首轮开发不应重写 OA。仓库内已经存在审批、报销、票据、企业微信、请假、采购、合同台账和项目轻管理的主要实现，下一步应按当前 PRD 做“主线收口”和“试运行门禁”，而不是新建一套系统。

当前可复用的主干如下：

主线	可复用实现	结论
统一审批中心	workflow 路由、WorkflowDefinition/Instance/Task/History 模型、PC/移动审批页、审批回归脚本	可作为 A2 底座，优先修入口、状态一致性、deeplink 和权限边界
报销/发票/OCR	reimbursements、invoicePool、附件、OCR、查重、付款、导出、PC/移动报销页	可作为 A3 底座，重点修主流程体验和状态文案
企业微信基础设施	wecomAuth、身份绑定表、移动入口识别、通知 dispatcher、企业微信 webhook provider	可作为 A4 底座，重点验证未绑定回退、停用阻断、通知脱敏和 deeplink
请假/考勤	leave、请假余额/附件/审批/撤回、团队日历；另有极简考勤与团队状态	A5 先收口请假，不扩成完整考勤；补卡/外出/加班需另拆或只做最小入口
采购/费用	purchaseRequests、明细、附件、审批、撤回、PO/合同号归档、采购回归	A6 可做采购最小可用收口；费用申请可先复用报销/采购口径，不新造预算/ERP
合同归档	contractsRegistry、合同编号唯一、项目关联、归档位置、审计	A6 可做台账最小可用；正式合同审批和合同附件库不是首轮默认范围
项目轻管理	projects、成员、里程碑、任务、风险、交付、周报/报销/合同关联	A6 可做项目页汇总收口，不做重型项目管理
权限/导航	systemWorkspace、导航可见性、前端路由守卫、角色权限	A7 重点收紧普通员工主路径和 P2 备用模块
回归门禁	server 回归脚本、client E2E、QA smoke/live readiness 脚本	A8 可复用现有门禁，缺真实配置时必须标 SKIP

首轮默认不新增公共 API、不新增数据库表。若后续确认要实现补卡/外出/加班独立审批对象、合同正文附件库、正式合同审批、自动发票验真强依赖或预算占用，应另拆 Issue，并在 Notes 写明迁移和回滚路径。

2. 当前事实源

本次按以下当前事实源盘点：

文档	用途
docs/海音达OA-MVP需求规格说明书.md	MVP 总纲、路线和验收
docs/需求-统一审批中心规约.md	审批动作、状态机、权限和留痕总依据
docs/需求-报销发票OCR规约.md	报销、发票、OCR、附件、付款和导出依据
docs/需求-企业微信基础设施规约.md	企业微信入口、绑定、通知、deeplink 和打卡边界
docs/需求-请假考勤修正规约.md	请假、补卡、外出、加班和考勤解释依据
docs/需求-采购费用审批规约.md	采购/费用申请最小可用依据
docs/需求-合同附件归档规约.md	合同台账、编号、归档位置和敏感边界依据
docs/需求-项目轻管理规约.md	项目轻管理和业务关联依据

路线确认：

• hyb-oa 是唯一业务主系统和唯一审批中心。
• 企业微信只做入口、身份、通知和打卡原始采集边界。
• 企业微信原生审批、飞书、钉钉、小程序、复杂 BPM、完整 ERP、AI 和重型项目管理不进入首轮开发。

3. 后端与数据模型盘点

3.1 统一审批中心

可复用：

• server/src/routes/workflow.js 已提供待办列表、待办详情、通过、驳回、退回、转审、批量通过、批量驳回。
• Prisma 已有 WorkflowDefinition、WorkflowInstance、WorkflowTask、WorkflowHistory、ApprovalRule、ApprovalTransfer。
• 待办详情已能关联报销、请假、采购、差旅对象。
• workflow 动作已在业务状态、历史记录、通知副作用之间做事务处理和后处理。

待修缺口：

• PC 待办列表目前偏“快速通过 + 详情”，退回、驳回、转审主要在详情页和移动页完成，A2 需确认 PC 操作是否清晰。
• 批量审批接口当前以报销权限和 reimbursement 为主，采购/请假批量是否首轮开放需在 A2 明确，不建议首轮扩大。
• 合同审批对象尚未接入 workflow，首轮 A6 只按合同台账最小可用处理。
• 移动审批存在离线队列能力，但 PRD 明确首批审批动作必须在线提交，A2 需确保离线草稿不会被误解为正式审批已完成。

3.2 报销、发票、OCR、附件

可复用：

• server/src/routes/reimbursements.js 已覆盖报销创建、列表、详情、明细、附件、提交、撤回、付款、项目关联。
• server/src/routes/invoicePool.js 和 server/src/routes/invoicePool/* 已覆盖票据上传、OCR、状态查询、可绑定票据、绑定/解绑、人工修正、归档、查重例外、发票文件访问。
• Prisma 已有 ReimbursementForm、ReimbursementItem、ReimbursementAttachment、InvoicePool、InvoiceVerificationRecord。
• 报销提交会校验绑定发票、审批定义、审批人和单号；付款后会归档已用发票。

待修缺口：

• InvoiceVerificationRecord 和验真接口已经存在，但当前 PRD 首批口径是 OCR + 查重 + 财务人工复核，A3 不能把自动验真变成必选路径。
• PC 和移动报销页功能较多，A3 重点应清理普通用户可见的内部术语、状态码和发票池概念。
• 报销主流程应优先验证“上传 -> OCR 终态 -> 绑定明细 -> 提交 -> 审批 -> 付款 -> 导出”，不在首轮扩展 ERP 导出能力。
• 费用申请若与报销/采购边界不清，A3/A6 应先采用现有报销或采购能力，不新建费用模块。

3.3 企业微信基础设施

可复用：

• server/src/routes/wecomAuth.js 已提供 /api/auth/wecom/config、login、callback、bind、unbind。
• WecomIdentityBinding 已保证 employee_id 和 external_user_id 唯一。
• callback 已覆盖已绑定直达、未绑定回退登录、绑定冲突、员工停用阻断和审计。
• server/src/services/notificationDispatcher.js、server/src/services/notifications/*、server/src/services/integrations/im/wecom.js 已支持企业微信 webhook、delivery 记录、失败分类和重试。
• client/src/lib/runtimeContext.ts 已能把企业微信/移动容器映射到 /mobile，并把 PC 详情页映射到移动等价路径。

待修缺口：

• 通知当前走 channel + webhook 能力，是否完全满足“脱敏标题、业务编号、状态、deeplink”需在 A4 逐类验收。
• 企业微信 live smoke 需要真实 CorpID、AgentID、回调地址、webhook 等配置；缺配置必须 SKIP。
• runtimeContext 中还有通用企业 IM UA 判断包含钉钉，仅用于移动偏好判断，不等于接入钉钉；A4/A7 可视情况把文案和测试聚焦为企业微信。

3.4 请假、考勤修正和团队状态

可复用：

• server/src/routes/leave.js 已覆盖假别、余额、工作日预览、请假创建/编辑/详情/提交/撤回。
• server/src/services/leave.js 已有工作日、附件规则、假期 ledger 预占和审批通过后扣减口径。
• LeaveRequest、LeaveLedger、WorkflowInstance 已支持请假接入统一审批。
• PC 请假页有团队日历，移动页支持请假提交，团队状态页支持在岗/居家/外出/出差/请假展示。
• 另有 attendance 路由、AttendanceRecord 和 AttendancePolicy，但应按当前路线视为备用/历史能力，不作为首轮正式打卡实现目标。

待修缺口：

• 补卡、外出、加班尚未形成独立 OA 审批对象；当前只有极简考勤补录和团队状态手工外出，不等于正式审批流。
• 企业微信打卡同步未实现，符合当前“首批不接打卡 API”的边界；A5 不应开发定位、人脸、Wi-Fi 或排班。
• A5 应先验证请假审批结果对团队状态或日历的影响。若补卡/外出/加班必须上线，应另拆独立 Issue，可能需要新增模型或复用申请对象，不能混在 A5 主线修补里。

3.5 P1 采购、合同、项目

可复用：

• purchaseRequests 已覆盖采购草稿、明细、附件、提交、撤回、审批、PO/合同号归档和采购回归脚本。
• contractsRegistry 已覆盖合同台账列表、到期提醒、新增、编辑、续签，合同编号唯一，支持项目关联、责任人、归档位置和审计。
• projects 已覆盖项目列表/详情、成员、里程碑、任务、风险、费用摘要、差旅摘要、周报、沟通记录、收口清单、交付记录和涉密文档引用。
• Prisma 已有 PurchaseRequest、PurchaseRequestItem、PurchaseAttachment、PurchaseOrderArchive、ContractRegistry、Project、ProjectMember、ProjectMilestone、ProjectTask、ProjectRisk、ProjectDeliveryRecord 等。

待修缺口：

• 采购当前包含预算预占、ERP track 等较重能力，A6 应只保留“申请 -> 审批 -> 附件/归档可追溯”的最小可用验收。
• 合同台账没有正式合同 workflow，也没有合同正文附件库；首轮只验收编号、状态、责任人、归档位置、项目关联和非涉密边界。
• 项目页功能较全，A6 应避免扩成项目管理平台，只确认关键事项汇总、风险、交付记录和业务关联。

4. 前端入口与页面盘点

可复用页面：

模块	PC 页面	移动页面
审批	WorkflowTasksPage.tsx、WorkflowTaskDetailPage.tsx	MobileApprovalsPage.tsx
报销	ReimbursementsPage.tsx、ReimbursementDetailPage.tsx、InvoicePoolPage.tsx	MobileReimbursementsPage.tsx、MobileReimbursementDetailPage.tsx、MobileCapturePage.tsx
企业微信绑定	ProfilePage.tsx	MobileProfilePage.tsx
请假	LeaveRequestPage.tsx	MobileLeavePage.tsx
采购	PurchaseRequestsPage.tsx	复用响应式 PC 页面
合同	ContractsRegistryPage.tsx	复用响应式 PC 页面
项目	ProjectsPage.tsx、ProjectDetailPage.tsx	移动端首批以 /mobile 摘要和 PC 响应式为主

入口现状：

• client/src/router/index.tsx 已注册 PC 和移动主路由。
• AppShellLayout 会根据企业微信/移动容器跳转到移动等价路径。
• MobileBottomNav 默认提供首页、审批、票据、我的；MobilePortalPage 额外提供报销、请假等卡片入口。
• notificationLinks.ts 已把 workflow、reimbursement、leave、purchase 等通知目标解析回 OA 页面。

待修缺口：

• PC 主导航目前有“主导航 / 管理入口 / 备用模块”分组，后台也有 system/navigation，但 fallback 与服务端默认可见性不完全一致；A7 需统一。
• 审批待办在服务端默认可见性中归入 admin/backup 强制段，A2/A7 需确保主管、财务、老板的审批入口清晰可达。
• 普通员工拥有一些旅行/采购/项目自助权限，A7 需确认是否会看到完整差旅、预算、AP、ERP、AI 等非首轮主路径。
• 移动端采购、合同、项目没有完整移动专页，首轮 A6 只做最小可用和可达性，不扩展移动完整编辑体验。

5. 测试与回归盘点

可复用门禁：

范围	已有脚本或用例
后端总回归	server/scripts/regression-all.sh
审批动作	server/scripts/regression-workflow-actions.sh、client/tests/e2e/workflow-quick-approve.spec.ts、client/tests/e2e/mobile-approvals-offline.spec.ts
报销/票据/OCR	server/scripts/regression-dedup.sh、server/scripts/regression-ocr.sh、client/tests/e2e/r102-reimbursement-main-flow.spec.ts、client/tests/e2e/invoice-ocr-flow.spec.ts
企业微信入口	client/tests/e2e/wecom-entry.spec.ts、client/tests/e2e/wecom-first-bind.spec.ts、client/tests/e2e/r124-mobile-entry-matrix.spec.ts
请假/日历	client/tests/e2e/leave-flow.spec.ts、client/tests/e2e/leave-team-calendar.spec.ts
采购/项目	server/scripts/regression-procurement.sh、client/tests/e2e/procurement-flow.spec.ts、client/tests/e2e/project-workbench.spec.ts
权限/导航	client/tests/e2e/settings-governance.spec.ts、scripts/qa/check-mobile-route-contract.mjs
组合门禁	scripts/qa/run-business-flow-gates.sh、scripts/qa/run-web-gates.sh、scripts/qa/check-live-smoke-env.mjs

测试缺口：

• 合同台账目前没有明确的首轮 E2E，应在 A6 或 A8 补人工步骤或轻量 E2E。
• 企业微信真实入口、真实 webhook 和真实 OCR 依赖配置，A8 必须允许 SKIP 并记录原因。
• A7 权限导航需要按员工、主管、财务、管理员做角色矩阵，不应只跑 build/typecheck。

6. A2-A8 实施边界建议

Issue	建议边界	不做范围	是否需要新增 API/DB
A2 统一审批中心	修 PC/移动待办、详情状态、审批历史、deeplink 一致性；确认并发/已处理提示	不新增企业微信原生审批；不扩复杂 BPM；不强行批量支持所有业务	默认不需要
A4 企业微信基础设施	验证 config、绑定、未绑定回退、停用阻断、通知脱敏、deeplink 回 OA	不接飞书；不接企业微信原生审批；不做打卡同步	默认不需要
A3 报销/发票/OCR	收口上传、OCR 状态、查重、绑定、提交、付款、导出、用户文案	不把自动验真设为必需；不扩 ERP；不重构 OCR provider	默认不需要
A5 请假/考勤	先收口请假审批、团队状态/日历；补卡/外出/加班不足则记录或最小入口	不接企微打卡 API；不做定位/人脸/Wi-Fi/排班	独立补卡/外出/加班可能需要另拆
A6 P1 最小可用	采购申请审批、合同台账、项目汇总最小可用	不做预算/ERP/AI/复杂招采/重型项目	合同审批/附件库若要做需另拆
A7 权限导航	收紧角色可见性和备用模块；确保审批、报销、请假入口清晰	不靠前端隐藏替代服务端权限	默认不需要
A8 回归门禁	汇总 server/client/E2E/smoke/live readiness；真实配置缺失标 SKIP	不部署；不通知真机试运行	不需要

7. 后续开发顺序

建议继续执行既定顺序：

1. A2：统一审批中心入口与状态收口。
2. A4：企业微信入口、绑定、通知回 OA。
3. A3：报销/发票/OCR 主链路收口。
4. A5：请假、补卡、外出、加班与考勤口径。
5. A6：P1 采购、合同、项目最小可用。
6. A7：权限、导航与备用模块护栏。
7. A8：回归门禁与试运行证据收口。

A1 之后可以进入 A2，但 A2 是涉及 workflow 状态机、权限和入口的一类高风险改动，实施前需要给出具体技术方案并等待批准。