wangsli/hyb-oa
1
0
派生 0
代码 工单 合并请求 工作流 8 软件包 项目 发布 百科 活动
文件
0b0cc69897e59fa69c7ee4402da029698c900b8b
hyb-oa/docs/管理员手册.md
T

20 KiB
原始文件 Blame 文件历史

hyb-oa 管理员手册（10 人以下团队版）

当前状态（2026-05-13 / DCL8）：R6 已通过，PC6、PA6、FL6、AP6、RI6、LP6、ME6、QG6、DG7/MRF7、MIA7、MIF7/MIF7T 和 MIF7TD 已完成相应收口；ME6-3 代表性企业微信真机门禁已关闭。R7 未真实启动，R7/OPS7/DOC7 仍只是准备材料，不代表已启动或已上线；下一步先做 R7E 自动门禁和参与人/窗口确认。

1. 适用范围

  • 适用于 small_team_internal 工作区模式。
  • 适用于单公司、少部门、全员账号密码登录的小团队。
  • 目标是把内部高频管理动作收口到 hyb-oa；企业微信只作为入口、身份、通知和打卡底座。

2. 管理员每周固定动作

  • 周一：查看 审批待办、报销/OCR 异常、请假/补卡/外出/加班审批、项目风险和本周关键付款/归档事项。
  • 周中：处理报销退回、重复发票例外、企业微信绑定异常、人员权限和审批规则缺口。
  • 周五：复核未完成审批、未付款报销、待归档合同/附件、采购/费用申请和下周请假安排。

3. 首次上线最小配置

  1. 进入 工作区设置，确认产品模式为 small_team_internal。
  2. 首批主路径优先保留：Portal、审批待办、报销、票据/OCR、请假、项目、采购/费用、合同/附件。
  3. 团队状态、周报、待办、公告、人员、资产 可按真实试运行需要开启；预算、支付批次、AP 运营、ERP、AI、完整差旅能力默认作为管理员备用或历史能力，不作为当前 MVP 首批主线。
  4. 在 用户管理 中按推荐预设配置：老板 / 管理员 / 主管 / 员工。
    • 正式审批组织口径：majianyong 配置为员工可见直属主管和 manager；wangshunli 配置为后台公司负责人 ceo + admin，不配置为普通 manager。
    • 普通员工和专用测试员工的直属主管配置为 majianyong；majianyong 的直属领导配置为 wangshunli。
    • admin 只代表系统管理权限，不代表业务审批权；需要业务审批时必须配置 manager、ceo、finance、hr 等正式业务角色。
    • 缺直属主管、主管停用、主管链断裂或审批节点解析到申请人本人时，应先修正组织或审批规则，不要用管理员账号代批。
  5. 检查功能开关：
    • 建议开启：portal_home_v1、企业微信入口相关开关、报销/OCR、审批待办、请假和项目基础能力。
    • 按需开启：announcements_v1、presence_board_v1、weekly_report_v1、employee_lifecycle_v1、todo_board_v1、global_search_v1。
    • 建议保留备用：payment_batch_v1、cutover_console_v1、预算/AP/ERP/AI 相关开关。

3.1 ORG8 组织账号与角色边界

OA 员工账号是权限、审批、业务数据和审计的主事实源；企业微信身份只作为入口、免登和通知辅助。管理员维护组织账号时，先保证员工主数据完整，再配置角色和企业微信绑定。

最小必填主数据：

字段 用途 缺失影响
员工账号和姓名 登录、单据归属、审批历史 无法稳定追踪责任人
部门和职位 列表筛选、组织展示、权限判断辅助 财务和负责人扫读困难
直属主管 请假、报销、采购等默认审批链 审批人缺失或错误回退
账号状态 登录、入口、通知和禁用拦截 离职或停用人员可能继续进入
业务角色 审批、财务、HR、系统管理入口 权限过大或无法处理待办
企业微信绑定状态 手机入口、免登、通知 deeplink 企业微信入口无法直达或误绑定

角色边界：

角色 允许能力 禁止或高风险边界
员工 提交本人报销、请假、采购，查看本人单据和通知 不得查看他人财务、审批待办或管理员入口
直属主管 / 审批人 处理分配给自己的审批待办，查看必要的单据摘要和历史 不得处理未分配给自己或超出角色范围的待办
财务 复核报销、处理付款标记、导出授权范围内财务数据 不默认拥有系统管理权限，不处理非财务系统配置
管理员 / HR 维护员工、部门、角色、主管链、入口配置和绑定异常 admin 不等于业务审批人，不应用管理员账号代批
系统管理员 维护部署、备份、配置、日志和企业微信应用密钥 不处理业务审批，不查看无关财务明细
老板 / 负责人 处理高风险或大额审批，查看授权管理摘要 不替代员工直属主管的日常组织配置

