Skip to content

Commit b05a304

Browse files
author
wangchunji
committed
feat: add toc persistence foundation
1 parent daed40f commit b05a304

32 files changed

Lines changed: 3324 additions & 0 deletions

‎.env.example‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
# Copy this file to .env and fill in your values
44
# ============================================================
55

6+
# MySQL / Session / Redis configuration for ToC auth and project isolation
7+
DATABASE_PROVIDER=mysql
68
DB_HOST=localhost
79
DB_PORT=3306
810
DB_NAME=cube_pets_office
@@ -11,6 +13,25 @@ DB_PASSWORD=your_password_here
1113

1214
PORT=3001
1315
NODE_ENV=development
16+
CORS_ORIGIN=http://localhost:5173
17+
18+
SESSION_SECRET=replace_with_a_64_char_random_hex_secret
19+
SESSION_COOKIE_NAME=cube_office_session
20+
SESSION_TTL_DAYS=30
21+
22+
REDIS_ENABLED=false
23+
REDIS_HOST=localhost
24+
REDIS_PORT=6379
25+
REDIS_PASSWORD=your_redis_password_here
26+
REDIS_DB=2
27+
REDIS_KEY_PREFIX=cube:pets:office:
28+
29+
QUEUE_REDIS_ENABLED=false
30+
QUEUE_REDIS_HOST=localhost
31+
QUEUE_REDIS_PORT=6379
32+
QUEUE_REDIS_PASSWORD=your_queue_redis_password_here
33+
QUEUE_REDIS_DB=3
34+
QUEUE_REDIS_KEY_PREFIX=cube:pets:office:queue:
1435

1536
LLM_API_KEY=your_api_key_here
1637
LLM_BASE_URL=https://api.openai.com/v1

‎.kiro/specs/admin-audit-and-support-operations/design.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# 设计文档：Admin Audit And Support Operations
2+
3+
## 设计概述
4+
5+
本 spec 是管理员后台的后置增强，聚焦高风险运营动作和审计。基础原则是：能看不代表能改；能改必须有原因、确认、审计和最小权限。
6+
7+
## 管理员分级
8+
9+
```ts
10+
type AdminCapability =
11+
| "admin:user:disable"
12+
| "admin:user:restore"
13+
| "admin:project:archive"
14+
| "admin:run:retry"
15+
| "admin:evidence:export"
16+
| "admin:audit:read";
17+
18+
const ADMIN_CAPABILITIES = {
19+
admin: [
20+
"admin:user:disable",
21+
"admin:project:archive",
22+
"admin:run:retry",
23+
"admin:audit:read",
24+
],
25+
super_admin: [
26+
"admin:user:disable",
27+
"admin:user:restore",
28+
"admin:project:archive",
29+
"admin:run:retry",
30+
"admin:evidence:export",
31+
"admin:audit:read",
32+
],
33+
};
34+
```
35+
36+
第一阶段可以只用简单 role 判断；如果后台动作继续增加，再引入 capability helper。
37+
38+
## 审计模型
39+
40+
```ts
41+
interface AdminAuditLog {
42+
id: string;
43+
actorUserId: string;
44+
actorRole: "admin" | "super_admin";
45+
action: string;
46+
targetType: "user" | "project" | "run" | "artifact" | "evidence" | "system";
47+
targetId: string;
48+
projectId?: string;
49+
reason?: string;
50+
requestId?: string;
51+
ip?: string;
52+
userAgent?: string;
53+
result: "allowed" | "denied" | "failed";
54+
detail?: Record<string, unknown>;
55+
createdAt: string;
56+
}
57+
```
58+
59+
审计日志只允许追加，不允许更新和删除。
60+
61+
## API 草案
62+
63+
```text
64+
POST /api/admin/users/:userId/disable
65+
POST /api/admin/users/:userId/restore
66+
POST /api/admin/projects/:projectId/archive
67+
POST /api/admin/runs/:runId/retry
68+
POST /api/admin/runs/:runId/mark-handled
69+
GET /api/admin/evidence/:evidenceId
70+
POST /api/admin/evidence/:evidenceId/export
71+
GET /api/admin/audit
72+
```
73+
74+
所有写操作请求体都必须包含 `reason`。
75+
76+
## 高风险操作确认
77+
78+
前端执行禁用用户、恢复用户、归档项目、重跑任务、导出 evidence 时，应展示确认弹层，并要求填写或选择原因。服务端不信任前端确认状态，只检查 `reason` 和权限。
79+
80+
## 脱敏策略
81+
82+
后台列表可默认展示脱敏邮箱：
83+
84+
```text
85+
alice@example.com -> a***e@example.com
86+
```
87+
88+
运行日志、artifact preview 和 evidence detail 可在服务端提供 `redacted` 字段。完整内容导出需要更高权限，并记录 `admin:evidence:export` 审计。
89+
90+
## 支持排障边界
91+
92+
管理员不直接 impersonate 普通用户。排障页面通过只读 project bundle、run detail、evidence timeline 和 audit log 还原上下文。需要代用户修改项目时，应另开明确的 support action，并记录原因。
93+
94+
## 与前置 spec 的关系
95+
96+
- 依赖 `consumer-email-auth-and-account` 提供用户、角色和禁用状态。
97+
- 依赖 `personal-project-ownership-and-isolation` 提供项目 owner 和资源边界。
98+
- 依赖 `admin-console-and-global-role-gate` 提供后台入口和只读后台视图。
99+
100+
## 非目标
101+
102+
不引入租户级后台、不引入部门岗位、不引入工单系统、不引入复杂审批流、不改变普通用户的项目所有权规则。

