hyb-oa/.trellis/tasks/08-11-internal-oa-usage-census-and-simplification/design.md

内部 OA 使用度普查与减法路线图：设计说明

1. 设计目标与边界

本任务是一次性生产测量和产品组合裁决，不是监控平台建设，也不是功能精简实施。设计优先保证三件事：查询确实只读、活动归因不把自动化当用户、结论不会由单一数字机械推出。

仓库事实源建立显式模块目录
  -> 本地校验查询合同与输出白名单
  -> 生产 identity / runtime SHA / migration PRE
  -> 单个 READ ONLY 事务读取聚合
  -> 脱敏快照 + 去污染分桶
  -> 业务必要性裁决
  -> 四类矩阵 + 30 天路线图
  -> 只读 reviewer

任何阶段失败都停止在证据层，不执行 feature flag、导航、代码、schema 或数据变更。

2. 模块目录

2.1 目录来源

目录由四个来源交叉形成：

1. workspaceSettings.js：用户实际可能看到的主、管理、备用和隐藏入口；
2. featureFlags/index.js：运行环境 gate 与数据库 override 的组合开关；
3. schema.prisma：真实持久化表、时间字段和 actor 关系；
4. 07-30 组合盘点与当前业务事实源：业务必要性、替代品和既有建议。

不以 Prisma model 数量直接代表模块数量。认证 challenge、session、迁移、通知投递、同步 item 等辅助表并入所属模块或列为系统活动，不单独宣称用户价值。

2.2 模块组

模块组	主记录信号	人工活动信号	典型系统/辅助信号
工作台/通知	notifications、announcements	公告创建/签收、真人通知阅读	通知投递重试
统一审批	workflow_instances/tasks/history	提交、审批完成、转交	超时提醒、自动撤权
报销/票据/OCR	reimbursement_forms、invoice_pool	真人提交、附件、财务处理	OCR/验真 job
付款/AP	payment_batches/items/receipts	创建、复核、执行、回单	outbox/ERP skip
采购	purchase_requests/items/attachments	申请、提交、归档	通知与工作流辅助
合同	contract_registry、confidential refs	创建、维护、终止/导出	到期类系统提示
项目	projects 及里程碑/任务/风险	负责人创建更新、成员活动	关联索引
资产/盘点	asset_cards、assignments、inventory_checks	建档、领用、转移、盘点	批量导入
请假/企微留存	leave_requests、wecom_approval_*	OA/企微发起和真人审批	callback、compensation、reconcile
考勤/团队状态	attendance/presence、wecom_checkin_*	真人修正、管理员校正	同步 run、日/月摘要
周报/普通待办/公告	weekly_reports、todo_items、portal_announcements	提交、完成、创建/签收	自动待办/提醒
预算	budget_pools/ledger/rules	预算维护与人工调整	阈值命中
差旅	travel_requests/orders/reconciliation	申请、导入确认、支付	卡流水导入/ERP
人员生命周期	employees、lifecycle/checklist、employee contracts/training/certs	入离职和资料维护	企微 HR 同步
薪资/绩效	salary/payslip/performance_*	生成、发放、评价	批处理生成
系统候选	feature flags、cutover、integration_*	管理员明确操作	定时同步、迁移期任务

实施阶段把该逻辑展开为逐表 allowlist；每个 SQL 标识符必须来自审核后的静态清单，不接受运行时动态拼接。

3. 数据采集合同

3.1 生产身份

• 复用 production-identity-bootstrap 解析唯一 trialrun 目标，不把仓库占位符、其他数据库或本地容器当生产。
• 读取并记录实际运行镜像的完整/短 SHA 与 migration 摘要。比较对象是当前运行容器，不要求本地文档提交后的 HEAD 等于已部署应用 SHA。
• 不为本任务复制脚本到生产、不发布新候选、不修改远端部署输入。

3.2 事务

审阅后的 task-scoped 查询通过 stdin 送入现有运行环境，不持久化在生产。核心事务合同为：

BEGIN TRANSACTION READ ONLY;
SET LOCAL statement_timeout = '30s';
SET LOCAL lock_timeout = '2s';
-- assert current_setting('transaction_read_only') = 'on'
-- execute static allowlisted aggregate SELECTs
COMMIT;

• 禁止 DDL、DML、SELECT ... FOR UPDATE、存储过程调用、临时表和动态 SQL。
• 聚合只用 count、max、条件计数和 count(distinct ...)；不返回原始业务行。
• 任一表不存在、字段不一致、超时或 JSON 输出不可解析，整体结果标记 QUERY_FAILED，不得把缺失值补成 0。
• 如果连接或输出通道不确定，先以只读证据定性；不得在未知状态下反复 SSH 执行。

3.3 PRE/POST