不兼容或需确认的组合：

  • admin-only 账号不得作为报销、请假或采购的业务审批人。
  • 财务和系统管理员混授属于高风险组合，必须有人工确认、审计记录和可回退路径。
  • 直属主管、审批人或财务账号停用后，不得继续接收新待办；历史审批记录保留只读。
  • 新员工账号创建必须同时确认直属主管、初始角色、账号状态和企业微信绑定路径。
  • 离职或停用账号必须阻断登录、企业微信入口和新业务处理，但不得删除历史单据和审批记录。

只读审计口径：

所有 ORG8 主数据审计只允许使用只读账号执行 SELECT，输出仅保留工号、姓名、状态、角色摘要、业务类型和数量；不得导出手机号、邮箱、银行卡、身份证号、密码哈希、token 或企业微信真实标识。发现问题后只记录摘要和责任归属，不在审计 SQL 中修数据。

直属主管缺失：

WITH role_summary AS (
  SELECT employee_id, string_agg(role_code::text, ',' ORDER BY role_code::text) AS roles
  FROM employee_roles
  GROUP BY employee_id
)
SELECT e.employee_no, e.name, e.status, COALESCE(r.roles, '') AS roles
FROM employees e
LEFT JOIN role_summary r ON r.employee_id = e.id
WHERE e.status = 'active'
  AND e.direct_manager_id IS NULL
  AND COALESCE(r.roles, '') !~ '(^|,)(ceo|admin)(,|$)'
ORDER BY e.employee_no;

主管停用或主管链断裂：

SELECT e.employee_no, e.name, m.employee_no AS manager_no, m.name AS manager_name, m.status AS manager_status
FROM employees e
LEFT JOIN employees m ON m.id = e.direct_manager_id
WHERE e.status = 'active'
  AND e.direct_manager_id IS NOT NULL
  AND (m.id IS NULL OR m.status <> 'active' OR m.archived_at IS NOT NULL)
ORDER BY e.employee_no;

待办分配给停用审批人或无有效角色持有人：

SELECT t.id AS task_id, wi.entity_type, a.employee_no AS assignee_no, a.name AS assignee_name, a.status AS assignee_status
FROM workflow_tasks t
JOIN workflow_instances wi ON wi.id = t.instance_id
LEFT JOIN employees a ON a.id = t.assignee_id
WHERE t.status = 'pending'
  AND t.assignee_id IS NOT NULL
  AND (a.id IS NULL OR a.status <> 'active' OR a.archived_at IS NOT NULL)
ORDER BY t.created_at;

SELECT t.assignee_role, count(*) AS pending_count
FROM workflow_tasks t
WHERE t.status = 'pending'
  AND t.assignee_role IS NOT NULL
  AND NOT EXISTS (
    SELECT 1
    FROM employee_roles er
    JOIN employees e ON e.id = er.employee_id
    WHERE er.role_code = t.assignee_role
      AND e.status = 'active'
      AND e.archived_at IS NULL
  )
GROUP BY t.assignee_role
ORDER BY t.assignee_role;

admin-only 误用为业务审批：

WITH role_summary AS (
  SELECT employee_id, string_agg(role_code::text, ',' ORDER BY role_code::text) AS roles
  FROM employee_roles
  GROUP BY employee_id
)
SELECT t.id AS task_id, wi.entity_type, e.employee_no, e.name, r.roles
FROM workflow_tasks t
JOIN workflow_instances wi ON wi.id = t.instance_id
JOIN employees e ON e.id = t.assignee_id
JOIN role_summary r ON r.employee_id = e.id
WHERE t.status = 'pending'
  AND r.roles ~ '(^|,)admin(,|$)'
  AND r.roles !~ '(^|,)(manager|ceo|finance|finance_mgr|hr)(,|$)'
ORDER BY t.created_at;

SELECT id, name, level1_role, level2_role, level3_role
FROM approval_rules
WHERE enabled = true
  AND 'admin' IN (level1_role::text, COALESCE(level2_role::text, ''), COALESCE(level3_role::text, ''))