‎.kiro/specs/admin-audit-and-support-operations/requirements.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# 需求文档：Admin Audit And Support Operations
2+
3+
## 目标
4+
5+
在管理员后台基础可视化之后，补充真实运营动作和强审计能力。该 spec 为后置可选项，只有当后台需要执行禁用用户、归档违规项目、重跑失败任务、导出证据等动作时才进入实施。
6+
7+
## 背景
8+
9+
`admin-console-and-global-role-gate` 第一阶段主要解决“管理员能看后台”。当系统进入真实运营后，管理员还需要有限度地干预用户和项目。由于这些动作风险高，必须有明确权限、确认、审计和回滚边界。
10+
11+
## 需求
12+
13+
### 需求 1：管理员操作分级
14+
15+
系统应区分只读管理员、运营管理员和超级管理员能力。第一阶段可用 `admin` 与 `super_admin` 分级表达。
16+
17+
### 需求 2：禁用和恢复用户
18+
19+
管理员应能禁用违规或异常用户；超级管理员应能恢复用户。被禁用用户不能登录或访问受保护接口。
20+
21+
### 需求 3：项目归档
22+
23+
管理员应能归档违规、异常或测试项目。项目归档不应物理删除证据链。
24+
25+
### 需求 4：失败任务处理
26+
27+
管理员应能查看失败任务详情，并根据权限执行重试、标记已处理或生成排障记录。
28+
29+
### 需求 5：证据查看与导出
30+
31+
管理员应能查看项目 evidence 和 artifact。导出敏感证据时必须记录审计事件，并根据需要脱敏。
32+
33+
### 需求 6：不可篡改审计
34+
35+
管理员关键操作必须记录到审计日志，包含操作者、目标、动作、原因、结果、时间、请求来源和关联项目。审计日志不允许普通更新或删除。
36+
37+
### 需求 7：操作确认
38+
39+
高风险动作必须要求二次确认，并记录确认原因。
40+
41+
### 需求 8：敏感信息脱敏
42+
43+
后台展示和导出用户邮箱、日志、artifact preview、runtime detail 时，应支持敏感字段脱敏策略。
44+
45+
### 需求 9：支持排障
46+
47+
管理员应能围绕用户、项目、任务和 evidence 构建排障上下文，避免直接进入用户个人工作台 impersonation。
48+
49+
### 需求 10：非目标
50+
51+
本 spec 不做计费、订阅、客服工单系统、项目协作成员、租户组织管理或复杂审批流。

