8000 添加页面 by hkxiaoyao · Pull Request #2 · xiaozhou26/icloud-hme · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .ccg/tasks/archive/2026-08/add-management-ui-plan/context.jsonl
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{"path":"main.go","reason":"程序入口、监听参数、Manager 与 Server 组装位置"}
{"path":"internal/server/server.go","reason":"全部现有 HTTP 路由、响应结构与 handler"}
{"path":"internal/account/manager.go","reason":"账号持久化、敏感字段、客户端工厂与并发边界"}
{"path":"internal/hme/auth.go","reason":"iCloud 密码登录与 OTP 错误语义"}
{"path":"internal/hme/client.go","reason":"Alias、CreateResult 与 HME 操作契约"}
{"path":"internal/mail/client.go","reason":"邮件摘要结构与 IMAP 查询"}
{"path":"internal/mail/web_client.go","reason":"Web API 邮件回退路径"}
{"path":"Dockerfile","reason":"当前仅 Go 的镜像构建流程"}
{"path":"build.sh","reason":"当前本地单二进制构建流程"}
{"path":".github/workflows/release.yml","reason":"多平台二进制与容器发布流程"}
{"path":"README.md","reason":"部署、配置和现有功能说明"}
{"path":"API.md","reason":"现有 API 请求响应约定"}
{"path":"accounts.json.template","reason":"已与当前 Manager JSON 结构不一致的模板"}
{"path":".gitignore","reason":"当前忽略 docs 与 JavaScript,影响计划和前端文件"}
9 changes: 9 additions & 0 deletions .ccg/tasks/archive/2026-08/add-management-ui-plan/plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# 计划位置

完整、可执行计划保存在:

`docs/superpowers/plans/2026-08-04-add-management-ui.md`

该文件包含目标架构、冻结的 API 契约、精确文件职责、10 个顺序任务、70 个测试驱动步骤、提交边界、CI/Release/Docker 改造以及最终验收矩阵。

本任务只制定计划,不实施业务代码。执行者应从 Task 1 顺序执行,不得跳过安全与测试任务。
64 changes: 64 additions & 0 deletions .ccg/tasks/archive/2026-08/add-management-ui-plan/requirements.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# 管理界面增强需求

## 用户目标

为现有 `icloud-hme` Go/Gin 服务制定一份可直接交给 DeepSeek 执行的管理界面实施计划。本次任务只产出计划,不修改业务代码。

## 对“界面管理”的落地解释

- 在服务根路径 `/` 提供中文单管理员 Web 控制台。
- 覆盖现有账号、Cookie、iCloud 登录、App Password、别名和收件箱能力。
- 保持发布物为一个自包含 Go 二进制;前端产物在构建时通过 `go:embed` 打入二进制。
- 前端与 API 同源部署,不增加 CORS,不依赖 CDN、远程字体或外部分析脚本。
- 桌面浏览器优先,同时保证窄屏下能够完成全部操作。

## 安全基线

- 所有业务 API 必须先通过管理员会话认证;管理员密码只从 `ICLOUD_HME_ADMIN_PASSWORD` 环境变量读取。
- 浏览器会话使用随机、HttpOnly、SameSite=Strict Cookie;所有状态变更请求验证 CSRF Token。
- 登录失败需要限流;API 和静态页面需要合理的安全响应头。
- API 响应不得返回 Cookie、App Password、iCloud 登录密码或含凭据的代理 URL。
- 前端不得把上述秘密写入 localStorage、sessionStorage、URL、日志或错误消息,提交后立即清空输入状态。
- 邮件摘要仅作为文本渲染,禁止使用 `dangerouslySetInnerHTML`。

## 功能范围

1. 管理员登录、会话恢复、退出。
2. 账号列表、添加、编辑基本信息、删除。
3. 更新 Cookie、设置/替换 App Password、使用 iCloud 密码和可选 OTP 登录。
4. 按账号列出别名、创建别名、停用、重新激活、删除。
5. 按账号和可选别名查看邮件摘要,控制 `limit` 与 `days`。
6. 对加载、空数据、失败、重试、破坏性确认和操作成功提供明确反馈。
7. 更新本地构建、Docker、GitHub Release、CI 和用户文档。

