УТВЕРЖДЁН УЖАС.00001-01 33 01-ЛУ ПРОГРАММНЫЕ СРЕДСТВА СЕРВИС «УМНЫЕ ЗНАКОМСТВА» И КЛИЕНТЫ СЕРВИСА Руководство программиста УЖАС.00001-01 33 01 Листов 16 2010 2 УЖАС.00001-01 33 01 АННОТАЦИЯ Настоящий документ предназначен для программистов и системных администраторов, обслуживающих программу УЖАС.00001-01 «Программные средства сервис «Умные знакомства» и клиенты сервиса». В документе содержатся сведения о назначении и условиях применения программы, процедуры инсталляции и начальной настройки серверной части и клиентских частей, а также общие сведения о структуре программных средств, входные и выходные данные программы. Приводятся сообщения, выдаваемые в ходе работы программы. Документ соответствует изданию (версии) 0.6 программы УЖАС.00001-01. 3 УЖАС.00001-01 33 01 СОДЕРЖАНИЕ 1. Назначение и условия применения программных средств ................................................ 4 1.1. Назначение программных средств .................................................................................... 4 1.2. Функции, выполняемые программными средствами ...................................................... 4 1.3. Состав аппаратных средств ................................................................................................ 4 1.4. Состав общесистемного программного обеспечения ...................................................... 4 2. Характеристики программных средств ................................................................................ 6 2.1. Выбор архитектуры программного комплекса ................................................................ 6 2.2. Основные классы системы ................................................................................................. 6 3. Обращение к программным средствам ................................................................................ 8 3.1. Установка программных средств....................................................................................... 8 3.2. Запуск программных средств ............................................................................................. 8 3.3. Удаление программных средств ........................................................................................ 8 4. Описание алгоритмов функциональных задач ............................................................ 9 5. Входные и выходные данные .............................................................................................. 12 6. Сообщения ............................................................................................................................ 14 Перечень сокращений .............................................................................................................. 15 4 УЖАС.00001-01 33 01 1. НАЗНАЧЕНИЕ И УСЛОВИЯ ПРИМЕНЕНИЯ ПРОГРАММНЫХ СРЕДСТВ 1.1. Назначение программных средств Программные средства (ПС) сервис «Умные знакомства» и клиенты сервиса представляют собой компоненты службы интернет-знакомств, основанной на отслеживании географического положения пользователей. 1.2. Функции, выполняемые программными средствами Программные средства сервис «Умные знакомства» и клиенты сервиса должны выполнять следующие функции: – согласование сеансового ключа симметричного шифрования конфиденциальных данных («обмен ключами»); – регистрация и удаление зарегистрированного пользователя; – вход в службу знакомств и выход из нее зарегистрированного пользователя; – определение и задание текущего местоположения пользователя; – ввод и просмотр сведений персональной анкеты пользователя, включая паспортные данные (фамилия, имя, пол, дата рождения), личные данные (интересы, цель знакомства и т.д.), физические параметры (рост, вес и т.д.), фотографию; – поиск по анкетам с сортировкой результатов по географической близости к пользователю, осуществляющему запрос; – отправка и получение персональных сообщений найденным пользователям и пользователям, которым сообщения отправлялись ранее; – поиск и оповещение с помощью СМС-сообщений клиентов, находящихся в радиусе непосредственной близости от пользователя, где радиус непосредственной близости равен 1 (одному) километру. 1.3. Состав аппаратных средств Минимальная конфигурация аппаратных средств для машин, на которых выполняется сервис, должна позволять запуск серверных приложений на базе Microsoft ASP.NET 4.0 и работу СУБД Microsoft SQL Server 2008. Минимальная конфигурация аппаратных средств для веб-клиента должна позволять запуск любого из современных веб-браузеров (Firefox 4.0, Opera 11, Internet Explorer 9) и обеспечивать доступ в интернет. Минимальная конфигурация аппаратных средств для мобильного клиента должна позволять запуск Java-приложений, соответствующих профилю устройства CLDC 1.1 и упакованных в соответствии со спецификацией MIDP 2.0. При этом для корректного функционирования мобильного клиента абсолютно необходимо наличие периферийного устройства — GPS-сенсора, снабженного программным интерфейсом, совместимым с JSR-00179 «Location API for J2ME». 1.4. Состав общесистемного программного обеспечения Для обеспечения функционирования ПС должны быть установлены и настроены: – для сервиса — серверная версия ОС Microsoft Windows 2003 R2, не ниже; Microsoft .NET Framework 4.0 Client Profile и Extended Profile, не ниже; Microsoft ASP.NET 4.0, не ниже; – для веб-клиента — любая ОС, поддерживающая один из указанных браузеров: Firefox 4.0, Opera 11, Internet Explorer 9; – для мобильного клиента — рекомендуется ОС Symbian S60 5th Edition (или выше), либо эмулятор мобильного устройства на базе указанной ОС; однако допустима любая мобильная ОС, имеющая J2ME с профилем CLDC 1.1, поддержкой MIDP 2.0 и JSR-00179. 5 УЖАС.00001-01 33 01 Для корректной работы сервиса необходимо правильно указать строку подключения к базе данных в файле конфигурации Web.config сервиса (XPath configuration/connectionStrings/add[name="Entities"]). Для руководства по строкам подключения следует обратиться к локальной справке СУБД Microsoft SQL Server 2008. Для корректной работы веб-клиента необходимо обеспечить доступность сервиса по адресу http://localhost:61673/ServicePrototype.svc. Для корректной работы мобильного клиента необходимо обеспечить доступность сервиса по произвольному адресу и соответствие настроек мобильного клиента этому адресу. 6 УЖАС.00001-01 33 01 2. ХАРАКТЕРИСТИКИ ПРОГРАММНЫХ СРЕДСТВ При разработке ПС использовались языки C# и Java, платформы ASP.NET 4.0 и J2ME, ORM Entity Framework 4.0. 2.1. Выбор архитектуры программного комплекса ПC сервиса «Умные знакомства» и клиентов сервиса использует следующую архитектуру (см. рис. 2.1): – Клиенты сервиса связываются с сервисом по протоколу HTTP и передают сообщения в формате SOAP. – Сервис связывается через прослойку объектно-реляционного отображения (ORM) Entity Framework с СУБД Microsoft SQL Server по протоколу TDF (Tabular Data Format). СУБД SQL Server Рис. 2.1 2.2. Основные классы системы Основные классы ПС: 1) интерфейс контракта сервиса и его реализации: – IServicePrototype — контракт сервиса; – ServicePrototype — серверная реализация контракта; – SmartDatingClient — клиентская реализация контракта (stub). 2) основные компоненты веб-клиента: – BasePage – базовый класс всех страниц веб-клиента, предоставляющий доступ к клиенту сервиса (объекту класса SmartDatingClient), а также информации о текущем ключе шифрования (свойства SessionKey и SessionKeyHash); – SiteMaster – класс-шаблон, предоставляющий основу разметки для всех страниц веб-клиента; – CryptoImpl — реализация криптографических процедур, требуемых для работы с сервисом. 7 УЖАС.00001-01 33 01 3) основные компоненты мобильного клиента: – ClientMIDlet — MIDlet клиента, содержащий описание пользовательского интерфейса (компоненты интерфейса, последовательность страниц интерфейса); – SetLocationThread — класс потока, периодически обновляющего текущее местоположение пользователя по данным GPS-датчика; – CryptoImpl — реализация криптографических процедур, требуемых для работы с сервисом. 4) сгенерированные прокси-классы доступа к сервису (в случае ASP.NET — класс SmartDatingClient, в случае J2ME — набор классов в пакете ru.zombator.services.smartdating. 8 УЖАС.00001-01 33 01 3. ОБРАЩЕНИЕ К ПРОГРАММНЫМ СРЕДСТВАМ 3.1. Установка программных средств Для установки ПС необходимо выполнить следующие действия: Установка сервиса 1) зарегистрироваться в системе под учетной записью администратора; 2) извлечь из репозитория папку ST-Prototype/SmartDatingService, поместить ее в нужное место иерархии папок веб-сервера (IIS или Cassini); 3) в случае использования Cassini — запустить Cassini командой WebDev.WebServer40.exe /port:61673 /path:"<путь к папке SmartDatingService>" 4) в случае использования IIS — создать в папке SmartDatingService приложение (Application) и удостовериться, что используетcя пул ASP.NET 4.0; 5) проверить работу сервиса, введя в браузере адрес сервиса. Должна появиться страница «SmartDatingService Service», сообщающая метаданные сервиса. Установка веб-клиента 1) зарегистрироваться в системе под учетной записью администратора; 2) извлечь из репозитория папку ST-Prototype/ClientProto/WebUI, поместить ее в нужное место иерархии папок веб-сервера (IIS или Cassini); 3) в случае использования Cassini — запустить Cassini командой WebDev.WebServer40.exe /port:8080 /path:"<путь к папке WebUI>" 4) в случае использования IIS — создать в папке WebUI приложение (Application) и удостовериться, что используетcя пул ASP.NET 4.0; 5) проверить работу веб-клиента, введя в браузере адрес веб-клиента. Должна появиться страница «Добро пожаловать --- Smart Dating». Установка мобильного клиента 1) извлечь из репозитория папку ST-Prototype/ClientProto/Client/Last Release, поместить ее содержимое на карту памяти или во внутреннюю память мобильного устройства; 2) открыть папку Last Release в диспетчере файлов устройства, щелкнуть по файлу Client.jad для установки; 3) подтвердить установку, несмотря на отсутствие цифровой подписи; 4) по окончании установки в меню «Приложения» (Applications) щелкнуть по ярлыку «ClientForServise» для запуска клиента; 5) если клиент установлен успешно, на экране появится страница «Мобильный клиент». 3.2. Запуск программных средств Запуск сервиса происходит автоматически в случае использования IIS, вручную в случае использования сервера Cassini. Запуск веб-клиента при использовании IIS производится автоматически, при использовании Cassini — производится вручную с помощью файла start.bat в папке WebUI. Запуск мобильного клиента осуществляется из меню «Приложения» (или аналогичного), имя приложения «ClientForServise». 3.3. Удаление программных средств Для удаления сервиса и веб-клиента необходимо, зайдя в систему с правами администратора, удалить папки SmartDatingService и WebUI соответственно. Для удаления мобильного клиента следует воспользоваться средством деинсталляции, предлагаемым ОС мобильного устройства для удаления J2ME-приложений, и удалить приложение «ClientForServise 1.0». 9 УЖАС.00001-01 33 01 4. ОПИСАНИЕ АЛГОРИТМОВ ФУНКЦИОНАЛЬНЫХ ЗАДАЧ В данном разделе кратко описываются алгоритмы, реализуемые в сервисе, к которым получают доступ веб-клиент и мобильный клиент. П р и м е ч а н и е. При описании алгоритмов (всех кроме согласования ключа) многократно повторяемые шаги «проверка правильности хеш-значения сеансового ключа, определение имени и идентификатора пользователя по сеансовому ключу» подразумеваются, но не описываются в силу их очевидности. 4.1. Согласование сеансового ключа симметричного шифрования конфиденциальных данных («обмен ключами») 1) генерация криптографически случайного ключа длиной 256 бит клиентом; 2) упаковка сгенерированного ключа в сообщение «Key Exchange» PKCS1.5, заполнение типа «2» (случайные данные); 3) передача сообщения сервису, вместе с e-mail пользователя (если обмен ключами осуществляется для создания нового пользователя, вместо e-mail ставится «*») 4) расшифровка сообщения «Key Exchange» на стороне сервиса, запоминание ключа сеанса, SHA1-хеша ключа сеанса и e-mail пользователя, осуществившего обмен ключами 4.2. Регистрация и удаление зарегистрированного пользователя Регистрация: 1) проверка пользователя по базе (нет ли?); 2) расшифрование пароля пользователя ключом сеанса; 3) сохранение SHA1-хеша пароля пользователя в базе в таблице Membership; Удаление: 1) проверка пользователя по базе (есть ли?); 2) удаление пользователя из таблицы Membership (по выявленному по SHA1-хешу ключа сеанса идентификатору пользователя). 4.2. Вход в службу знакомств и выход из нее зарегистрированного пользователя Вход: 1) проверка пользователя по базе (есть ли?); 2) расшифрование пароля пользователя ключом сеанса; 3) проверка SHA1-хеша расшифрованного пароля на соответствие хешу, сохраненному в базе в таблице Membership для данного пользователя; 4) пометка «пользователь с данным ключом сеанса аутентифицирован». Выход: 1) проверка, аутентифицирован ли пользователь с данным ключом сеанса; 2) удаление пометки об аутентификации; 3) удаление пометки о прохождении обмена ключами, ключ сеанса теперь недействителен. 4.3. Определение и задание текущего местоположения пользователя Определение: 1) проверка пользователя по базе (есть ли?); 2) получение полей latitude и longitude из базы из таблицы Location для данного ид пользователя Задание: 1) проверка пользователя по базе (есть ли?); 2) установка полей latitude и longitude в базе в таблице Location для данного ид пользователя 3) в поле date_changed («момент обновления местоположения») устанавливается текущий момент времени 10 УЖАС.00001-01 33 01 4.4. Ввод и просмотр сведений персональной анкеты пользователя, включая паспортные данные (фамилия, имя, пол, дата рождения), личные данные (интересы, цель знакомства и т.д.), физические параметры (рост, вес и т.д.), фотографию Просмотр: 1) проверка пользователя по базе (есть ли?); 2) получение данных из таблицы PersonalData для данного ид пользователя в структуру PersonalData; 3) формирование xml-представления указанной структуры, вида <pd> <имя_поля_базы_данных> значение_поля_если_не_null </имя_поля_базы_данных> </pd> 4) зашифрование полученного представления ключом сеанса Ввод: 1) проверка пользователя по базе (есть ли?); 2) расшифрование xml-представления структуры PersonalData ключом сеанса; 3) заполнение полей структуры PersonalData в соответствии с xml-представлением; 4) обновление (если запись уже есть) или добавление записи в таблицу PersonalData со значениями полей, соответствующими полям структуры PersonalData 4.5. Поиск по анкетам с сортировкой результатов по географической близости к пользователю, осуществляющему запрос 1) создание объекта «запрос поиска»; 2) добавление к созданному объекту критериев поиска (вида «имя_параметра {= | >= | like} значение), расшифровываемых ключом сеанса; 3) выполнение запроса согласно заданному объекту «запрос поиска» (критерии объединяются ключевым словом and); 4) получение результатов как списка результатов поиска (результат поиска — структура PersonalData и два поля: latitude (широта), longitude (долгота); 5) вычисление для каждого из результатов расстояния между текущим пользователем и пользователем, чьи данные указаны в результате поиска; 6) сортировка по расстоянию до текущего пользователя, по возрастанию; 7) удаление объекта «запрос поиска». 4.6. Отправка и получение персональных сообщений найденным пользователям и пользователям, которым сообщения отправлялись ранее Отправка: 1) проверка пользователя по базе (есть ли?); 2) проверка получателя по базе (есть ли?); 3) расшифрование тела и заголовка сообщения ключом сеанса; 4) сохранение сообщения в таблице Msgs в двух экземплярах: в почтовом ящике отправителя (msgbox_id=ид текущего пользователя, folder=2) и почтовом ящике получателя (msgbox_id=ид_получателя, folder=0). Получение: 1) проверка пользователя по базе (есть ли?); 2) получение всех сообщений в заданной папке (либо folder=0 «входящие», либо folder=2 «отправленные») для заданного ид пользователя по таблице Msgs; результат возвращается массивом элементов типа Msg (сообщение) 11 УЖАС.00001-01 33 01 4.7. Поиск и оповещение с помощью СМС-сообщений клиентов, находящихся в радиусе непосредственной близости от пользователя, где радиус непосредственной близости равен 1 (одному) километру Поиск: 1) проверка пользователя по базе (нет ли?); 2) просмотр всех записей в таблице Location, для которых ид не равен ид текущего пользователя; 3) для найденных записей — определение расстояния до текущего пользователя аналогично п. 4.5; 4) фильтрация записей по признаку «расстояние <= 1000» (расстояние вычисляется в метрах). Оповещение: Для каждого результата поиска, если заполнено поле phone_number структуры PersonalData, извлечь телефон, удалить ведущий знак «+» (если имеется), и выполнить методы Authenticate и SubmitSm сервиса SmsHostService (sms-host.ru), указав параметры аккаунта sms-host.ru в первом случае и номер, время доставки сообщения и его текст — во втором. Текст сообщения может содержать последовательность символов «[]», перед отправкой она заменяется на «<имя_пользователя> <фамилия_пользователя>». 12 УЖАС.00001-01 33 01 5. ВХОДНЫЕ И ВЫХОДНЫЕ ДАННЫЕ П р и м е ч а н и я. Везде, где на вход требуется подавать последовательности байт (например, криптографические ключи), на вход подаются base64-закодированные строки, представляющие указанные последовательности. 5.1. Согласование сеансового ключа симметричного шифрования конфиденциальных данных («обмен ключами») ВХОД: 1) e-mail пользователя (если обмен ключами осуществляется для создания нового пользователя, вместо e-mail ставится «*») 2) байты сообщения «Key Exchange» PKCS1.5 (тип заполнения =2, случайные данные) ВЫХОД: статус обмена ключами 5.2. Регистрация и удаление зарегистрированного пользователя Регистрация ВХОД: 1) e-mail пользователя 2) зашифрованный ключом сеанса пароль ВЫХОД: статус регистрации Удаление ВХОД SHA1-хеш ключа сеанса ВЫХОД результат удаления 5.3. Вход в службу знакомств и выход из нее зарегистрированного пользователя Вход ВХОД 1) e-mail пользователя 2) зашифрованный ключом сеанса пароль ВЫХОД статус входа Выход ВХОД SHA1-хеш ключа сеанса; ВЫХОД статус выхода 5.4. Определение и задание текущего местоположения пользователя Определение ВХОД SHA1-хеш ключа сеанса ВЫХОД пара значений (широта; долгота) Задание ВХОД SHA1-хеш ключа сеанса, широта, долгота ВЫХОД статус задания 13 УЖАС.00001-01 33 01 5.5. Ввод и просмотр сведений персональной анкеты пользователя, включая паспортные данные (фамилия, имя, пол, дата рождения), личные данные (интересы, цель знакомства и т.д.), физические параметры (рост, вес и т.д.), фотографию Просмотр ВХОД: SHA1-хеш ключа сеанса ВЫХОД: зашифрованное xml-представление структуры PersonalData (см. 4.5) Ввод ВХОД: SHA1-хеш ключа сеанса, зашифрованное xml-представление структуры PersonalData (см. 4.5) ВЫХОД: результат задания персональных данных 5.6. Поиск по анкетам с сортировкой результатов по географической близости к пользователю, осуществляющему запрос ВХОД: SHA1-хеш ключа сеанса; набор критериев поиска ВЫХОД: набор результатов поиска 5.7. Отправка и получение персональных сообщений найденным пользователям и пользователям, которым сообщения отправлялись ранее Отправка ВХОД: SHA1-хеш ключа сеанса; ид пользователя-получателя; зашифрованные ключом сеанса заголовок и текст письма ВЫХОД: результат отправки Получение ВХОД: SHA1-хеш ключа сеанса; папка, в которой показываем сообщения (либо folder=0 «входящие», либо folder=2 «отправленные») ВЫХОД: набор сообщений (данных типа Msg) 5.8. Поиск и оповещение с помощью СМС-сообщений клиентов, находящихся в радиусе непосредственной близости от пользователя, где радиус непосредственной близости равен 1 (одному) километру ВХОД: SHA1-хеш ключа сеанса; текст сообщения для оповещения ВЫХОД: результат оповещения 14 УЖАС.00001-01 33 01 6. СООБЩЕНИЯ При работе ПC могут выдаваться следующие виды сообщений об ошибках и предупреждений (табл. 1). Таблица 1 Сообщение "Операция завершена неудачно." /* Failure */, Возможная причина Неполадки с базой данных. Ошибка в сервисе. "Введен неверный адрес электронной почты или Ошибка в адресе или пароле: такого пользопароль." /* InvalidEmail */,/* вателя в базе нет InvalidEmailOrPassword */ Ошибка в клиенте. Попробуйте еще раз. "Ошибка связи: неправильный ключ сессии. Попробуйте чуть позже." /* InvalidSessionKey */, "Эта операция доступна только для пользовате- Не выполнен вход в сервис лей, вошедших в службу." /* NotAuthenticated */, "Пользователь с таким адресом почты уже зарегистрирован. Выберите другой адрес." /* AccountAlreadyExists */, "Личная анкета еще не заполнена." /* NoPersonalData */, "Местоположение неизвестно." /* NoLocation */, "Такого пользователя-получателя не существует." /* NoRecipient */, "Сообщение не найдено." /* MessageNotFound */, "Невозможно переместить сообщения в эту папку." /* IllegalDestination */, Пользователь с таким адресом в базе уже есть Анкета еще не заполнена, поэтому данные получить нельзя Участник еще не указал свое местоположение Указан несуществующий адресат сообщения, возможно, пользователь удалил себя Сообщения с указанным идентификатором в данном почтовом ящике нет Перемещение сообщений не реализовано (нет смысла перемещать из «Входящих» в «Отправленные» или наоборот) Проблема в клиенте "Ошибка поиска: неправильный дескриптор. Попробуйте чуть позже." /* InvalidSearchDescriptor */, "Попытка повторно добавить уже имеющийся Проблема в клиенте критерий поиска." /* DuplicateSearchCriteria */, "Критерий поиска не обнаружен." /* SearchCriteriaNotFound */, "Не задано ни одного критерия поиска. Поиск невозможен." /* NoCriteriasDefined */, "Не найдено участников, удовлетворяющих заданным критериям. Попробуйте обобщить запрос." /* NoMembersFound */, "Неизвестный критерий поиска." /* UnknownSearchCriteria */}; Проблема в клиенте Не указано ни одного критерия, результат будет слишком общим, поэтому не ищем Критериев слишком много и/или они слишком строгие Проблема в клиенте. Указан недопустимый критерий поиска 15 УЖАС.00001-01 33 01 ПЕРЕЧЕНЬ СОКРАЩЕНИЙ БД ОС ПС – база данных; – операционная система; – программное средство 16 УЖАС.00001-01 33 01 Лист регистрации изменений Номера листов (страниц) Изм. изме- замененненных ных новых Всего № Входящий листов документа № сопровоаннули(страдительного рованниц) в документа и ных докумендата те Подпись (фамилия) Дата