• PRE：生产 identity、运行 SHA、migration pending、数据库事务只读能力均明确。
• POST：事务成功提交、transaction_read_only=on 证据存在、输出仅含白名单字段；再次确认运行 SHA/migration 未被本任务改变。
• PRE/POST 间可能有真实用户并发新增记录。若重复只读校验数值变化，记为并发观察，不归因于普查，也不为了“稳定结果”暂停用户。

4. 输出模型与隐私

每个模块只允许输出如下稳定字段：

moduleKey
totalRows
created30d / created90d
activity30d / activity90d
latestActivityAt
humanActors30d / humanActors90d
humanEvents30d / humanEvents90d
smokeEvents30d / smokeEvents90d
systemEvents30d / systemEvents90d
unknownEvents30d / unknownEvents90d
navigationMode
effectiveFlagState
queryStatus

时间按生产数据库当前时间计算并统一输出 ISO 时间；最终文档可只保留日期粒度。禁止输出 employee id、姓名、员工编号、邮箱、手机号、IP、user agent、业务编号、金额、正文、附件路径、原始 extra 或 payload。

4.1 smoke 识别

复用现有 helper 的 smoke-like 语义：已知 smoke 前缀、受控测试编号及“测试/试运行”标志。匹配只发生在生产事务内，外部只收到 human/smoke/system/unknown 聚合计数。规则命中不删除数据，也不改变账号状态。

4.2 system 识别

系统活动由静态 action/表映射识别，例如同步 run、callback/compensation、通知投递、OCR/验真 job、ERP outbox/skip、逾期提醒和自动撤权。管理员手工触发的 job 可以同时具有真人触发者和系统结果；矩阵分别记录“真人触发”和“系统产物”，避免重复解释为两名用户。

4.3 unknown

旧数据没有 actor、actor 已归档、action 语义混合或来源无法证明时进入 unknown。unknown 可以证明“存在数据”，不能证明真人持续使用。

5. 有效导航与开关

• 导航以生产 workspace_settings 的模块可见性为准，缺记录时才回退当前应用默认配置。
• feature flag 的有效状态同时考虑运行环境 gate、数据库 override、rollout 类型和部门 allowlist；只输出 on/off/partial/unknown，不输出环境变量原值或部门标识。
• “隐藏但有真实使用”可能来自直达链接或管理员入口，是需要核实的发现；“显示但无人使用”才构成导航减法候选。
• flag 关闭只能解释当前不可用，不能证明数据无价值或可以物理退役。

6. 分类算法

分类采用证据卡而非硬阈值自动打标。每张卡包含：

production usage + people/frequency + exposure
+ owner + failure cost + substitute
historical recommendation + confidence
=> decision + rationale + trigger

判定顺序：

1. 先看是否存在真实人工活动，而不是总行数；
2. 再看 30/90 天频率、实际 actor 数和最近活动；
3. 再应用小团队决策门，识别低频但必要能力；
4. 最后考虑当前入口是否造成认知负担，以及是否有企微/手工 SOP 等可靠替代；
5. 证据冲突或缺业务确认时，保守落入 保持冻结 并列出确认问题。

分类不会自动执行动作：

分类	本任务产物	后续动作
重点优化	最多两条真实问题候选	另建产品 task，先说明具体用户与问题
保持冻结	保持可用、不扩建	事件触发或真实问题出现再评估
隐藏入口	可逆显隐建议	另建 workspace/flag task 并批准生产变更
候选退役	调研清单	另做数据导出、保留、依赖、回滚审查后再决定

7. 失败矩阵

失败	处理
生产 identity、SHA 或 migration 不明确	停止，不查询
事务不是 read-only	立即回滚并停止
allowlist 与 schema 不一致	标记合同失败，回本地修正，不推断使用度
查询超时/通道中断/JSON 不可解析	QUERY_FAILED；保留首个失败现场，不连续重跑
smoke/system 无法可靠区分	进入 unknown，不计入真人活动
导航或 flag 有效状态无法计算	标记 unknown，不以代码默认代替生产事实
数据显示零使用但业务必要性未确认	保持冻结，登记负责人确认项
发现疑似真实业务缺陷	停止产品处置，另建缺陷 task；本任务只记录证据

8. 证据与复核

任务目录只保存查询合同、脱敏聚合快照、决策矩阵和执行摘要。生产连接信息、原始 SQL 输出、完整账号和 payload 不进入仓库、task 或对话。

由于结论会影响后续模块显隐和退役决策，执行后启动只读 reviewer，重点核对：

• 实际查询是否严格等于 allowlist 和只读合同；
• 人工/smoke/system/unknown 分桶是否有证据；
• 零行、flag off、自动审计量是否被误用；
• 四类结论是否符合小团队决策门；
• 路线图是否把产品价值置于工具债之前；
• 本任务是否未执行任何产品或生产变更。

9. 回滚

本任务没有生产写入，因此没有数据回滚。若聚合、归因或分类错误，撤回相应结论并重新审阅查询合同即可。任何未来隐藏/退役动作的回滚由其独立 task 设计，本任务不预先授权。