## 明确不做

- 多管理员、RBAC、OAuth/SSO、找回密码。
- 新数据库、跨实例共享会话、审计日志平台。
- 邮件正文/附件查看、富 HTML 渲染、发信。
- 修改或重新设计 iCloud/SRP/IMAP 协议实现。
- 跨域部署前后端或兼容旧浏览器。

## 已发现的现状风险

- `internal/server/server.go` 当前未保护任何 `/api` 路由。
- `loginAccount` 会把 `client.Cookies` 原样返回。
- `account.Manager.ListAccounts` 只清空 `Cookies`,仍可能序列化 `AppPassword` 和带账号密码的 `Proxy`。
- `AddAccount` 未接收 `icloud_email`,导致无 Cookie 新账号难以直接进入密码登录流程。
- `listInbox` 忽略无效整数输入,未限制 `limit`、`days` 的范围。
- `Manager` 在释放互斥锁后继续读写共享 `Account` 指针和 Cookie map;管理界面增加并发请求后需要通过 `go test -race` 验证。
- 当前没有 Go 测试、前端工程或 CI 检查;Docker/Release 也没有 Node 构建阶段。
- `.gitignore` 忽略所有 `docs/` 与 `*.js`,新增计划和前端配置必须显式处理。

## 假设与兼容性决策

- 接受一次安全性驱动的破坏性变更:升级后所有业务 API 需要登录会话。
- 现有业务路由和字段命名尽量保持不变;不趁机重写为新的 REST 版本。
- 进程重启后会话失效是可接受的;会话只保存在内存。
- `ICLOUD_HME_SECURE_COOKIE=false` 仅用于本机 HTTP;经 TLS 反向代理部署时必须设为 `true`。
- 构建源码需要 Node.js 22.12+;已发布二进制运行时不需要 Node.js。

## 计划质量限制

- 2026-08-04 尝试按仓库规范并行调用 Gemini 与 Claude 做分析,但外部模型读取仓库的权限被安全策略拒绝;未绕过该限制。
- 最终计划由本地源码审查、官方技术文档核验和自审完成。
43 changes: 43 additions & 0 deletions .ccg/tasks/archive/2026-08/add-management-ui-plan/review.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# 计划自审结果

## 结论

计划可以交给 DeepSeek 按任务顺序执行。范围被拆成 10 个可独立测试和提交的任务,业务代码尚未修改。

## Spec coverage

- 管理员登录、会话恢复与退出:Task 2、3、6。
- 账号、Cookie、iCloud 登录、OTP、App Password 与代理:Task 1、3、7。
- 别名创建/列表/停用/激活/删除:Task 3、8。
- 收件箱筛选与邮件摘要:Task 3、9。
- 单二进制内嵌、SPA fallback:Task 4、5、10。
- 安全认证、CSRF、限流、脱敏、安全头、无 HTML 注入:Task 1–3、6–9。
10BC8 - Go/前端测试、竞态检测、CI、Docker、Release 与文档:Task 1–10。
- 明确排除多用户、数据库、邮件正文和 iCloud 协议重写:计划第 1.2 节与 DeepSeek 执行约束。

未发现需求缺口。

## Placeholder scan

- 未发现 `TBD`、`TODO`、`implement later`、`fill in details`、“类似 Task N”或“适当处理”等占位表达。
- 出现的 `./...` 均为 Go 包通配命令,不是内容占位。
- Docker 密码示例使用明确的不可照抄示例值,并要求文档标注更换。

## Type and contract consistency

- `account.Summary` 是唯一 HTTP 账号 DTO;`managerBackend` 把 Manager 方法适配为 handler 使用的 `Backend`。
- `AddAccountWithInput` → `Backend.AddAccount`、`UpdateMetadata` → `Backend.UpdateAccount` 的适配关系已明确。
- alias 保留 `anonymousId/createdAt`,create/inbox/account 保留现有 snake_case;前端类型按真实字段建模。
- CSRF Header、Cookie 名称、会话响应、错误码和环境变量在后端、前端、测试、文档任务中一致。
- Vite public 占位文件会在清空 dist 后复制回去,不会导致 tracked `placeholder.txt` 被删除。