‎.kiro/specs/admin-audit-and-support-operations/tasks.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# 任务清单：Admin Audit And Support Operations
2+
3+
- [ ] 定义 `AdminAuditLog` 类型和只追加持久化策略
4+
- [ ] 定义后台操作 capability helper，区分 `admin` 和 `super_admin`
5+
- [ ] 为管理员写操作增加 `reason` 校验
6+
- [ ] 实现禁用用户接口，并写入审计日志
7+
- [ ] 实现恢复用户接口，仅允许 `super_admin` 调用
8+
- [ ] 实现管理员归档项目接口，不物理删除项目证据链
9+
- [ ] 实现失败任务重试接口，并记录操作者和原因
10+
- [ ] 实现失败任务标记已处理接口
11+
- [ ] 实现管理员 evidence 查看接口，默认返回脱敏内容
12+
- [ ] 实现 evidence 导出接口，仅允许高权限管理员调用并记录审计
13+
- [ ] 新增后台高风险动作确认 UI，要求填写或选择原因
14+
- [ ] 新增后台审计详情页，支持按 actor、target、action、project 和时间筛选
15+
- [ ] 为用户邮箱、日志、artifact preview 和 evidence detail 增加脱敏 helper
16+
- [ ] 补充测试，覆盖权限分级、reason 必填、审计只追加、禁用用户无法登录、导出审计记录
17+
- [ ] 在文档中声明本 spec 为后置可选，不阻塞 ToC 登录和个人项目隔离 MVP

‎.kiro/specs/admin-console-and-global-role-gate/design.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# 设计文档：Admin Console And Global Role Gate
2+
3+
## 设计概述
4+
5+
本 spec 为 ToC 产品增加管理员后台。用户侧仍以“我的项目”为主，后台作为独立运营视角存在。第一阶段采用全局角色 gate：`user` 不能访问，`admin` 和 `super_admin` 可以访问。
6+
7+
## 角色判断
8+
9+
```ts
10+
type UserRole = "user" | "admin" | "super_admin";
11+
12+
function isAdmin(user: CurrentUser | undefined) {
13+
return user?.role === "admin" || user?.role === "super_admin";
14+
}
15+
```
16+
17+
服务端中间件：
18+
19+
```ts
20+
function requireAdmin(req, res, next) {
21+
if (!req.user) {
22+
return res.status(401).json({ success: false, error: "Authentication required" });
23+
}
24+
25+
if (req.user.role !== "admin" && req.user.role !== "super_admin") {
26+
return res.status(403).json({ success: false, error: "Admin privileges required" });
27+
}
28+
29+
next();
30+
}
31+
```
32+
33+
## 路由与 API
34+
35+
前端路由：
36+
37+
```text
38+
/admin
39+
/admin/users
40+
/admin/users/:userId
41+
/admin/projects
42+
/admin/projects/:projectId
43+
/admin/runs
44+
/admin/failures
45+
/admin/audit
46+
```
47+
48+
服务端 API：
49+
50+
```text
51+
GET /api/admin/summary
52+
GET /api/admin/users
53+
GET /api/admin/users/:userId
54+
GET /api/admin/projects
55+
GET /api/admin/projects/:projectId
56+
GET /api/admin/runs
57+
GET /api/admin/failures
58+
GET /api/admin/audit
59+
```
60+
61+
所有 `/api/admin/*` 先走 `requireAuth`，再走 `requireAdmin`。后台第一阶段复用同一套 DB-backed session，不新增 `admin_session`、`AdminTokenService` 或独立 admin token。
62+
63+
## 后台菜单
64+
65+
后台菜单第一阶段写死：
66+
67+
- Overview
68+
- Users
69+
- Projects
70+
- Runs
71+
- Failures
72+
- Audit
73+
74+
不引入 `Menu` 表，不引入 role-menu 关系，不迁移 web-main 的 `/system/menus`。
75+
76+
## 页面职责
77+
78+
### Overview
79+
80+
展示用户数、项目数、运行中任务、失败任务、最近异常和系统健康摘要。
81+
82+
### Users
83+
84+
展示用户列表和详情。第一阶段以查看为主，禁用/恢复用户等写操作由后置运营 spec 承接。
85+
86+
### Projects
87+
88+
展示全局项目列表和详情。管理员可查看项目上下文、owner、状态、spec、route、mission、artifact 和 evidence 摘要。
89+
90+
### Runs / Failures
91+
92+
展示运行任务、失败任务、等待接管任务和最近执行轨迹，用于运营排障。
93+
94+
### Audit
95+
96+
展示基础审计日志。更完整的不可篡改审计、导出和敏感操作记录由后置 spec 承接。
97+
98+
## 前端入口
99+
100+
应用 shell 通过 `isAdmin(currentUser)` 判断是否展示后台入口。普通用户看不到入口；即使手动输入 URL，也由路由守卫和服务端 API 拒绝。
101+
102+
## 与 web-main 的取舍
103+
104+
可参考：
105+
106+
- `access.ts` 的 route gate 思路
107+
- `getCurrentUser` / `currentUser.roles` 的用户上下文
108+
- `/system/users`、`/system/operation-logs`、`/system/monitor` 的后台信息架构
109+
110+
不迁移：
111+
112+
- 独立 admin token / admin_session 双会话体系
113+
- 动态菜单树
114+
- 菜单 CRUD
115+
- 角色管理页
116+
- 权限管理页
117+
- 租户、部门、岗位、用户组
118+
- 数据权限配置
119+
120+
## 非目标
121+
122+
本 spec 不处理项目 owner 隔离本身，不处理登录注册，不处理管理员禁用用户、删除项目、重跑任务和导出 evidence 等高风险操作。