ORDER BY priority;

财务和系统管理员混授：

WITH role_summary AS (
  SELECT employee_id, string_agg(role_code::text, ',' ORDER BY role_code::text) AS roles
  FROM employee_roles
  GROUP BY employee_id
)
SELECT e.employee_no, e.name, e.status, r.roles
FROM employees e
JOIN role_summary r ON r.employee_id = e.id
WHERE e.status = 'active'
  AND r.roles ~ '(^|,)admin(,|$)'
  AND r.roles ~ '(^|,)(finance|finance_mgr)(,|$)'
ORDER BY e.employee_no;

4. 人员生命周期管理

4.1 入职

  1. 在 人员管理 创建员工账号。
  2. 打开员工详情页，补齐部门、职位、直属上级、试用期结束日、工作地点、紧急联系人。
  3. 发起 入职，系统会自动生成 checklist：账号初始化、资产发放、制度确认。
  4. checklist 全部完成后，员工状态自动从 onboarding 进入 probation。

4.2 转正 / 调岗

  • 转正：记录事件并将员工状态改为 active。
  • 调岗：记录部门、直属上级、职位调整，同时生成调岗交接 checklist。
  • 这两个动作只做管理留痕，不引入复杂审批流。

4.3 离职

  1. 发起 离职 后，系统自动生成离职 checklist：资产归还、权限回收、费用与审批清理、交接说明。
  2. 若员工仍有名下资产或待处理审批任务，系统不会自动完成离职。
  3. checklist 完成且阻塞清零后，账号会被停用，主业务入口对该账号不可再用。

5. 团队状态与考勤口径

  • 员工每天可在 Portal 或 团队 页更新状态：在岗 / 居家 / 外出 / 出差。
  • 已批准请假会自动覆盖当天状态为 请假。
  • 企业微信打卡只作为原始采集工具；定位、人脸、Wi-Fi 和排班规则不在 OA 内重造。
  • OA 后续同步企业微信打卡数据后，应结合 OA 请假、补卡、外出、加班审批形成正式考勤口径。
  • 请假、补卡、外出、加班等审批仍在 OA 内完成，不使用企业微信原生审批。

6. 周报与待办

  • 周报固定三段：本周完成 / 当前阻塞 / 下周计划。
  • 建议每周五下班前提交，周一老板看团队汇总。
  • 需要跟进的事项可从周报沉淀为待办。
  • 高优先级待办建议由老板或管理员统一看板跟进。

7. 公告与 Portal 使用建议

  • 公告只发公司级通知、制度更新、假期提醒，不做复杂 CMS。
  • Portal 首屏建议重点看：
    • 今日团队状态
    • 未提交周报人数
    • 需协助员工
    • 入/离职待办
    • 资产待归还
    • 审批待办

8. 备用模块治理

  • 采购/费用、合同/附件和项目轻管理属于 P1 轻量能力，可在 P0 审批、报销/OCR、请假和企业微信入口稳定后逐步开放。
  • 预算、支付批次、AP 运营、ERP、AI、完整差旅、资产深度管理等保留代码和历史数据，但不作为当前 MVP 首批主路径。
  • 若短期完全不用，保持管理员可见即可，不必删除。
  • 只有出现真实场景时，再恢复到主导航或单独扩展。

9. 推荐上线顺序

  1. 先完成账号、角色、部门、企业微信自建应用入口和账号密码回退路径。
  2. 再启用 OA 统一审批中心 + 报销/发票/OCR/附件，跑通提交、审批、退回、查重、付款和导出闭环。
  3. 同步启用 请假/补卡/外出/加班，明确企业微信打卡只是原始采集，正式考勤解释回到 OA 审批结果。
  4. 在 P0 稳定后开放 P1：采购/费用审批、合同/附件归档、项目轻管理。
  5. 最后按真实需要评估周报、团队状态、公告、人员生命周期、资产、预算、支付、ERP、AI 和完整差旅。

10. 试点验收口径

  • 全员都能账号密码登录；已绑定员工能从企业微信 海音达工作台 进入移动工作台。
  • 至少 1 笔报销完成：上传发票或附件 -> OCR/查重 -> 提交 -> OA 审批 -> 财务复核/付款标记 -> 导出。
  • 至少 1 条请假或补卡完成：员工提交 -> OA 审批 -> 团队状态或考勤解释口径不破坏。
  • 至少 1 个审批待办从企业微信提醒 deeplink 回到 OA 页面处理。
  • P1 试点时，至少 1 条采购/费用申请、1 条合同台账、1 个项目关联事项可创建、审批或归档。
  • 上线前完成 1 次 DB + 文件存储备份和恢复演练，并记录恢复后的 /ready 结果
  • 普通员工主导航不出现预算、AP、ERP、AI、完整差旅等当前首批不开放的备用模块。

