Scert/.claude/docs/ai/project-members/api-handoff-v2.md

90 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Scert 项目入口与成员页面接口交接
## 本版范围
本版接续 `api-handoff.md` 的成员列表、授予和撤销接口,新增当前账户可见项目入口以及成员页面。管理员通过“项目与成员”导航进入,普通用户通过用户中心的同名板块进入;普通用户担任项目管理员时无需进入全局管理员控制台。
项目创建、编辑、删除,以及域名、证书、服务器、DNS 和排队任务的完整权限链不属于已完成内容。前端测试和构建不代表浏览器验收,更不代表生产验收。
## GET /api/v1/projects
用途:从服务端读取当前真实账户有权访问的项目,前端不得先读取全量项目再自行过滤,也不得固定使用默认项目。
认证:正式会话 Cookie;同源发送。身份仅来自会话,账户状态、全局角色与当前项目成员关系由同一条 SQL 实时查询。只有有效超级管理员可见所有项目;普通管理员和普通用户只可见自己有合法项目角色的项目。分组关系不隐式授予权限。
请求示例:
```http
GET /api/v1/projects?page_size=5&after=project-a
```
| 参数 | 类型 | 约束 |
|---|---|---|
| `page_size` | 整数 | 默认 10,允许 5、10、15、30;页面项目列表默认选 5 |
| `after` | 字符串 | 默认空;使用上页 `next_cursor`,只允许 1~128 位 ASCII 字母、数字、连字符或下划线 |
重复参数、未知参数、非法转义或无效页大小返回 400,不接受操作者 ID 或角色参数。按项目 ID 升序做游标分页,无总数和任意页码跳转;同一账户在项目内具有多个角色不会重复返回项目。
成功响应:
```json
{
"items": [
{
"id": "project-b",
"name": "测试项目",
"description": "项目说明",
"can_manage_members": true
}
],
"page_size": 5,
"has_more": false,
"next_cursor": ""
}
```
- `items` 始终为数组;有效账户没有可见项目或请求末尾之后的游标,返回空数组。
- `can_manage_members` 仅表示本次查询时的页面能力提示,不是后续调用的授权凭据;成员接口继续独立判权。
- 不返回项目成员目录、邮箱、密码摘要或账户分组。
- 项目列表与成员接口的所有响应均设置 `Cache-Control: private, no-store` 和 `Vary: Cookie`,包括未认证和权限拒绝响应;前端请求同时使用 `cache: no-store`。
- 只有存在更多数据时 `has_more` 为真,`next_cursor` 才包含本页最后项目 ID。
### 错误边界
错误格式沿用 `{"error":"中文提示","request_id":"请求编号"}`。
| 状态码 | 含义与前端行为 |
|---|---|
| 400 | 参数无效;不重复提交原参数 |
| 401 | 会话无效;清空旧数据并跳转登录 |
| 403 | 会话验证后账户状态或角色已不允许读取;清空旧项目,不伪装空列表 |
| 409 | 系统尚未初始化;不解释为合法空项目 |
| 500 | 查询失败;仅显示稳定中文信息和安全的请求编号,不显示数据库原始错误 |
| 503 | 项目仓储未接入;不能当作没有项目 |
## 成员页面交互
1. 先获取可见项目,再选择实际返回的项目;仅在 `can_manage_members` 为真时请求成员和账户建议。
2. 成员使用既有账户游标分页,默认每页 10,允许 5、10、15、30;一个账户的多个角色合并展示。
3. 账户建议复用现有 `GET /api/v1/users` 权限边界,并合并本页有效成员的 ID、用户名;停用账户不加入授予建议。普通项目管理员不会因此读取全站账户列表。
4. 不在既有可见账户范围内的目标,填写对方提供的明确账户 ID;用户管理页面显示已有可见账户的 ID,普通用户可取得自己的 ID,不要求查看数据库。
5. 授予角色只提交 `user_id`、`role`;不提交操作者或全局角色。成功后重新读取第一页;409 保留输入、刷新成员并显示冲突,不乐观添加成员。
6. 撤销前显示账户与中文角色的确认栏;DELETE 不发送正文。撤销自己管理角色后,如果成员刷新返回 403,清空成员和账户建议,关闭继续修改能力;通过刷新项目重新获取能力提示。
7. 项目切换、分页更新和组件卸载均终止旧读取并使用请求代次防止迟到响应覆盖新状态。已提交的变更不能承诺被浏览器取消;旧项目变更响应不得刷新新项目或清空新表单。
8. 账户建议失败时允许手工填写账户 ID;成员读取失败显示错误而非伪造成功。网络故障显示中文;401 跳转登录;安全格式的 `request_id` 附在错误信息后。
## 实现与验证位置
- 仓储:`backend/internal/repository/project_directory.go`,与基础全量 `ProjectRepository.ListProjects` 分离。
- HTTP:`backend/internal/httpapi/project_directory_api.go`;应用通过独立 `ProjectDirectory` 依赖接线。
- 页面:`frontend/src/views/ProjectManagement/`,视图、样式、目录逻辑、成员逻辑与请求封装分开。
- 普通工作台:`frontend/src/views/UserManagement/UserWorkspace.vue`/`.js`/`.css`,账户与项目单板块显示。
- 正式测试:项目目录仓储、HTTP 边界、实际应用登录接线及 `ProjectManagement.test.js`;最终命令、条件跳过与验收缺口以支持矩阵第二十四节为准。
## 尚未完成
- [ ] 项目创建、编辑、删除及相关事务审计。
- [ ] 本批页面的真实浏览器布局与交互验收。
- [ ] 全部资源入口与排队任务的执行、取消、重试权限重判。
- [ ] PostgreSQL 当前实库、Linux 原生与完整生产部署验收。