hyb-oa/.trellis/tasks/07-18-small-team-internal-readiness/prd.md

五人团队正式内用最小收口

Goal

在不部署、不连接真实数据、不进行公网或企业微信真机验证的前提下，把当前代码收敛为适合约 5 人公司内部使用的本地候选版本。角色上明确分离业务管理、财务和 OA 系统运维；业务上保证付款状态、敏感资料和高影响操作可控；工程上建立可信的本地候选门禁。

本任务承接用户在 2026-07-17 批准的 07-17-small-team-internal-readiness 方案。由于任务实际创建日期为 2026-07-18，Trellis 目录按规则使用 07-18-small-team-internal-readiness。

Scope

• Backend：Fastify 权限、员工/账号/工资/合同和付款批次路由，Prisma 加法迁移，聚焦与并发测试。
• Frontend：角色管理、敏感资料与付款页面、共享表格/dirty guard、移动考勤与归档、聚焦 E2E/视觉断言。
• QA / governance：路由分类、流程覆盖扫描、local-candidate runner、当前 task、必要 Trellis spec/现有手册及 finding 生命周期。
• 只使用本地合成数据和隔离测试资源；不改变生产配置或真实数据。

Requirements

角色、权限与敏感资料

• 所有账号保留员工基础能力；日常职责可显式兼任 manager、ceo、finance 和新增 system_admin。
• manager 与员工 direct_manager_id 分开维护；经理身份不自动建立汇报关系。
• 新增 RoleCode.system_admin。现有 admin 继续作为通配超级管理员，但只用于初始化和应急，不作为普通预设。
• 普通用户管理界面显示员工、直属经理、公司负责人、财务、OA 系统管理员；finance_mgr/hr/administration 保留为高级兼容职责；普通界面不可授予 admin。
• system_admin 可管理其他普通账号、业务角色、系统配置、集成和审计；不得修改自己的角色，不得授予或撤销 admin/system_admin，所有变更写脱敏审计。
• system_admin 不获得工资、银行、证件、员工合同、付款执行或业务审批权限。
• 付款复核要求显式具有 manager 或 ceo，不能仅凭 admin 或 system_admin 进入正常审批路径。
• 新增细分权限：system.accounts.manage、system.roles.manage、payroll.manage、employee.bank.read、employee.bank.manage、employee.identity.manage、employee.contract.manage、payment.batch.review。
• /employees 对业务选择调用者只返回窄 DTO；完整员工档案仅本人或人员资料管理员可读，权限拒绝发生在敏感查询或文件读取前。
• 财务只读银行字段，不读取证件或修改敏感资料；未授权字段从响应中省略。
• 员工合同列表、元数据、附件下载和写操作使用独立权限；DTO 不返回内部路径，成功访问和变更写脱敏审计。
• 前端按权限隐藏动作；后端仍为最终授权边界。

付款一致性与最小审计

• 固定“财务制单/执行 + 经理或公司负责人复核”；创建者不得复核自己的批次。
• 所有金额只需一次独立复核；总金额达到 50000 元时增加警示和强确认，不增加第三人审批。
• 批次状态为 draft -> reviewed -> executed|failed|cancelled；failed 只重试失败项或取消剩余项；executed/cancelled 为终态。
• 创建、复核、执行、取消、付款元数据更新和回单作废在事务内锁定批次；执行再按稳定顺序锁定源单并复查状态和金额。
• 并发竞争返回确定性 409，不重复更新付款状态、审计或通知。
• 正式范围只接受已审批、未付款且未进入其他有效批次的报销；payment_batch_v1 启用时直接报销付款端点不得形成第二付款路径。
• 新增付款候选查询，页面按业务编号、人员、金额和日期选择，不要求粘贴内部 UUID；创建接口继续权威复查。
• 取消必须填写 2–500 字原因；取消失败批次只终止未付款项，不表示退款或冲正。
• 回单采用有理由的留痕作废，不物理删除；已复核后的付款元数据变更写 before/after 审计。

核心页面与本地候选门禁

• 项目、资产、合同、付款、报销表格在 768×1024 和 1024×768 下操作可达；容器可控横滚，页面整体不横向溢出。
• 报销、采购、合同、资产长表单共享未保存保护，覆盖站内跳转、记录切换、浏览器返回和刷新。
• 高敏附件删除和付款回单作废显示对象、后果和理由确认；普通可恢复动作不升级为强确认。
• 新增 /mobile/attendance 并消除移动考勤自循环；修复 375×812 下移动归档长字段裁切和底栏遮挡。
• 完成付款、合同、票据的权限显隐；修正资产旧 E2E，补齐项目/资产标题动作视觉覆盖；通过后回填并归档 05-31-unified-page-header-actions。
• 所有注册路由分类为 core、supported-noncore、deferred 或 frozen。未分类、核心行为测试缺失、仅由 manual/live 测试覆盖时门禁非零退出。
• 本地核心矩阵覆盖：登录退出、报销、审批、票据、采购、项目/合同、付款/AP、人员/审计、考勤/归档、移动工作台。
• 建立仓库内可移植的 local-candidate 门禁，不依赖公网、生产配置、历史 Issue CSV 或个人绝对路径。

