AI-Secretary/docs/specs/05_权限日志失败记录.md

05_权限日志失败记录

1. 模块目标

权限、日志和失败记录模块负责保证第一版闭环可控、可追溯、可复盘。权限必须在后端校验，关键操作必须写日志，AI、飞书、调度和业务失败必须形成失败记录。

权限、安全、日志脱敏、飞书验签幂等和访问边界的全局事实源是 docs/contracts/安全权限日志约定.md；本 spec 只说明模块目标和业务补充。

2. 第一版做什么

1. 定义老板、程经理、普通员工、管理员 / AI 团队四类角色。
2. 控制事项、提醒、草稿、反馈、失败记录的可见范围和操作范围。
3. 记录关键操作日志。
4. 记录 AI 解析失败、模型调用失败、AI 记忆读写失败、草稿转换失败、人员映射缺失、飞书通知失败、回调失败、定时触发失败、用户反馈有问题等失败。
5. 支持管理员 / AI 团队查看和处理失败记录。
6. 对敏感信息做日志边界约束。

3. 第一版不做

1. 不做复杂组织架构。
2. 不做细粒度多级权限。
3. 不做复杂审批流。
4. 不做独立失败看板或复杂 BI。
5. 不把飞书身份直接等同于业务权限。
6. 不把密钥、token、完整手机号、完整邮箱写入普通日志。

4. 核心流程

权限校验：

请求进入 DRF view
-> permission class 做入口校验
-> serializer 做参数校验
-> service 做业务权限和状态校验
-> 通过后执行业务动作

失败记录：

业务或外部调用失败
-> 写 failure_records
-> 保留关联对象和失败类型
-> 管理员 / AI 团队处理
-> 填写处理结果
-> 写 operation_logs

操作日志：

关键动作发生
-> 记录 actor、action、target_type、target_id
-> 记录操作渠道和结果摘要
-> 避免记录敏感明文

5. 数据对象

本模块主要使用：

1. users
2. failure_records
3. operation_logs
4. model_call_logs
5. feishu_events
6. secretary_messages
7. bot_contexts

字段以 docs/contracts/数据对象约定.md 为准。

安全和访问边界以 docs/contracts/安全权限日志约定.md 为准。

6. 接口需求

主要接口：

1. GET /api/users/me
2. GET /api/failure-records
3. GET /api/failure-records/{id}
4. PATCH /api/failure-records/{id}
5. POST /api/failure-records/{id}/resolve
6. GET /api/notifications
7. GET /api/notifications/{id}
8. GET /api/feedbacks

接口格式以 docs/contracts/API接口约定.md 为准。

7. 权限规则

1. 普通员工只能看自己作为接收人、创建人或反馈人的记录。
2. 老板能看自己发起、创建或接收的记录。
3. 程经理能看自己发起、负责、待确认，以及第一批试用管理范围内的记录。
4. 管理员 / AI 团队能看失败记录、通知记录、人员映射和必要操作日志。
5. 普通员工不能给别人创建事项或提醒。
6. 反馈人必须是事项或提醒接收人。
7. 飞书登录用户必须匹配到启用状态的平台用户后才能进入平台。
8. 模型调用日志、飞书原始 payload、失败记录原始错误和一次性操作 token 明文不得对普通员工开放。

8. 状态流转

失败记录状态以 docs/contracts/状态流转约定.md 为准。核心约束：

1. 新失败进入 pending。
2. 处理中进入 processing。
3. 填写处理结果后进入 resolved。
4. 确认不处理可进入 cancelled。
5. 失败记录状态变化必须写操作日志。

9. 必须写日志的动作

1. 飞书登录成功或失败。
2. 机器人收到老板消息。
3. 非老板私聊机器人。
4. AI 生成草稿、解析失败。
5. AI 追问、普通记录、上下文回顾和 BotContext 变化。
6. 人工确认、修改、取消草稿。
7. 老板点击补充/重说。
8. 程经理确认复杂事项。
9. 创建事项、创建提醒。
10. 发送通知、补发通知、通知失败。
11. 接收反馈，尤其是有问题反馈。
12. 定时提醒触发成功或失败。
13. AI 记忆读写失败、草稿转换失败和失败记录处理。
14. 背景摘要或老板风格提示词版本启用。

10. 给 AI 的测试样例

1. 普通员工创建给别人的事项，应被拒绝并写权限失败日志。
2. 普通员工创建给别人的提醒，应被拒绝。
3. 非接收人提交反馈，应被拒绝。
4. 管理员处理失败记录时，必须留下处理结果。
5. 日志中不得包含完整手机号、完整邮箱、飞书 token 或密钥。
6. 未匹配平台用户的飞书登录应失败并写失败记录。
7. PostgreSQL AI 记忆读写失败时，应写 memory_store_failed，不得继续依赖内存确认草稿。
8. 飞书旧卡片或失效卡片回调只记录事件，不写业务对象。
9. 一次性操作 token 只能保存 hash，普通日志不得出现明文。

11. Review 重点

1. 后端权限是否完整。
2. 状态流转是否可追踪。
3. 失败记录是否包含关联对象、失败类型和处理结果。
4. 日志是否记录操作人和渠道。
5. 敏感信息是否被脱敏。
6. 访问范围是否符合 安全权限日志约定.md。