# 账户分享功能开发计划

## 1. 项目目标

开发一个“账户公开分享”功能，允许用户把自己的模拟盘/观察账户生成一个可公开访问的页面，用于社交传播、围观讨论和 AI 自动交易研究展示。

目标不是把后台账户页直接公开，而是做一个适合外部访问的公开观察页：

- 首屏能快速看懂账户表现
- 能看到最近交易和持仓结构
- 能看到 AI 决策摘要
- 默认安全、可控披露、可撤销

---

## 2. 交付目标

外包团队需完成一个可上线的 Django 功能模块，包含：

1. 后端分享链接管理能力
2. 公开分享页面
3. 快照数据生成机制
4. 披露权限控制
5. 可选密码保护、过期、撤销等安全控制
6. 基础访问统计
7. 必要测试和交付文档

---

## 3. 使用场景

### 场景 1：用户对外分享

用户在登录态下，为某个账户创建一个分享链接，设置展示粒度后，将链接发到微信群、X、即刻等平台。

### 场景 2：访客围观

未登录访客打开链接后，可以查看该账户的公开信息，包括收益、持仓结构、最近交易、AI 决策摘要。

### 场景 3：受控分享

用户可对分享链接设置：

- 可选密码保护
- 过期时间
- 最大访问次数
- 撤销
- 更换公开码

---

## 4. 范围定义

### 本期必须交付

- 分享链接创建、编辑、撤销、换码
- 公开分享页面
- 分享快照生成和读取
- 三档披露级别
- 首屏摘要区
- 收益曲线
- 持仓展示
- 最近交易展示
- 决策摘要展示
- 可选密码保护
- 过期控制
- 最大访问次数控制
- 访问日志
- Open Graph 元信息

### 本期不做

- 评论系统
- 公开广场
- 订阅通知
- 分享页点赞/收藏
- 搜索引擎收录
- 多账户榜单
- 复杂社交裂变机制
- AI 原始长推理全文公开展示

---

## 5. 产品要求

### 5.1 页面定位

页面风格要更接近“公开观察页 / 实验页”，不能做成 Django 后台页面或纯管理报表页面。

### 5.2 页面结构

公开分享页按以下顺序展示：

1. Hero 首屏摘要
2. 核心指标卡片
3. 收益曲线与回撤
4. 当前持仓与分布
5. 最近交易动态
6. AI 决策摘要
7. 风险提示与免责声明

### 5.3 首屏必须展示的信息

- 账户标题
- 副标题
- 账户类型标签：模拟 / 实盘 / 观察组合
- 最近更新时间
- 累计收益率
- 最近 7 日收益率
- 最近 30 日收益率
- 当前仓位
- 一个明显 CTA：查看最近交易 / 查看 AI 最近操作

### 5.4 社交传播要求

- 页面首屏在手机端应适合截图传播
- 页面需支持 Open Graph 标题、描述、缩略摘要
- 页面打开 5 秒内应能理解账户近况

---

## 6. 披露级别设计

外包团队按以下三档实现：

### `snapshot`

适合公开传播。

- 展示收益率、仓位、分布图
- 展示最近交易摘要
- 不展示具体金额
- 不展示完整持仓数量
- 不展示深层决策证据

### `observer`

适合熟人围观。

- 展示持仓明细
- 展示最近交易记录
- 展示部分决策摘要
- 允许隐藏金额

### `research`

适合研究用途。

- 展示更完整决策摘要
- 展示证伪逻辑摘要
- 展示结构化特征摘要
- 默认建议启用过期时间，密码保护由用户自选

---

## 7. 技术实现要求

### 7.1 应用结构

新增 Django app：`apps/share/`

目录建议如下：

```text
apps/share/
├── domain/
│   ├── entities.py
│   └── services.py
├── application/
│   ├── use_cases.py
│   └── dtos.py
├── infrastructure/
│   ├── models.py
│   ├── repositories.py
│   └── snapshot_service.py
└── interface/
    ├── views.py
    ├── serializers.py
    ├── urls.py
    └── api_urls.py
```

如果外包团队认为不需要严格分层，可以做轻量实现，但必须满足：

- 模型、业务逻辑、接口层职责清晰
- 公开页与后台管理接口隔离
- 快照生成逻辑独立封装

### 7.2 数据读取原则

公开页默认读取 `ShareSnapshot`，而不是直接联查原始业务表。

原因：

- 减少公开访问对主业务表压力
- 提高页面稳定性
- 避免外部访问触发复杂联表
- 保证公开内容可复现

### 7.3 兼容现有模块