Acceptance Criteria

• Prisma enum 包含 system_admin，加法迁移可验证且有回滚说明；既有角色与历史账号不自动迁移。
• 角色矩阵证明业务管理、财务、系统管理员和超级管理员职责分离，系统管理员不能自我提权。
• 员工目录、完整档案、银行、证件、工资和员工合同权限满足字段级与对象级边界；拒绝路径无敏感 DB/file 副作用。
• 付款批次创建、复核、执行、失败重试、取消和回单作废满足状态机、maker-checker、原因与审计合同。
• 合成本地 PostgreSQL 并发验证覆盖双执行、执行与取消、双创建、直接付款与批次付款竞争，结果唯一且不重复审计/通知。
• 付款页面使用业务候选选择器，不要求普通用户输入 UUID；高额仅增加警示和确认。
• 五类表格、四类未保存表单、不可逆动作、移动考勤和移动归档通过聚焦浏览器验证。
• 付款、合同、票据权限显隐与后端拒绝一致；05-31-unified-page-header-actions 剩余测试和视觉证据闭合后才归档。
• 路由清单无未分类项，门禁反例对 unmapped、manual-only、核心缺失行为/视觉均能失败。
• 十个核心流程束在本地合成环境实际运行，记录最终 URL、H1、角色、主操作和页面错误断言。
• 完整本地质量门禁通过；权限、状态机、workflow 和迁移变更完成独立只读复审。
• 收口结论只写 LOCAL_CANDIDATE_PASS，不写已部署、可公网测试或企业微信真机通过。

Definition of Done

• 代码、迁移、测试、现有规范/手册和 finding 生命周期同步更新，未新建重复审查报告。
• bash scripts/check-minimal.sh、Prisma 校验、服务端聚焦及全量测试、前端 typecheck/build、聚焦 Playwright、task validate、Trellis governance、敏感扫描、文档 registry 和 git diff --check 通过。
• 三个实施阶段分别复核，最后以中文 commit 引用本任务；不部署、不 push。
• 05-31-unified-page-header-actions 仅在其剩余验收确实闭合后归档；当前任务完成后按 Trellis finish-work 归档并记录 journal。

Test Plan

• 静态与单元：Prisma validate、触及服务端文件 node --check、权限/DTO/审计/付款路由 Vitest、前端 typecheck/build。
• 集成：隔离合成 PostgreSQL 应用已提交 migration，运行付款四类并发竞争，结束后清理数据库；不连接共享开发库或生产库。
• 浏览器：本地 Vite dev 与合成 fixture 实际运行十个核心流程；PC 768×1024/1024×768 和 WeCom UA 375×812 记录 URL、H1、角色、错误及溢出指标。
• 门禁可信度：为 unclassified、manual-only、core behavior missing、visualRequired missing 提供反例测试并断言非零退出；Playwright --list 只证明资产可解析。
• 全量收口：bash scripts/check-minimal.sh、task validate、Trellis governance、敏感扫描、文档 registry、git diff --check；权限/状态机/workflow/迁移另做只读 reviewer 复核。

Decision (ADR-lite)

Context：公司约 5 人，需要低配置成本，但系统维护者不一定是领导，付款与高敏资料仍需要最小职责分离。

Decision：保留现有多角色引擎和业务职责，新增受限 system_admin，保留隐藏的应急 admin；付款使用数据库行锁和 maker-checker，不建设通用权限平台、事件平台或多级审批系统；发布只增加本地候选模式。

Consequences：日常界面简单且允许一人兼任多个职责；数据库仅做加法迁移；至少两个不同账号才能闭环付款；真实账号分配和内部环境验证必须在后续授权任务完成。

Out of Scope

• 部署、公网检查、生产配置、真实账号分配、真实数据库写入、迁移 deploy、数据库重置、备份恢复演练。
• 企业微信真机、真实 OCR、真实付款、银行直连/流水、退款冲正、ERP/总账、差旅付款恢复。
• 通用 RBAC 平台、权限表达式设计器、全局幂等平台、事件总线、分布式锁、可配置多级金额审批。
• 全量可访问性、搜索直达、复杂离线数据生命周期、所有通知精准定位、非核心路由视觉重做。

Technical Notes

• 规划基线：58c8dec；实现开始前若 HEAD 变化，更新 task notes 并重跑全部门禁。
• 发现来源：归档任务 07-16-system-multidimensional-audit 中 DATA-EMP-001、DATA-HR-ATT-001、PAY-STATE-001、PAY-AUDIT-001、PAY-UX-001、UX-SAFE-001、UX-FORM-001、MOB-ATTEND-001、RESP-TABLE-001、REL-GATE-001、UI-PERM-001、MOB-ARCHIVE-001。
• 页面可靠性沿用现有设计语言，不做新视觉风格裁决；当前会话没有可用的 frontend-design skill。