## 风险审查

- Critical:当前匿名 API、登录响应 Cookie 泄露、ListAccounts 的 AppPassword/Proxy 泄露均被列为上线前阻断项。
- Warning:Manager 解锁后继续访问共享指针/map;Task 1 要求深拷贝并用 race detector 验证。
- Warning:当前无测试缝;Task 3 定义高层 Backend,所有 handler 测试离线。
- Info:引入 Node 构建会增加源码构建步骤;发布二进制运行时仍不需要 Node。

## 审查限制

按仓库规范尝试并行调用 Gemini 与 Claude,但外部模型读取仓库的授权被安全策略拒绝,未绕过。自审基于本地源码、官方 React/Vite/Vitest 文档以及计划内一致性检查完成。
13 changes: 13 additions & 0 deletions .ccg/tasks/archive/2026-08/add-management-ui-plan/task.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
{
"id": "add-management-ui-plan",
"title": "制定管理界面实施计划,供 DeepSeek 后续执行",
"status": "completed",
"complexity": "L+",
"risk": "high",
"domain": "fullstack",
"currentPhase": "completed",
"nextAction": "将 docs/superpowers/plans/2026-08-04-add-management-ui.md 交给 DeepSeek 顺序执行",
"createdAt": "2026-08-04T00:00:00Z",
"completedAt": "2026-08-04T00:00:00Z",
"branch": "main"
}
68 changes: 68 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
name: CI

on:
push:
branches: [main]
pull_request:

permissions:
contents: read

jobs:
web:
name: Web (lint + test + build)
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-node@v4
with:
node-version: '22'
cache: npm
cache-dependency-path: web/package-lock.json

- name: Install dependencies
run: npm --prefix web ci

- name: Lint
run: npm --prefix web run lint

- name: Test
run: npm --prefix web run test:run

- name: Build
run: npm --prefix web run build

- name: Upload dist for Go job
uses: actions/upload-artifact@v4
with:
name: webui-dist
8 path: internal/webui/dist/
if-no-files-found: error

go:
name: Go (test + vet + build)
runs-on: ubuntu-latest
needs: web
steps:
- uses: actions/checkout@v4

- uses: actions/setup-go@v5
with:
go-version: '1.26'
cache: true

- name: Download frontend dist
uses: actions/download-artifact@v4
with:
name: webui-dist
path: internal/webui/dist/

- name: Test
run: go test -race ./internal/... .

- name: Vet
run: go vet ./internal/... .

- name: Build
run: go build ./internal/... .
48 changes: 48 additions & 0 deletions .github/workflows/docker-image.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
name: Docker Image

on:
push:
branches: [main]
workflow_dispatch:

permissions:
contents: read
packages: write

jobs:
docker:
name: Build & push GHCR image
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: docker/setup-qemu-action@v3

- uses: docker/setup-buildx-action@v3

- name: Log in to ghcr.io
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}

- name: Docker meta
id: meta
uses: docker/metadata-action@v5
with:
images: ghcr.io/${{ github.repository }}
tags: |
type=raw,value=latest,enable={{is_default_branch}}
type=sha,prefix=sha-

- name: Build & push
uses: docker/build-push-action@v6
with:
context: .
push: true
platforms: linux/amd64
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=max
11 changes: 11 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,17 @@ jobs:
steps:
- uses: actions/checkout@v4

- uses: actions/setup-node@v4
with:
node-version: '22'
cache: npm
cache-dependency-path: web/package-lock.json

- name: Build frontend
run: |
npm --prefix web ci
npm --prefix web run build

- uses: actions/setup-go@v5
with:
go-version: '1.26'
Expand Down
5 changes: 4 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,12 @@
CLAUDE.md
# Claude sessions
/.claude/
*.js
docs/
.superpowers/
# Web frontend build output & deps
/web/node_modules/
/internal/webui/dist/*
!/internal/webui/dist/placeholder.txt
!capture_statsig_pair.js
!capture_statsig_pair_v5.js
# Temp / test files
Expand Down
Loading
Loading
0