需对接现有数据来源：

- `apps.simulated_trading`
- `apps.decision_rhythm`
- `apps.signal`
- 如有必要，对接 `apps.alpha`

外包团队不得大范围重构现有模块，只能在兼容前提下增加读取与聚合逻辑。

---

## 8. 数据模型要求

### 8.1 ShareLink

建议字段：

- `id`
- `owner`
- `account_id`
- `short_code`
- `title`
- `subtitle`
- `share_level`
- `status`
- `password_hash`
- `expires_at`
- `max_access_count`
- `access_count`
- `last_snapshot_at`
- `last_accessed_at`
- `allow_indexing`
- `show_amounts`
- `show_positions`
- `show_transactions`
- `show_decision_summary`
- `show_decision_evidence`
- `show_invalidation_logic`
- `created_at`
- `updated_at`

要求：

- `allow_indexing` 默认 `False`
- 默认关闭金额展示
- 默认链接状态为 `active`
- 支持 `revoked`、`expired`、`disabled`

### 8.2 ShareSnapshot

建议字段：

- `id`
- `share_link`
- `snapshot_version`
- `summary_payload`
- `performance_payload`
- `positions_payload`
- `transactions_payload`
- `decision_payload`
- `generated_at`
- `source_range_start`
- `source_range_end`

要求：

- 以 JSON 字段存储公开页渲染数据
- 至少保留最新一份快照
- 结构需要可扩展

### 8.3 ShareAccessLog

建议字段：

- `id`
- `share_link`
- `accessed_at`
- `ip_hash`
- `user_agent`
- `referer`
- `is_verified`
- `result_status`

要求：

- 不直接明文保存 IP
- 能统计访问来源和访问成功情况

---

## 9. 安全要求

### 9.1 短码要求

不得使用“可枚举的短数字 ID”或过短随机码。

建议：

- 使用不可预测的随机字符串作为主识别码
- 长度建议 8 位以上
- 如需要可读 slug，仅作展示，不作主查找键

推荐路径：

- `/s/{code}/`
- 可选展示路径：`/s/{code}/{slug}/`

### 9.2 密码要求

密码保护是可选项，不是默认要求。

- 默认公开链接可直接访问
- 用户可自行开启密码保护
- 使用 Django 标准 password hasher
- 不要手写 SHA-256 存储
- 验证接口必须限流
- 密码校验通过后需建立短期受限访问态

### 9.3 默认保护要求

- 默认不展示真实金额
- 默认不展示账户敏感标识
- 默认不允许搜索引擎收录
- 撤销后公开页必须不可访问
- 过期后公开页必须不可访问

### 9.4 合规提示

公开页底部必须展示：

- 仅供研究交流，不构成投资建议
- 历史表现不代表未来收益
- 页面数据可能存在延迟
- 页面内容经过脱敏与摘要处理

---

## 10. 页面展示要求

### 10.1 Hero 首屏

字段要求：

- 标题
- 副标题
- 账户标签
- 最近更新时间
- 累计收益率
- 近 7 日收益率
- 近 30 日收益率
- 当前仓位

### 10.2 核心指标区

至少展示：

- 累计收益率
- 近 7 日收益率
- 近 30 日收益率
- 最大回撤
- 当前仓位
- 正收益周期占比或胜率

### 10.3 收益图表区

至少展示：

- 收益曲线
- 回撤信息
- 可选基准对比

### 10.4 持仓区

至少展示：

- 当前持仓列表或卡片
- 仓位占比
- 行业或主题分布

### 10.5 最近交易区

按时间倒序展示最近交易动态，每条至少包含：

- 时间
- 动作
- 标的
- 仓位变化或交易摘要
- 一句话原因

### 10.6 决策摘要区

至少展示：

- AI 看到了什么
- AI 做了什么判断
- AI 采取了什么动作
- 在什么条件下判断失效

要求：

- 默认展示摘要层
- 深层证据按披露级别决定是否展示

---

## 11. 后端接口要求

### 11.1 管理端接口

建议至少提供以下接口：

- `GET /api/share/links/`
- `POST /api/share/links/`
- `GET /api/share/links/{id}/`
- `PATCH /api/share/links/{id}/`
- `POST /api/share/links/{id}/revoke/`
- `POST /api/share/links/{id}/rotate/`
- `POST /api/share/links/{id}/refresh-snapshot/`
- `GET /api/share/links/{id}/stats/`
- `GET /api/share/links/{id}/preview/`

说明：

- 管理端统一用内部 `id`，不要用 `short_code` 做后台主键
- 所有管理接口必须要求登录
- 用户只能管理自己的分享链接

