updated_readme

README.md

@@ -1,86 +1,103 @@
 # CypherLegacy Backend
 
-CypherLegacy 是一个基于 FastAPI 构建的数字遗产继承系统后端。它允许用户安全地存储加密的数字资产，并指定在用户去世（被管理员确认状态）后可以由特定的继承人领取这些资产。
+CypherLegacy is a secure digital legacy inheritance system backend built with FastAPI. It allows users to safely store encrypted digital assets and designate specific heirs who can claim these assets after the user's status is confirmed as "deceased" by an administrator.
 
-## 🌟 核心功能
+## 🌟 Core Features
 
-- **安全注册与认证**: 采用 RSA 密钥对生成机制。用户注册时自动生成公私钥对，公钥用于加密资产，私钥用于解密。
+- **Secure Authentication**: Registration automatically generates an RSA key pair (public/private). Public keys are used for encryption, while private keys are used for secure decryption.
-- **数字资产加密存储**: 用户可以上传资产，系统使用用户的公钥对资产内容进行加密存储。
+- **Encrypted Asset Storage**: Users can upload assets that are encrypted using their unique public key before storage.
-- **遗产指定**: 用户可以为每个资产指定一名继承人（Heir）。
+- **Legacy Designation**: Users can assign specific heirs (via email) to each of their digital assets.
-- **吊唁/状态确认**: 系统管理员有权标记用户为“已故”（guale）。
+- **Status Monitoring**: Administrators can officially declare a user as "deceased" (`guale`), triggering the inheritance process.
-- **遗产申领**: 
+- **Inheritance Claiming**:
-    - 只有被确认标记为“已故”的用户，其指定的继承人才能申领资产。
+    - Designated heirs can claim assets only after the owner's status is verified.
-    - 申领过程中，系统利用已故用户的私钥解密内容并安全交付给继承人。
+    - The system securely decrypts the content using the deceased user's private key for the authorized heir.
-- **密钥分片 (Sharding)**: 支持私钥分片存储逻辑，增强安全性。
+- **AI Proxy Service**: A built-in proxy for interacting with AI models with role-based configurations and weekly quota/token management.
+- **Subscription Tiers**: Multi-tier subscription system (Free, Pro, etc.) controlling limits on heirs, AI usage, and more.
+- **Last Active Tracking**: Automatically tracks user activity to help monitor status.
 
-## 🛠 技术栈
+## 🛠 Technology Stack
 
-- **框架**: [FastAPI](https://fastapi.tiangolo.com/)
+- **Framework**: [FastAPI](https://fastapi.tiangolo.com/)
-- **数据库**: [PostgreSQL](https://www.postgresql.org/) (通过 `asyncpg` 异步驱动)
+- **Database**: [PostgreSQL](https://www.postgresql.org/) (via `asyncpg` async driver)
 - **ORM**: [SQLAlchemy 2.0](https://www.sqlalchemy.org/) (AsyncIO)
-- **加密**: [Cryptography](https://cryptography.io/) & [PyCryptodome](https://pycryptodome.org/) (RSA 加密)
+- **Encryption**: [Cryptography](https://cryptography.io/) & [PyCryptodome](https://pycryptodome.org/) (RSA Encryption)
-- **权限**: [python-jose](https://github.com/mpdavis/python-jose) (JWT Token)
+- **Authentication**: [python-jose](https://github.com/mpdavis/python-jose) (JWT Tokens) & Passlib (Bcrypt/Argon2)
+- **Request Client**: [HTTPX](https://www.python-httpx.org/) (for AI Proxy)
 
-## 🚀 快速开始
+## 🚀 Getting Started
 
-### 1. 使用 Docker Compose 启动 (推荐)
+### 1. Using Docker Compose (Recommended)
 
-这是最快的方式，会自动配置数据库和应用环境。
+This is the fastest way to get the system running with a pre-configured database.
 
 ```bash
 docker-compose up --build
 ```
-简单测试：
+
+- **API Documentation**: `http://localhost:8000/docs`
+- **Default Admin**: `admin` / `admin123`
+
+### 🧪 Running Tests
+
+Once the service is up, you can run the automated test scenario:
 ```bash
 python3 test/test_scenario.py
 ```
 
-- 接口文档: `http://localhost:8000/docs`
+### 2. Local Manual Setup
-- 管理员默认账号: `admin` / `admin123`
 
-### 2. 本地手动启动
+1. **Environment Setup**:
-
-1. **安装环境**:
    ```bash
    python -m venv venv
    source venv/bin/activate  # Linux/macOS
+   # or venv\Scripts\activate on Windows
    pip install -r requirements.txt
    ```
 
-2. **配置环境变量**:
+2. **Configuration**:
-   创建一个 `.env` 文件或设置环境变量 `DATABASE_URL`。默认为：
+   Create a `.env` file or set the `DATABASE_URL` environment variable. Default:
    `postgresql+asyncpg://user:password@localhost:5432/fastapi_db`
 
-3. **初始化数据库**:
+3. **Database Initialization**:
    ```bash
    python reset_db.py
    ```
 
-4. **运行服务**:
+4. **Run Service**:
    ```bash
    uvicorn app.main:app --reload
    ```
 
-## 📖 API 概览
+## 📖 API Overview
 
-### 用户接口
+### User & Auth
-- `POST /register`: 用户注册，自动生成 RSA 密钥对。
+- `POST /register`: Register and generate RSA keys.
-- `POST /token`: 登录获取 JWT Access Token。
+- `POST /login`: Login and receive JWT access token.
+- `GET /users/search`: Search for users by username or email.
 
-### 资产接口
+### Asset Management
-- `POST /assets/`: 创建加密资产（上传者自动加密）。
+- `GET /assets/get`: Retrieve assets owned by the current user.
-- `POST /assets/assign`: 为资产指定继承人。
+- `POST /assets/create`: Create a new encrypted asset.
-- `POST /assets/claim`: 继承人申领资产（需原所有人状态为 `guale`）。
+- `POST /assets/assign`: Assign or unassign an heir to an asset.
+- `POST /assets/delete`: Remove an asset.
+- `GET /assets/designated`: List assets where the user is the designated heir.
 
-### 管理员接口
+### Inheritance
-- `POST /admin/declare-guale`: 管理员宣告用户“已故”。
+- `POST /assets/claim`: Claim an asset (requires owner to be marked as deceased).
 
-## 🔒 安全设计
+### AI & Roles
+- `POST /ai/proxy`: Proxy requests to external AI providers with quota tracking.
+- `GET /get_ai_roles`: Retrieve available AI personas/roles.
 
-1. **端到端思想**: 资产在存储前使用 RSA 公钥加密。
+### Admin
-2. **状态验证**: 申领逻辑严格校验 `heir_id` 以及 `author.guale` 状态。
+- `POST /admin/declare-guale`: (Admin Only) Declare a user as deceased.
-3. **密钥管理**: 本项目目前为了演示方便在数据库中存储了私钥，在生产环境下建议配合 KMS 或硬件安全模块使用。
 
-## 📜 许可证
+## 🔒 Security Design
+
+1. **End-to-End Principles**: Sensitive assets are encrypted before storage.
+2. **State Verification**: Claim logic strictly validates the `heir_id` and the `deceased` status of the owner.
+3. **Key Management**: For demonstration, private keys are stored in the database. In a production environment, integration with a KMS (Key Management Service) or HSM (Hardware Security Module) is highly recommended.
+
+## 📜 License
 
 MIT License