11. 4 周观测操作法

  1. 每周一进入 Portal 和 审批待办 查看近 7 天登录覆盖率、审批积压、报销/OCR 异常、请假/补卡审批和企业微信入口错误。
  2. 每周五记录本周结论、关键阻塞、是否需要调整审批规则、报销规则、企业微信入口或导航。
  3. 若某周出现员工未登录、报销长期停留、发票重复处理不清、审批积压或企业微信绑定异常，优先修正规则和入口，不额外维护表格作为正式记录。
  4. 连续 4 周都达到预期后，再扩大到 P1 采购/费用、合同归档和项目轻管理试点。

12. 企业微信入口与登录策略

  • 企业微信定位为 入口 + 免登 + 通知 + 打卡原始采集，不承载公司正式审批流。
  • 公司只维护一个企业微信自建应用，建议命名为 海音达工作台。
  • 默认工作台入口在企业微信手机端落到 /mobile；桌面浏览器和账号密码登录仍进入 /portal。员工真正操作仍在 hyb-oa 内完成。
  • 所有报销、采购、费用、合同、请假、补卡、外出、加班、出差审批都在 OA 内提交和审批；企业微信消息只负责提醒并 deeplink 回 OA。
  • 企微免登建议先完成账号绑定，再逐步在试点部门开启；任何时候都保留账号密码回退。
  • 若 OA 部署到公网，生产建议同时满足：HTTPS、COOKIE_SECURE=true、登录失败锁定、限流、审计开启。

正式接入最小步骤

  1. 在企业微信管理后台创建或编辑唯一自建应用：海音达工作台。
  2. 将工作台入口配置为：https://oa.hyinda.com/api/auth/wecom/login?returnTo=%2Fmobile。
  3. 将 OAuth 回调地址配置为：https://oa.hyinda.com/api/auth/wecom/callback。
  4. 在 deploy/trialrun/.env 中补齐并开启：
    • WECOM_ENABLED=true
    • WECOM_ENTRY_ENABLED=true
    • WECOM_OAUTH_ENABLED=true
    • WECOM_CORP_ID=...
    • WECOM_AGENT_ID=...
    • WECOM_AGENT_SECRET=...
    • WECOM_REDIRECT_URI=https://oa.hyinda.com/api/auth/wecom/callback
    • WECOM_ALLOWED_RETURN_HOSTS=oa.hyinda.com
  5. 先让管理员用账号密码登录，在 个人设置 完成一次绑定，再测试企业微信工作台直达；已绑定用户从手机企业微信进入时应直接看到移动工作台。
  6. 不配置企业微信原生审批模板作为正式流程；审批提醒使用企业微信消息，审批动作回到 OA 页面完成。

员工会看到的典型状态

  • 未绑定：登录页会提示“当前企业微信账号尚未绑定”，回退到账号密码登录。
  • 已绑定：从企业微信工作台进入后直接落到 /mobile，桌面或普通浏览器场景仍可进入 Portal。
  • 入口未开放：个人设置仍可绑定，但登录页不会把企业微信作为正式入口展示。
  • 配置不完整：个人设置会明确提示缺少 CorpID / AgentID / 回调地址 等原因。
  • 收到审批提醒：点击后进入 OA 审批页，在 OA 中同意、驳回、退回或转审。

13. 轻项目管理使用建议

  • 项目主档只做轻量管理：成员、里程碑、任务、风险、交付记录、合同台账与资料引用。
  • 不要把 hyb-oa 推成完整项目组合平台；甘特图、资源排产、CRM 仍不在本主线。
  • 员工日常动作建议统一挂项目：
    • 差旅申请挂项目
    • 报销单挂项目
    • 周报按项目拆分进展
    • 待办可直接挂项目
  • 管理层每周主要查看 项目 页中的逾期里程碑、高优任务、风险与费用/出差汇总，而不是再维护第二套项目台账。