### 11.2 公开访问接口

- `GET /s/{code}/`
- `GET /s/{code}/data/`
- `POST /s/{code}/verify/`

要求：

- 未开启密码保护时可直接访问公开数据
- 已开启密码保护时，未验证前不可返回受保护数据
- 公开接口要有节流和异常兜底

---

## 12. 前端实现要求

### 12.1 技术要求

- 复用现有 Django Template 体系
- 图表优先复用现有 ECharts
- 复用现有 `design-tokens.css`

### 12.2 视觉要求

- 不得直接套用后台页面样式
- 要更像“公开展示页”
- 移动端优先
- 核心指标层级清晰
- 支持手机截图传播

### 12.3 模板建议

建议模板路径：

```text
core/templates/share/
├── public_share.html
├── partials/
│   ├── hero.html
│   ├── metrics.html
│   ├── performance_chart.html
│   ├── positions.html
│   ├── transactions.html
│   ├── decision_summary.html
│   └── disclaimer.html
└── password_modal.html
```

---

## 13. 快照机制要求

### 13.1 生成时机

至少支持以下两种刷新方式：

- 用户手动刷新
- 链接创建/编辑后自动刷新

可选：

- 定时任务刷新
- 关键交易后自动刷新

### 13.2 快照内容

快照需包含公开页所需完整渲染数据，不应只保存 ID 引用。

### 13.3 失败处理

若快照生成失败：

- 不应影响已有可用快照访问
- 管理端应返回明确错误信息
- 需要记录日志

---

## 14. 测试要求

外包团队必须交付测试，不接受“只手测无自动化”。

### 14.1 后端测试

至少覆盖：

- 创建分享链接
- 更新分享配置
- 撤销链接
- 过期控制
- 最大访问次数控制
- 可选密码校验
- 公开页访问
- 快照生成
- 访问日志记录
- 用户权限隔离

### 14.2 前端/页面测试

至少完成：

- 公开页主流程手测
- 手机端布局检查
- 密码保护开启时的访问流程检查
- 首屏展示完整性检查

### 14.3 回归要求

不得破坏现有：

- `simulated_trading` 页面
- `decision_rhythm` 相关读取逻辑
- 已有账户页面

---

## 15. 验收标准

### 功能验收

1. 登录用户可创建分享链接
2. 用户可配置标题、副标题、披露级别和安全选项
3. 未登录访客可访问公开页
4. 用户可自选是否开启密码保护
5. 受密码保护链接在验证前不可查看主体数据
6. 撤销后链接失效
7. 过期后链接失效
8. 更换短码后旧链接失效
9. 分享页能展示收益、持仓、交易、决策摘要

### 体验验收

1. 手机端首屏可清楚展示账户摘要
2. 页面风格明显区别于后台管理页
3. 图表加载正常
4. 页面适合截图和社交传播

### 技术验收

1. 所有接口权限正确
2. 随机短码不可轻易枚举
3. 默认不泄露金额与敏感标识
4. 公开页主要读取快照，不直接压主业务查询
5. 有基础自动化测试

---

## 16. 建议排期

按 1 名后端 + 1 名前端估算，建议开发周期：

### 第一阶段：后端基础能力，3-4 个工作日

- 模型
- 迁移
- 管理接口
- 快照生成
- 权限和安全控制

### 第二阶段：公开页实现，3-4 个工作日

- 模板
- 图表
- 响应式布局
- 密码验证流程

### 第三阶段：联调和测试，2-3 个工作日

- 数据联调
- 异常处理
- 自动化测试
- 修复问题

总计建议：`8-11 个工作日`

---

## 17. 外包交付物清单

外包团队最终需交付：

1. 完整代码
2. Django migration 文件
3. 接口说明
4. 测试代码
5. 手工验收说明
6. 涉及配置项说明
7. 已知限制说明

---

## 18. 开发约束

- 不得大改现有项目架构
- 不得破坏现有模块 URL 和页面
- 不得引入过重前端框架
- 不得把公开页直接建立在后台复杂联表查询上
- 优先复用现有样式、图表和 Django 基础设施

---

## 19. 备注给外包团队

这个功能的重点不是“把账户后台公开出来”，而是做一个适合外部围观和社交传播的公开观察页。

因此请优先保证：

- 首屏可读性
- 披露控制
- 页面稳定性
- 手机端效果
- 默认安全

如果实现过程中出现“数据完整性”和“公开展示可读性”冲突，优先保证公开展示可读性，但不能突破安全边界。