‎.kiro/specs/admin-console-and-global-role-gate/requirements.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# 需求文档：Admin Console And Global Role Gate
2+
3+
## 目标
4+
5+
为 ToC 形态的 Cube Pets Office 增加管理员后台入口。普通用户只进入个人项目工作台；`admin` 和 `super_admin` 才能看到并访问后台，用于查看用户、项目、运行状态和基础运营信息。
6+
7+
## 背景
8+
9+
用户侧产品主线是个人 Project-first 工作台，不应暴露企业后台概念。管理员后台是运营和支持视角，应与普通用户导航分离。`web-main` 的动态菜单和 `/system/*` 页面可作为后台信息架构参考，但第一阶段不迁移菜单管理、角色管理和权限矩阵。
10+
11+
## 需求
12+
13+
### 需求 1：管理员角色识别
14+
15+
系统应根据当前用户全局角色判断是否为管理员。`admin` 和 `super_admin` 可以访问后台；`user` 不能访问后台。
16+
17+
### 需求 2：后台入口可见性
18+
19+
普通用户登录后不应看到后台入口。管理员登录后应在应用 shell 中看到后台入口。
20+
21+
### 需求 3：后台路由保护
22+
23+
所有 `/admin/*` 路由必须受 `requireAdmin` 保护。普通用户直接访问后台地址时应被拒绝或跳转。
24+
25+
### 需求 4：后台菜单
26+
27+
第一阶段后台菜单可写死，不需要数据库动态菜单。菜单至少覆盖用户、项目、运行、异常和基础审计入口。
28+
29+
### 需求 5：用户管理视图
30+
31+
管理员应能查看用户列表和用户详情，包括邮箱、角色、状态、创建时间、最后登录时间和项目数量。
32+
33+
### 需求 6：项目管理视图
34+
35+
管理员应能查看全局项目列表和项目详情。项目详情以运营只读为主，展示 owner、状态、spec/route/execution/evidence 摘要。
36+
37+
### 需求 7：运行监控视图
38+
39+
管理员应能查看全局运行任务、失败任务、等待接管任务和最近执行状态。
40+
41+
### 需求 8：后台 API 隔离
42+
43+
后台 API 应使用 `/api/admin/*` 命名空间，并和普通 `/api/projects` 用户接口分离，避免管理员全局能力泄漏到普通用户路径。
44+
45+
### 需求 9：基础审计
46+
47+
管理员访问后台和执行关键后台动作时，应记录操作者、动作、目标、时间和结果。完整审计治理由后置 spec 承接。
48+
49+
### 需求 10：非目标
50+
51+
本阶段不做动态菜单 CRUD、角色权限管理页、租户管理、部门岗位管理、数据范围规则和复杂 support 分级操作。

0 commit comments

Comments
 (0)