14. 涉密边界

  • hyb-oa 只记录涉密合同或资料的元数据：编号、责任人、密级、归档位置、离线档案号。
  • 涉密正文、涉密附件、详细报价/成本/毛利、敏感客户资料不进入公网 OA。
  • 企业微信通知不得发送涉密正文，只保留最小必要信息和 deeplink。
  • 企业微信审批不作为涉密或财务审批载体，正式审批记录以 OA 审批历史和审计日志为准。
  • 如项目被标记为涉密，管理员应要求正文继续保存在内网文件盘、NAS 或离线档案中。

15. 初始化与导入建议

  1. 首次上线先完成系统初始化：数据库迁移、配置种子、管理员种子。
  2. 不要直接把开发库、测试库或旧 OA 整库导入到生产。
  3. 如需导入，只导最小必要主数据：
    • 部门
    • 员工
    • 角色
    • 在用资产
    • 活跃项目
    • 合同元数据
  4. 不导入这些内容：
    • 历史审批单
    • 通知历史
    • 审计日志
    • 聊天记录
    • 涉密正文与附件
  5. 建议顺序：初始化系统 -> 管理员登录验证 -> 最小主数据导入 -> 小范围试点 -> 全员启用。

16. 公网部署最低建议

  1. 为 OA 配置独立 HTTPS 域名，例如 https://oa.example.com。
  2. 在 deploy/trialrun/.env 中设置：
    • APP_ORIGIN=https://oa.example.com
    • COOKIE_SECURE=true
    • PUBLIC_SECURITY_HARDENING_ENABLED=true
  3. 若启用企业微信入口，补齐：WECOM_* 与 WECOM_ALLOWED_RETURN_HOSTS。
  4. 将 OPENAPI_DOCS_ENABLED 保持为 false，不要在公网生产暴露文档入口。
  5. 定期检查审计日志中的登录失败、Refresh 来源不匹配与涉密资料查看记录。
  6. 准备独立 smoke 账号，不使用老板、管理员或真实员工日常账号跑自动化；smoke 账号的角色和直属上级应按正式审批链配置。
  7. 每次正式发布前记录备份文件名、恢复负责人和上个可回滚 tag。

17. 网页自动化门禁（R28/R30）

  • 推荐发布时直接执行：bash scripts/qa/run-release-gate.sh all。
  • 发布前至少执行一次：bash scripts/qa/run-web-gates.sh smoke-local。
  • 发版前或主分支合并前建议执行：bash scripts/qa/run-web-gates.sh full-local。
  • 发布到 https://oa.hyinda.com 后，使用独立 smoke 账号执行：bash scripts/qa/run-web-gates.sh smoke-live。
  • live smoke 只做只读检查，不允许提交审批、付款、导入或任何真实业务写操作。
  • 如果本机已配置 LIVE_SMOKE_*，bash deploy/trialrun/deploy.sh 完成远端部署后会自动补跑 live smoke。
  • 首次接入企微、SMTP 或证书变更可人工复核；日常发布不再要求手点页面验收。

18. R23 试点收口纪律

  • 客户沟通如果影响项目计划、交付、报价、风险或下一步动作，必须在 24h 内回填到 项目 -> 客户沟通。
  • 回填只写结果摘要、下一步动作和下次跟进日期，不粘贴完整聊天记录，不上传私人微信截图。
  • 项目经理每周至少检查一次 项目 -> 项目收口 面板，确认红黄灯来源是否已经处理。
  • 若某项收口任务选择 已豁免，必须填写理由；豁免不代表永久忽略，只代表本周软约束放行。
  • 试点期每周五复盘一次“仍靠聊天/表格补流程”的案例，并决定是补回填纪律还是补最小功能。

19. R29 设计与工作台治理口径

  • 首页不再做“模块超市”，而是先告诉员工今天该做什么。
  • 管理员不要把备用模块重新平铺到主导航，避免系统再次变成模块拼盘。
  • 员工入口默认认知应保持为：企业微信进入 -> OA 移动工作台 -> 进入审批/报销/请假等模块处理；PC 用户可直接登录 OA。
  • 如果未来新增页面，请优先复用统一骨架：
    • 首页：WorkbenchHero + MetricCard + SectionPanel
    • 列表页：PageHeader + FilterBar + 主列表
    • 详情页：概览 -> 执行 -> 留痕 -> 归档/合规
  • 若某页面出现两个以上竞争级主按钮，应视为设计回退并在上线前修正。
在新工单中引用 查看 Git Blame 复制永久链接